bigpowers 2.87.0 → 2.87.2

package/README.md

@@ -43,15 +43,17 @@ After installing, ask your agent to run the `using-bigpowers` skill — it is th
 
 ```bash
 # Global install (no lifecycle scripts — npm v10+ safe)
-npm install -g bigpowers
+npm install -g bigpowers@latest
 bigpowers setup     # runs sync + install, links skills to your tools
 
-# Or one-shot with npx
-npx bigpowers setup
+# Or one-shot with npx (always fetches the newest release)
+npx bigpowers@latest setup
 ```
 
 Both commands sync skill artifacts and link them to Claude Code, Gemini CLI, and Cursor (see [Prerequisites](#-prerequisites)).
 
+> **Always pin `@latest`.** With bigpowers already installed globally, a bare `npx bigpowers setup` reuses the stale global binary and `npm update -g bigpowers` doesn't reliably cross to the newest release. `npm install -g bigpowers@latest` and `npx bigpowers@latest setup` force a registry fetch every time.
+
 ### Interactive Installer
 
 The `npx bigpowers setup` command launches an interactive menu where you can:
@@ -269,10 +271,11 @@ Or add manually to `.claude/settings.json`:
 **npm install:**
 
 ```bash
-npm update -g bigpowers
-bigpowers update   # re-sync and refresh symlinks
+bigpowers update   # fetches bigpowers@latest (global installs), then re-syncs + refreshes symlinks
 ```
 
+`bigpowers update` now runs `npm install -g bigpowers@latest` for you when bigpowers is installed globally, so running it alone is enough to reach the newest release. Prefer to do it by hand? `npm install -g bigpowers@latest && bigpowers update`. (Avoid `npm update -g bigpowers` — it does not reliably cross to `@latest`.)
+
 **git clone:**
 
 ```bash
@@ -301,9 +304,9 @@ bash scripts/install.sh --uninstall
 ### Reinstall
 
 ```bash
-npx bigpowers setup
+npx bigpowers@latest setup
 # or, if installed globally:
-bigpowers setup
+bigpowers update
 ```
 
 ---

package/VALIDACAO_CONTRA_GSD.md

@@ -0,0 +1,321 @@
+# Validação Cruzada: Bigpowers vs. GSD (Get Shit Done)
+
+**Data:** 2026-05-18  
+**Scope:** Comparar consolidação proposta com arquitetura de artefatos de GSD
+
+---
+
+## 1. Comparação de Estrutura
+
+### GSD (Get Shit Done)
+```
+.planning/
+├── PROJECT.md       ← Contexto do projeto (validado vs. em escopo)
+├── ROADMAP.md       ← Fases + plans + success criteria
+├── STATE.md         ← Estado atual (< 100 linhas)
+├── {phase}-{plan}-PLAN.md    ← Planos individuais
+└── todos/pending/            ← Ideias capturadas
+
+templates/             ← 30+ templates
+references/            ← 60+ docs de referência técnica
+workflows/             ← 93+ workflows (comandos CLI)
+```
+
+### Bigpowers (Proposta de Consolidação)
+```
+specs/
+├── STATE.md              ← Estado atual (59 linhas) ✅
+├── RELEASE-PLAN.md       ← Roadmap vivo ✅
+├── PLAN-v*.md            ← Histórico → archive/ ✅
+├── archive/releases/     ← Novo: histórico consolidado
+├── CONTEXT.md, UBIQUITOUS_LANGUAGE.md, etc.
+└── ...
+
+SKILL-INDEX.md           ← Novo: tabela canônica
+README.md                ← Simplificado
+CONVENTIONS.md           ← Existente
+```
+
+---
+
+## 2. Gap Analysis: O Que Falta em Bigpowers
+
+### 2.1 Falta: PROJECT.md (Contexto do Projeto)
+
+**GSD tem:**
+```markdown
+# PROJECT.md
+
+## What This Is
+[Descrição atual do projeto]
+
+## Core Value
+[Uma coisa que importa mais]
+
+## Requirements
+- Validated (já enviado, comprovado)
+- Active (em construção)
+- Out of Scope (com razão do exclusão)
+
+## Context
+[Background técnico e de usuário]
+
+## Constraints
+[Limitações: stack, timeline, etc.]
+
+## Key Decisions
+[Histórico de decisões significativas]
+```
+
+**Bigpowers não tem equivalente.** Tem CLAUDE.md (comandos, stack, arquitetura), mas não tem:
+- ❌ Requisitos (Validated/Active/Out of Scope)
+- ❌ Core Value (a uma coisa que importa)
+- ❌ Decisões significativas rastreadas
+- ❌ Constraints formalizadas
+
+**Recomendação:** Criar `specs/PROJECT.md` para bigpowers com:
+- What This Is: "38 agent skills for spec-driven TDD by solo developers"
+- Core Value: "Maintain quality (audit score) while scaling skill count"
+- Active Requirements: Feature completeness, testing mandates, etc.
+- Out of Scope: Domain-specific skills (scaffold-exercises), plugins, marketplace
+- Key Decisions: verb-noun naming, local-first (sem GitHub issues), BMAD phases, etc.
+
+---
+
+### 2.2 ROADMAP.md vs. RELEASE-PLAN.md
+
+**GSD usa ROADMAP.md:**
+- Fases numeradas (1, 2, 3, ...)
+- Decimal phases para inserts (2.1 = "critical fix inserted between 2 and 3")
+- Success Criteria (observable behaviors)
+- Plans count per phase
+- Progress table com milestone column
+
+**Bigpowers usa RELEASE-PLAN.md:**
+- Releases (v1.11, v1.12, ...)
+- WSJF scoring
+- Status (✅, ⏳)
+- Focus area (Benchmarks, Auditor, Karpathy, etc.)
+- Detailed action items per release
+
+**Análise:**
+- ✅ RELEASE-PLAN.md é mais rico que ROADMAP (tem WSJF, status, detalhes)
+- ✅ Ambas rastreiam progresso
+- ⚠️ Bigpowers não tem "Success Criteria" formalizados (deveriam estar em STATE ou PROJECT)
+
+**Recomendação:** Manter RELEASE-PLAN.md, mas adicionar "Success Criteria" por release:
+```markdown
+### v1.17.0 — Guardrails (WSJF 3.2) ⏳
+
+**Success Criteria:**
+- [ ] "Zoom-out mandate" implemented in plan-work as HARD-GATE
+- [ ] Surgical changes checklist in audit-code passes 100% of tests
+- [ ] CONVENTIONS.md explicitly forbids "touch unrelated code"
+```
+
+---
+
+### 2.3 Artefatos Intermediários (Templates)
+
+**GSD tem 30+ templates:**
+- AI-SPEC.md, DEBUG.md, VALIDATION.md
+- discovery.md, research.md, spec.md
+- planner-subagent-prompt.md
+- continue-here.md
+
+**Bigpowers tem:**
+- Implícitos em cada skill (não há templates separados)
+- Rely em CONVENTIONS.md
+
+**Recomendação:** Criar `templates/` subdir em bigpowers:
+```
+templates/
+├── spec.md              (→ specs/PLAN.md output format)
+├── phase-discussion.md  (→ output de elaborate-spec)
+├── diagnosis.md         (→ output de investigate-bug)
+└── ...
+```
+
+---
+
+### 2.4 Referências Técnicas (References)
+
+**GSD tem 60+ references:**
+- gates.md (quais gates bloquear, quais permitir)
+- planner-antipatterns.md (o que não fazer)
+- verification-patterns.md (como testar)
+- thinking-models-*.md (modelos de pensamento por agente)
+- tdd.md, executor-examples.md
+
+**Bigpowers tem:**
+- AUDIT.md (auditoria de cobertura de Clean Code)
+- COMPARISON.md (comparação com superpowers, BMAD, etc.)
+- Skills source em SKILL.md (inline docs)
+
+**Recomendação:** Segregar em `references/`:
+```
+references/
+├── clean-code-mapping.md     (como cada skill implementa Clean Code)
+├── gates-and-guardrails.md   (HARD-GATEs em cada skill)
+├── skill-antipatterns.md     (o que não fazer em cada skill)
+├── bmad-lifecycle.md         (phases BMAD detalhadas)
+└── ...
+```
+
+---
+
+## 3. Validação: Minha Proposta vs. GSD
+
+### O Que Está Certo em Minha Proposta
+
+✅ **Hierarquia de artefatos**
+- STATE → RELEASE-PLAN → SKILL-INDEX → README
+- GSD faz: PROJECT → ROADMAP → STATE → PLAN
+- Abordagens equivalentes, estilos diferentes
+
+✅ **Consolidação de redundância**
+- Deletar PLAN.md (stale) ← mesma que GSD faria
+- Arquivar PLAN-v*.md ← GSD collapsa em `<details>` tags
+- Single skill index ← GSD não tem equivalent, é um win para bigpowers
+
+✅ **Nomes simples (verb-noun)**
+- Bigpowers: `develop-tdd`, `validate-fix`, etc.
+- GSD: `/gsd-new-project`, `/gsd-plan-phase`, etc. (verb-noun style)
+- ✓ Bigpowers está bem aqui
+
+✅ **Clareza de fases (BMAD)**
+- Bigpowers: Discover → Elaborate → Plan → Build → Sustain
+- GSD: Phase 1, 2, 3, ... (fases numeradas)
+- Ambas funcionam; BMAD é mais descritivo
+
+### O Que Está Incompleto em Minha Proposta
+
+❌ **Falta PROJECT.md**
+- GSD começa aqui: "What This Is", "Core Value", "Requirements"
+- Bigpowers tem CLAUDE.md, mas não `specs/PROJECT.md`
+- **Ação:** Adicionar PROJECT.md como canônico de contexto do projeto
+
+❌ **Falta Success Criteria formalizados**
+- GSD em ROADMAP: "Observable behaviors that must be TRUE"
+- Bigpowers em RELEASE-PLAN: Apenas "Focus Area" e "Objective"
+- **Ação:** Adicionar Success Criteria por release em RELEASE-PLAN.md
+
+❌ **Falta templates/ e references/**
+- GSD segrega templates (30+) e references (60+)
+- Bigpowers tem tudo inline em SKILL.md
+- **Ação:** Opcional; se fizer, criar `templates/` e `references/` como em GSD
+
+❌ **Falta "Skill Antipatterns" ou "Gates"**
+- GSD tem gates.md (quais gates bloquear)
+- Bigpowers tem mandates em prose, não formalizados
+- **Ação:** Criar `references/gates-and-guardrails.md`
+
+---
+
+## 4. Recomendação: Incorporar Melhores Práticas de GSD
+
+### Fase 1: Imediato (Incorporar em Análise/SKILL-INDEX)
+
+- [ ] Criar `specs/PROJECT.md` com:
+  - What This Is
+  - Core Value
+  - Active Requirements
+  - Out of Scope
+  - Key Decisions (a tabela de ADRs existentes)
+
+- [ ] Atualizar RELEASE-PLAN.md com Success Criteria por release
+
+- [ ] Manter SKILL-INDEX.md como proposto (similar a nada em GSD, é um win único)
+
+### Fase 2: Médio Prazo (30 min de trabalho)
+
+- [ ] Criar `templates/` com estruturas esperadas (spec.md, diagnosis.md, etc.)
+
+- [ ] Criar `references/bmad-phases.md` (ciclo BMAD detalhado)
+
+- [ ] Criar `references/gates-and-guardrails.md` (HARD-GATEs por skill)
+
+### Fase 3: Longo Prazo (Nice-to-Have)
+
+- [ ] Criar `references/skill-antipatterns.md` (o que não fazer)
+
+- [ ] Criar `references/clean-code-mapping.md` (como cada skill implementa Clean Code)
+
+---
+
+## 5. Tabela: Estrutura Final Recomendada
+
+| Nível | Artefato | Propósito | GSD Equivalente |
+|---|---|---|---|
+| **Visão** | specs/PROJECT.md | Contexto, requisitos, decisões | PROJECT.md |
+| **Roadmap** | specs/RELEASE-PLAN.md | Sequência de releases + success criteria | ROADMAP.md |
+| **Estado** | specs/STATE.md | Posição atual (< 100 linhas) | STATE.md |
+| **Skill Catalog** | SKILL-INDEX.md | Tabela canônica de 38 skills | (N/A em GSD) |
+| **Templates** | templates/*.md | Estruturas esperadas | templates/ |
+| **Referência** | references/*.md | Gates, antipatterns, ciclo BMAD | references/ |
+| **Documentação** | README.md | Install, quickstart | README.md |
+| **Convênios** | CONVENTIONS.md | Code, test, git, specs/ standards | CONVENTIONS.md |
+| **Histórico** | specs/archive/releases/PLAN-v*.md | Planos completados | (Collapsed em ROADMAP) |
+
+---
+
+## 6. Validação Final: Aplicar ao Projeto Skills
+
+**Antes (Atual):**
+```
+PLAN.md (stale, 453 linhas)
+        ↓
+specs/RELEASE-PLAN.md (vivo, 104 linhas)
+      ↓
+specs/STATE.md (59 linhas) ✓
+      ↓
+specs/PLAN-v*.md (16 arquivos, dispersos)
+      ↓
+README.md (191 linhas, copia RELEASE-PLAN)
+```
+
+**Depois (Proposto + GSD Best Practice):**
+```
+specs/PROJECT.md (novo)           ← Core Value, Requirements, Decisions
+        ↓
+specs/RELEASE-PLAN.md (revisado)  ← Roadmap + Success Criteria
+        ↓
+specs/STATE.md (mantém)           ← Current Position
+        ↓
+SKILL-INDEX.md (novo)             ← Tabela canônica
+        ↓
+README.md (simplificado)          ← Install, quickstart, link a SKILL-INDEX
+        ↓
+templates/ (novo, opcional)       ← Estruturas esperadas
+references/ (novo, opcional)      ← Gates, antipatterns, BMAD phases
+```
+
+**Resultado:**
+- ✅ Sem redundância entre PLAN.md, RELEASE-PLAN, README
+- ✅ Hierarquia clara: PROJECT → RELEASE-PLAN → STATE → SKILL-INDEX
+- ✅ Incorpora melhores práticas de GSD sem copiar excessivamente
+- ✅ Nomes simples (verb-noun) mantidos
+- ✅ Fases BMAD explícitas em PROJECT.md ou documento separado
+
+---
+
+## 7. Checklist Final
+
+- [x] Minha análise identificou redundâncias corretas (PLAN.md, PLAN-v*.md, skill index)
+- [x] Minha hierarquia proposta é consistente com GSD (STATE → ROADMAP → skills)
+- [x] Faltou: PROJECT.md (contexto do projeto)
+- [x] Faltou: Success Criteria formalizados
+- [x] Faltou: templates/ e references/ (nice-to-have)
+- [x] SKILL-INDEX.md é único valor adicionado vs. GSD (bom!)
+- [x] Nomes simples e ciclo BMAD estão corretos
+- [x] Recomendação: Incorporar PROJECT.md + Success Criteria antes de executar
+
+---
+
+## 8. Próximos Passos Imediatos
+
+1. ✅ Criar `specs/PROJECT.md` com estrutura de GSD
+2. ✅ Atualizar `specs/RELEASE-PLAN.md` com Success Criteria
+3. ✅ Finalmente: Deletar `PLAN.md`, arquivar `PLAN-v*.md`, simplificar README
+4. 📝 Opcional: Criar `templates/` e `references/` conforme GSD
+

package/bin/bigpowers.js

@@ -29,6 +29,43 @@ function run(cmd, cwd = ROOT) {
   }
 }
 
+// True when this copy runs from the global npm install (not a git clone or npx temp dir).
+function isGlobalInstall() {
+  try {
+    const globalRoot = execSync('npm root -g', { encoding: 'utf8' }).trim();
+    return globalRoot && ROOT.startsWith(globalRoot);
+  } catch {
+    return false;
+  }
+}
+
+// `bigpowers update` used to only re-sync the already-installed files, so it never fetched
+// a newer release. When we're the global install, pull the latest from npm first; the reinstall
+// overwrites ROOT in place, so the setup.js required afterwards is the freshly installed one.
+function selfUpdateGlobalPackage() {
+  if (!isGlobalInstall()) {
+    console.log('bigpowers: not a global npm install — skipping package self-update.');
+    console.log('  git clone → `git pull && npm run sync && bash scripts/install.sh`');
+    console.log('  one-shot  → `npx bigpowers@latest setup`');
+    return;
+  }
+  console.log('bigpowers: fetching the latest release from npm (npm install -g bigpowers@latest)...');
+  try {
+    execSync('npm install -g bigpowers@latest', { stdio: 'inherit' });
+  } catch {
+    console.error('bigpowers: `npm install -g bigpowers@latest` failed — re-syncing the installed version instead.');
+  }
+}
+
+// Best-effort registry check; silent on any failure so offline/slow networks never block a command.
+function latestPublishedVersion() {
+  try {
+    return execSync('npm view bigpowers version', { encoding: 'utf8', timeout: 4000 }).trim();
+  } catch {
+    return null;
+  }
+}
+
 const cmd = process.argv[2];
 
 if (cmd === 'setup' || cmd === 'install') {
@@ -39,7 +76,8 @@ if (cmd === 'setup' || cmd === 'install') {
 }
 
 if (cmd === 'update') {
-  // Delegate to interactive installer (same as setup)
+  // Pull the newest release first (global installs), then re-sync + refresh symlinks.
+  selfUpdateGlobalPackage();
   const setupScript = path.join(ROOT, 'bin', 'setup.js');
   require(setupScript);
   return;
@@ -51,6 +89,11 @@ if (cmd === 'status') {
       .filter(d => fs.lstatSync(path.join(os.homedir(), '.claude', 'skills', d)).isSymbolicLink())
       .length;
     console.log(`bigpowers v${pkg.version} — ${count} skills installed`);
+    const latest = latestPublishedVersion();
+    if (latest && latest !== pkg.version) {
+      console.log(`\n⬆️  A newer release is available: v${latest} (you have v${pkg.version}).`);
+      console.log('   Upgrade: npm install -g bigpowers@latest && bigpowers update');
+    }
   } else {
     console.log('bigpowers not installed. Run: bigpowers setup');
   }
@@ -63,8 +106,8 @@ bigpowers — agent skills for spec-driven, test-first development
 
 Commands:
   bigpowers setup    Install skills into ~/.claude/skills/
-  bigpowers update   Re-run sync and install (after npm update -g bigpowers)
-  bigpowers status   Show installed version and skill count
+  bigpowers update   Fetch the latest release (global installs) + re-sync and refresh symlinks
+  bigpowers status   Show installed version and skill count (warns if a newer release exists)
   bigpowers help     This message
 `);
   process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.87.0",
+  "version": "2.87.2",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/lib/git-hours.sh

@@ -18,7 +18,7 @@ partition() {
   git -C "$ROOT" log --no-merges "$range" \
       --pretty=format:"%at%x1f%H%x1f%(trailers:key=${key},valueonly,separator=%x2C)" \
     | sort -n \
-    | awk -F '\x1f' -v IDLE="$IDLE_SECONDS" -v PAD="$PAD_SECONDS" '
+    | awk -v FS="$(printf '\037')" -v IDLE="$IDLE_SECONDS" -v PAD="$PAD_SECONDS" '
         {
           ts = $1 + 0; story = $3
           gsub(/[[:space:]]/, "", story)

package/scripts/record-cycle-time.sh

@@ -90,7 +90,7 @@ cmd_report() {
 }
 
 cmd_append() {
-  local range="HEAD" key="$STORY_KEY" story="" bcps="" merged_at="" file="$ROOT/specs/metrics/cycle-times.yaml"
+  local range="HEAD" key="$STORY_KEY" story="" bcps="" bcp_plus="" merged_at="" file="$ROOT/specs/metrics/cycle-times.yaml"
   local telemetry=""  # path to harness telemetry JSON (GSD-2/gsd-pi format, optional)
   while [ $# -gt 0 ]; do
     case "$1" in
@@ -143,6 +143,8 @@ cmd_append() {
   agent_compression="null"; agent_tool_calls="null"; agent_api_requests="null"
   agent_duration_ms="null"; agent_model="null"; agent_tier="null"
   agent_downgraded="null"; agent_skills="[]"
+  agent_tokens_in="null"; agent_tokens_out="null"
+  agent_tokens_cache_read="null"; agent_tokens_cache_write="null"
 
   if [ -n "$telemetry" ] && [ -f "$telemetry" ]; then
     # GSD-2/gsd-pi snapshotUnitMetrics JSON format:

package/scripts/validate-agentic-ste.sh

@@ -79,7 +79,13 @@ ste_extract_prose() {
 
 ste_count_words() {
   # shellcheck disable=SC2207
-  local words=($1)
+  local words
+  # BUG-2026-08-05-ste-glob-wordcount: ($1) globs each word — a bare ** (markdown
+  # bold opener) expands to every file in cwd and inflates the count. Disable
+  # pathname expansion; safe here because this function only runs inside $( ).
+  set -f
+  words=($1)
+  set +f
   echo "${#words[@]}"
 }
 
@@ -168,6 +174,14 @@ name: fixture-long
 description: Long sentence fixture.
 ---
 Run the full local green stack including compliance verification gates sync skills trace stories and catalog drift check before any forward implementation work on this repository.
+EOF
+
+  cat > "$tmp/good-bold.md" <<'EOF'
+---
+name: fixture-bold
+description: Bold markdown list fixture (BUG-2026-08-05-ste-glob-wordcount).
+---
+1. **Check dependencies first.** DO inspect what your current dependencies already do before writing your own code.
 EOF
 
   local saved_strict=$STRICT saved_audit=$AUDIT
@@ -181,6 +195,13 @@ EOF
     return 1
   fi
 
+  VIOLATIONS=0
+  ste_audit_file "$tmp/good-bold.md"
+  if (( VIOLATIONS > 0 )); then
+    echo "SELF-TEST FAIL: bold-markdown fixture should pass (glob word-count bug, BUG-2026-08-05)" >&2
+    return 1
+  fi
+
   VIOLATIONS=0
   ste_audit_file "$tmp/bad-hedge.md"
   if (( VIOLATIONS == 0 )); then