@aksp/opencrew 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,111 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.5.0] — 2026-10-02
+
+Trilha U1 "Revisor com dentes" — primeira melhoria vinda do uso real
+(`docs/jornada/2026-10-02-uso-real.md`, `specs/fase-u1-revisor-com-dentes.md`).
+
+### Added
+- **Verificador automático** (`_opencrew/core/scripts/verificar.mjs`, Node puro): mede o texto
+  ANTES do revisor usando os limites `constraints:` dos best-practices — título e meta description
+  do blog, legenda e hashtags do Instagram, slides do carrossel, post do LinkedIn, tweets, links
+  (alerta quando abaixo do mínimo). Bloqueia placeholders (`wa.me/55…9999…`, `[Empresa X]`,
+  `lorem ipsum`…), termos entre aspas em `## Proibições Explícitas` da memória da crew e
+  `[PREENCHER: …]`; alerta afirmações em 1ª pessoa com dado concreto (R$, %, ano passado,
+  "N clientes"). Relatório em PT-BR com valor medido × limite; última linha
+  `VERIFICACAO:OK | BLOQUEADA | AGUARDANDO_USUARIO`.
+- **Regras de veracidade** injetadas em todo passo de criação: nunca inventar casos, depoimentos,
+  números ou histórias em 1ª pessoa — usar `[PREENCHER: o que falta]`.
+
+### Changed
+- **Revisão com trava**: antes de todo passo com `on_reject`, o runner verifica **todas** as saídas
+  desde o redator (não só a entrada do revisor — no uso real as legendas nunca eram revisadas);
+  `VERIFICACAO:BLOQUEADA` força REJECT seja qual for a nota; no limite de ciclos o usuário escolhe
+  corrigir, aceitar (registrado) ou abortar; a aprovação final mostra o resumo e pede os
+  `[PREENCHER]`.
+- `review.md`: o revisor copia os números do relatório (nunca estima), não aprova com bloqueio e
+  tem nota máxima 7/10 com alerta não resolvido. `copywriting.md` e o build: regra de não inventar.
+- **Instagram em 4:5**: carrossel/feed agora 1080×1350 (a API do Instagram só publica de 4:5 a
+  1,91:1), no máximo 10 slides; presets do `image-creator`, `template-designer` (e modelos-base),
+  `image-fetcher` e best-practices atualizados. Limites com nomes canônicos (`hashtags_max`).
+
+### Internal
+- Docs de jornada (`docs/jornada/`: uso real, roteiro de teste U0, medições) e roadmap de trilhas U.
+- Regras de dev 12 (limite só vale se medido) e 13 (PT-BR para o usuário); alerta de tamanho e
+  lint cobrem os scripts do runtime.
+
+## [1.4.2] — 2026-10-02
+
+Hotfix "parar de causar dano" (Fase 1 da auditoria — `specs/fase-1-hotfix.md`).
+
+### Fixed
+- **`CLAUDE.md` gerado não traz mais o fluxo STATUS.md do mantenedor** (vazado na 1.4.0/1.4.1);
+  o `update` remove a seção de instalações existentes, sem tocar no texto do usuário.
+  `STATUS.md` saiu do `.gitignore` do template.
+- **`--help` nunca executa comando**: `update --help` / `-h` e `init --help` só mostram a ajuda.
+  Parser estrito (`node:util.parseArgs`): opção desconhecida, `--ide` sem id válido ou
+  argumento solto (`init minha-pasta`) falham com exit 1 **antes** de escrever qualquer arquivo.
+  `--ide claude-code` (com espaço) e `-yv` funcionam. `update --dry-run` = `--check`.
+- **`update` sem `AGENTS.md`** cria a ponte em vez de quebrar com ENOENT.
+- **Migração do `AGENTS.md` legado faz backup** em `AGENTS.md.bak` (ou `.bak-<timestamp>`).
+- **`.env.example` e `.gitignore` do usuário não são mais sobrescritos/ignorados**: recebem um
+  bloco `# opencrew:start … # opencrew:end` no fim; as linhas do usuário ficam intactas.
+  O bloco do `.gitignore` agora cobre `.claude/settings.local.json`, `crews/*/state.json` e
+  `crews/*/_investigations/`.
+- **Ctrl+C no prompt de IDEs não deixa instalação pela metade**: as IDEs são escolhidas antes
+  da primeira escrita; cancelamento sai com 130 e "Cancelled — nothing was written.". Uma
+  instalação interrompida (core sem stamp de versão) é **retomada** pelo próximo `init`.
+- Erros inesperados mostram uma linha `✗ <mensagem>` (stack só com `OPENCREW_DEBUG=1`).
+- Marcadores de bloco: um `start` órfão (fim apagado à mão) não faz mais a regravação engolir
+  linhas do usuário.
+- Skills: caminho do `image-ai-generator` corrigido (`{skill_path}/scripts/generate.py`, nota
+  `py -3` no Windows); `instagram-publisher` lê as imagens da pasta do run atual; o
+  `image-creator` renderiza JPEG quando o destino é Instagram.
+- Runner: o toggle do dashboard reconhece o formato `- **Dashboard:** enabled` gravado no
+  onboarding.
+
+### Security
+- **Publicar/enviar é sempre o último trecho do pipeline**: `… → Review → Final Approval
+  checkpoint → [Publish/Send]` (design), com o novo Gate 2c BLOCKING no build. Passos com
+  `side_effects: irreversible` rodam inline e **nunca** têm retry automático nem auto-correção
+  de veto — o runner avisa que a ação pode já ter acontecido e pergunta.
+- **`instagram-publisher`**: legenda via `--caption-file` (nunca interpolada no shell); só
+  aceita `.jpg`/`.jpeg` dentro de `crews/*/output/`; upload no imgBB expira em 24h; token da
+  Graph API no corpo dos POST, não na URL; fluxo preview → `--dry-run` → confirmação explícita
+  ("publish"/"publicar") → publicação única.
+
+### Changed
+- Template `templates/AGENTS.md` (o `system.md` instalado) compactado (−24%) sem mudar o roteamento.
+
+### Internal
+- Testes por cenário da spec (F1-01a…F1-13a); trava nova: nenhum arquivo de `templates/`
+  carrega conteúdo do mantenedor. `KNOWN_BROKEN` de referências zerado.
+
+### Added (governança do repositório — Fase 0)
+- Auditoria geral da v1.4.1 com roadmap por fases: `docs/auditoria/2026-10-02-auditoria-geral.md`.
+- Regras de desenvolvimento em `AGENTS.md` (project-standards T3, tabela Regra → Trava);
+  `CLAUDE.md` da raiz vira apontador versionado.
+- Porta de verificação única `npm run verify` (`scripts/verify.js`): lint (agora inclui
+  `bin/`), testes (descobertos automaticamente em `tests/`), version-sync e alerta de
+  tamanho (`scripts/check-size.js`). CI e publish chamam a mesma porta.
+- Travas novas: `tests/package.test.js` (conteúdo do tarball × README),
+  `tests/template-refs.test.js` (caminhos citados nos prompts existem),
+  `tests/verify.test.js` e `tests/check-size.test.js` (provetas).
+- `GLOSSARIO.md`; `IDEIAS.md` reformatado com triagem e `Alocação: →`.
+
+### Changed (governança do repositório — Fase 0)
+- Dogfood do mantenedor sai da raiz e vai para `sandbox/` (fora do git).
+- `publish.yml` confere a tag contra a versão do `package.json` e roda `npm run verify`;
+  CI e publish usam só `npm ci` (sem fallback que esconde drift do lockfile).
+
+### Docs (Fase 0)
+- README: o dashboard não é instalado pelo `init`; `update` não atualiza as pontes de IDE
+  (use `init --repair-bridges`); migração do `AGENTS.md` legado perde instruções extras;
+  flags `upgrade`, `--ide`, `--all`/`-y`, `--repair-bridges` documentadas; contagens
+  corrigidas (22 guias, 13 prompts); Windsurf removido da lista; promessa "30-70% de
+  economia" sem base removida.
+
 ## [1.4.1] — 2026-08-04
 
 ### Fixed
@@ -25,6 +130,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
   - `AGENTS.md` — step 7b na seção Loading the Pipeline Runner.
   - 3 novos testes de contrato em `docs.test.js`.
 
+> Itens desta versão que ficaram de fora da entrada original (acrescentados na auditoria
+> de 2026-10-02):
+- **Pontes `.agents/`** para Antigravity, Gemini CLI e Qwen Code
+  (`.agents/skills/opencrew/SKILL.md`, `.agents/workflows/opencrew.md`).
+- **`init --repair-bridges`**: regrava as pontes de IDE num workspace existente.
+- **`update` migra `AGENTS.md` legado** (pré-1.3, sistema completo) para a ponte fina.
+- **Fix Antigravity**: frontmatter no workflow para registrar `/opencrew`.
+- ⚠️ **Regressão**: o `CLAUDE.md` gerado passou a conter a seção "STATUS.md (gestão de
+  sessão)" do fluxo pessoal do mantenedor, e `templates/gitignore` ganhou `STATUS.md`.
+  Correção prevista na 1.4.2 (F1-01).
+
 ## [1.3.3] — 2026-08-03
 
 ### Fixed

package/README.md

@@ -34,7 +34,12 @@ dentro da sua IDE.**
   sem abrir editor nenhum.
 - 🎛️ **Seleção inteligente de agentes** — o sistema analisa seu pedido e
   sugere quais agentes são necessários para aquela tarefa. Você confirma ou
-  ajusta com um clique. Economia de 30-70% de tokens quando agentes são pulados.
+  ajusta com um clique. Agentes pulados não gastam tokens naquele run.
+- 🔎 **Revisor com dentes** — antes da revisão, um verificador automático mede o texto
+  (tamanho de título, meta description, legenda, hashtags, slides), barra placeholders,
+  termos que você proibiu e `[PREENCHER]` pendentes, e aponta afirmações a confirmar.
+  Bloqueio não passa, seja qual for a nota do revisor. A crew não inventa casos nem números:
+  quando falta um dado real, ela pergunta na aprovação final.
 
 ---
 
@@ -126,12 +131,12 @@ enxuto — todos apontam para a mesma fonte.
 |---|---|
 | `AGENTS.md` (ponte) + `.claude/skills/opencrew/SKILL.md` + `CLAUDE.md` | Claude Code |
 | `AGENTS.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | OpenAI Codex, Codex CLI |
-| `AGENTS.md` (ponte) + `.cursor/rules/opencrew.mdc` | Cursor, Windsurf |
+| `AGENTS.md` (ponte) + `.cursor/rules/opencrew.mdc` | Cursor |
 | `AGENTS.md` (ponte) + `.github/copilot-instructions.md` | VS Code + GitHub Copilot |
 | `AGENTS.md` (ponte) + `.opencode/commands/opencrew.md` | OpenCode |
 | `AGENTS.md` (ponte) + `.agent/rules/opencrew.md` + `.agent/workflows/opencrew.md` + `.agents/skills/opencrew/SKILL.md` + `.agents/workflows/opencrew.md` | Google Antigravity |
-| `GEMINI.md` (ponte) | Gemini CLI |
-| `QWEN.md` (ponte) | Qwen Code |
+| `GEMINI.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | Gemini CLI |
+| `QWEN.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | Qwen Code |
 | `AGENTS.md` (ponte) + `.trae/rules/opencrew.md` | Trae |
 
 > ⚠️ **Importante:** `CLAUDE.md`, `GEMINI.md` e os demais arquivos de IDE são
@@ -150,8 +155,8 @@ meu-projeto/
 ├── CLAUDE.md                     ← ponte fina + suas instruções (merge)
 ├── GEMINI.md                     ← ponte fina (Gemini CLI)
 ├── .mcp.json                     ← servidor Playwright do OpenCrew
-├── .gitignore
-├── .env.example
+├── .gitignore                    ← bloco `# opencrew` no fim; suas linhas são mantidas
+├── .env.example                  ← idem
 │
 ├── _opencrew/
 │   ├── core/
@@ -159,8 +164,8 @@ meu-projeto/
 │   │   ├── runner.pipeline.md    ← executor de pipeline
 │   │   ├── skills.engine.md      ← gerenciador de skills
 │   │   ├── architect.agent.yaml  ← definição do Arquiteto
-│   │   ├── best-practices/       ← 23 guias de melhores práticas
-│   │   └── prompts/              ← 12 prompts de fase (discovery, design, build, etc.)
+│   │   ├── best-practices/       ← 22 guias de melhores práticas + _catalog.yaml
+│   │   └── prompts/              ← 13 prompts de fase (discovery, design, build, etc.)
 │   ├── agents/                   ← 5 agentes base compartilhados
 │   │   ├── researcher.agent.md
 │   │   ├── copywriter.agent.md
@@ -185,11 +190,12 @@ meu-projeto/
 │   ├── instagram-publisher/      ← publicação no Instagram
 │   ├── resend/                   ← envio de emails
 │   └── ...
-│
-└── dashboard/
-    └── index.html                ← dashboard visual (opcional, offline)
 ```
 
+> O dashboard visual (`dashboard/index.html`) **não é instalado** pelo `init` — ele vive
+> só no repositório do OpenCrew e ainda é experimental (decisão de publicar ou remover:
+> Fase 4 da auditoria em `docs/auditoria/`).
+
 ---
 
 ## Mantendo o OpenCrew atualizado
@@ -198,18 +204,29 @@ meu-projeto/
 npx @aksp/opencrew update
 ```
 
-O `update` **nunca destrói seus dados**. Ele atualiza apenas:
+O `update` não toca nas suas crews nem na sua memória. Ele atualiza apenas:
 
 | O que é atualizado | O que NUNCA é tocado |
 |---|---|
-| `_opencrew/core/` (framework) | `crews/` (suas crews) |
-| Skills do catálogo | `_opencrew/_memory/` (perfil, preferências) |
+| `_opencrew/core/` (framework — sobrescrito por inteiro) | `crews/` (suas crews) |
+| Skills do catálogo (sobrescritas — edições locais se perdem) | `_opencrew/_memory/` (perfil, preferências) |
 | `_opencrew/core/system.md` | `.env` (suas chaves) |
-| Bloco `<!-- opencrew -->` nos bridges | Arquivos de IDE (fora do bloco) |
+| Bloco `<!-- opencrew -->` no `AGENTS.md` | Pontes das IDEs (`CLAUDE.md`, `.cursor/`, `.agents/`…) |
+
+As **pontes das IDEs não são atualizadas** pelo `update`. Para regravá-las com a versão
+atual, use:
+
+```bash
+npx @aksp/opencrew init --repair-bridges --ide=claude-code
+```
+
+(troque `claude-code` pelas IDEs que você usa, separadas por vírgula; sem `--ide`, o
+comando grava as pontes de **todas** as IDEs suportadas).
 
 Se você está migrando de uma versão anterior a v1.3, o `update` detecta
 AGENTS.md legados (sistema completo de 150 linhas) e os substitui pela ponte
-fina automaticamente, sem perder suas instruções.
+fina. Desde a v1.4.2 o arquivo original é copiado antes para `AGENTS.md.bak` (até a v1.4.1,
+instruções suas adicionadas a esse `AGENTS.md` legado eram perdidas).
 
 Para verificar se há atualização disponível sem aplicar:
 
@@ -245,7 +262,11 @@ npx @aksp/opencrew update --check
 |---|---|
 | `npx @aksp/opencrew init` | Instala o OpenCrew na pasta atual |
 | `npx @aksp/opencrew update` | Atualiza o framework |
-| `npx @aksp/opencrew update --check` | Verifica se há update disponível |
+| `npx @aksp/opencrew update --check` (ou `--dry-run`) | Verifica se há update disponível, sem alterar nada |
+| `npx @aksp/opencrew upgrade` | Atalho para `update` |
+| `npx @aksp/opencrew init --ide=claude-code,cursor` | Instala só as pontes das IDEs indicadas |
+| `npx @aksp/opencrew init --all` (ou `-y`) | Instala as pontes de todas as IDEs |
+| `npx @aksp/opencrew init --repair-bridges` | Regrava as pontes de IDE num workspace existente |
 | `npx @aksp/opencrew version` | Mostra a versão instalada |
 | `npx @aksp/opencrew help` | Mostra ajuda dos comandos CLI |
 

package/bin/opencrew.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // opencrew — CLI entry point
-import { run } from '../src/cli.js';
+import { run, reportError } from '../src/cli.js';
 
-run(process.argv.slice(2)).catch((err) => {
-  console.error(err?.stack || String(err));
-  process.exit(1);
+// run() reports its own errors; this only catches a failure inside the reporter itself.
+run(process.argv.slice(2)).catch((e) => {
+  process.exitCode = reportError(e);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,8 +19,9 @@
   ],
   "scripts": {
     "start": "node bin/opencrew.js",
-    "test": "node --test tests/cli.test.js tests/docs.test.js tests/fsx.test.js tests/ides.test.js tests/init.test.js tests/paths.test.js tests/ui.test.js tests/update.test.js",
-    "lint": "eslint src/ tests/ scripts/",
+    "test": "node scripts/verify.js test",
+    "lint": "node scripts/verify.js lint",
+    "verify": "node scripts/verify.js",
     "version": "node scripts/stamp-version.js && git add templates/_opencrew/.opencrew-version"
   },
   "keywords": [

package/src/cli.js

@@ -1,6 +1,8 @@
+import { parseArgs as nodeParseArgs } from 'node:util';
 import { readJson } from './lib/fsx.js';
 import { packageJsonPath } from './lib/paths.js';
 import { allIdeIds } from './lib/ides.js';
+import { UsageError, isPromptCancel } from './lib/errors.js';
 import { init } from './commands/init.js';
 import { update } from './commands/update.js';
 import { c, log, err, warn, info } from './lib/ui.js';
@@ -31,27 +33,56 @@ function lt(a, b) {
   return false; // equal
 }
 
-function parseArgs(argv) {
-  const opts = { _: [] };
-  for (const a of argv) {
-    if (a.startsWith('--')) {
-      const eq = a.indexOf('=');
-      const k = eq > -1 ? a.slice(2, eq) : a.slice(2);
-      const v = eq > -1 ? a.slice(eq + 1) : true;
-      opts[k] = v;
-    } else if (a.startsWith('-') && a.length === 2) {
-      // Short flags: -y → yes, -v → version, -h → help
-      const short = a[1];
-      opts[short] = true;
-    } else {
-      opts._.push(a);
-    }
+const OPTION_SPEC = {
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'v' },
+  ide: { type: 'string' },
+  all: { type: 'boolean' },
+  yes: { type: 'boolean', short: 'y' },
+  'repair-bridges': { type: 'boolean' },
+  check: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+};
+
+const GLOBAL_OPTIONS = ['help', 'version'];
+const COMMAND_OPTIONS = {
+  init: ['ide', 'all', 'yes', 'repair-bridges'],
+  update: ['check', 'dry-run'],
+  upgrade: ['check', 'dry-run'],
+};
+
+/**
+ * Strict argument parsing: unknown options, options of another command and stray
+ * positionals are UsageErrors — raised before any command can write a file.
+ */
+export function parseArgs(argv) {
+  let parsed;
+  try {
+    parsed = nodeParseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true, tokens: true });
+  } catch (e) {
+    const unknown = e.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' && e.message.match(/'([^']+)'/);
+    const cmd = argv.find((a) => !a.startsWith('-')) ?? 'init';
+    throw new UsageError(unknown
+      ? `Unknown option '${unknown[1]}' for "${cmd}".`
+      : e.message.split('. ')[0].replace(/\.$/, '') + '.');
   }
-  // Normalize short flags to their long-form equivalents.
-  if (opts.y) opts.yes = true;
-  if (opts.v) opts.version = true;
-  if (opts.h) opts.help = true;
-  return opts;
+  const [cmd, ...extra] = parsed.positionals;
+  const { values } = parsed;
+  const command = cmd ?? (values.version ? 'version' : values.help ? 'help' : 'init');
+
+  const allowed = new Set([...GLOBAL_OPTIONS, ...(COMMAND_OPTIONS[command] ?? [])]);
+  const foreign = parsed.tokens.find((t) => t.kind === 'option' && !allowed.has(t.name));
+  if (foreign) throw new UsageError(`Unknown option '${foreign.rawName}' for "${command}".`);
+
+  if (extra.length) {
+    throw new UsageError(command === 'init'
+      ? 'init does not take a directory — cd into the project folder first.'
+      : `Unexpected argument "${extra[0]}" for "${command}".`);
+  }
+
+  const opts = { ...values, _: parsed.positionals };
+  if (opts['dry-run']) opts.check = true;
+  return { command, opts };
 }
 
 function help(version) {
@@ -65,8 +96,8 @@ ${c.bold('Commands')}
   init            Scaffold an opencrew workspace in the current folder
   update          Refresh the framework (keeps your crews, memory and .env)
   upgrade         Alias for update
-  help            Show this help
-  version         Print the version
+  help            Show this help (also: <command> --help, -h)
+  version         Print the version (also: --version, -v)
 
 ${c.bold('Options for init')}
   --ide=a,b       Preselect IDEs (skip the prompt). Valid: ${allIdeIds().join(', ')}
@@ -75,7 +106,8 @@ ${c.bold('Options for init')}
   --repair-bridges  Regenerate IDE bridge files in an existing workspace
 
 ${c.bold('Options for update')}
-  --check         Dry-run: report whether an update is available without making changes
+  --check         Report whether an update is available without making changes
+  --dry-run       Same as --check
 
 ${c.bold('Examples')}
   npx @aksp/opencrew init
@@ -87,8 +119,26 @@ ${c.bold('Examples')}
 `);
 }
 
-export async function run(argv) {
-  const opts = parseArgs(argv);
+/** Turn any error into one readable line and an exit code. Stack only with OPENCREW_DEBUG=1. */
+export function reportError(e) {
+  if (isPromptCancel(e)) {
+    warn('Cancelled — nothing was written.');
+    return 130;
+  }
+  err(e?.message ?? String(e));
+  if (e instanceof UsageError) info(`Run ${c.cyan('npx @aksp/opencrew help')} for usage.`);
+  else if (process.env.OPENCREW_DEBUG) console.error(e?.stack);
+  return 1;
+}
+
+export async function run(argv, { commands = { init, update } } = {}) {
+  let command, opts;
+  try {
+    ({ command, opts } = parseArgs(argv));
+  } catch (e) {
+    process.exitCode = reportError(e);
+    return;
+  }
 
   let version = 'unknown';
   let engines = {};
@@ -115,23 +165,23 @@ export async function run(argv) {
     }
   }
 
-  const cmd = opts._[0] || (opts.version ? 'version' : opts.help ? 'help' : 'init');
-
-  switch (cmd) {
-    case 'init':
-      return init(opts);
-    case 'update':
-    case 'upgrade':
-      return update(opts);
-    case 'version':
-    case '--version':
-      return log(version);
-    case 'help':
-    case '--help':
-      return help(version);
-    default:
-      err(`Unknown command: ${cmd}`);
-      help(version);
-      process.exitCode = 1;
+  // --version / --help never run a command (they may follow any command).
+  if (opts.version || command === 'version') return log(version);
+  if (opts.help || command === 'help') return help(version);
+
+  try {
+    switch (command) {
+      case 'init':
+        return await commands.init(opts);
+      case 'update':
+      case 'upgrade':
+        return await commands.update(opts);
+      default:
+        err(`Unknown command: ${command}`);
+        help(version);
+        process.exitCode = 1;
+    }
+  } catch (e) {
+    process.exitCode = reportError(e);
   }
 }