@fontdata/ai-harness 2.0.0 → 2.1.0

package/templates/skills/executar-plan/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: executar-plan
+description: Executa o plano aprovado de um trabalho com sub-agents em paralelo, fase a fase, com TDD, gates de revisor-testes e qa, bloqueios registrados sem parar a execução e retomada de onde parou.
+argument-hint: "[id do trabalho]"
+---
+
+# Executar plano — orquestração com sub-agents
+
+Trabalho: $ARGUMENTS
+
+Você é o **ORQUESTRADOR**. Você não implementa nada: lê o plano, delega cada task a sub-agents, aplica os gates e
+mantém o estado em disco. **Sempre relate no chat qual agent está ativo**, principalmente nos gates.
+
+## Passo 0 — Identificar o trabalho (somente leitura)
+
+1. Use o id informado; sem id, procure em `docs/trabalhos/` o único `PLAN.md` com status `aguardando-aprovacao`
+   ou `em-execucao`. Com mais de um, pergunte qual.
+2. Leia `SPEC.md`, `PLAN.md`, `DECISOES.md` e `BLOQUEIOS.md` do trabalho, o `CLAUDE.md` da raiz e as rules. Quando
+   existir `.claude/rules/harness-projeto.md`, delegue cada task ao agent do domínio, aplique os portões extras
+   depois de `revisor-testes` e `qa` e passe aos gates o comando da suíte declarado.
+3. Confirme que o plano pode ser executado: `auditoria_plano: aprovado` no frontmatter e nenhum achado `contrato-*`
+   deste trabalho em `npx @fontdata/ai-harness doctor`. Sem isso, pare e sugira `/nova-tarefa`.
+
+## Passo 1 — Retomada
+
+Descubra onde a execução está seguindo `references/retomada.md`: status das tasks no frontmatter, bloqueios
+abertos e eventos do rastro. Apresente ao usuário:
+
+- tasks concluídas, pendentes, bloqueadas e a retomar;
+- o plano de execução a partir daqui (fases, paralelismo, agents).
+
+**🚦 Aguarde a confirmação** para começar ou retomar.
+
+## Passo 2 — Iniciar
+
+1. No `PLAN.md`, troque apenas a linha `status:` do plano para `em-execucao` (e `atualizado_em`).
+2. Grave `.ai-harness/estado.json` com `{"trabalho_ativo": "<id>"}` — é por ele que os hooks e o rastro sabem
+   qual trabalho está em curso.
+
+## Passo 3 — Executar fase por fase
+
+1. Nunca inicie uma fase antes de todas as tasks da anterior estarem `concluida` (ou `bloqueada`/`pulada` com
+   registro).
+2. Dentro da fase, dispare em paralelo as tasks `paralelizavel: true` cujas dependências estão concluídas.
+3. Ao delegar uma task, registre o início, troque o status da task para `em-andamento` e passe ao sub-agent o
+   contexto de `references/delegacao.md`:
+
+   ```bash
+   npx @fontdata/ai-harness evento task_iniciada --trabalho <id> --task <T-SS.NN> --nome executar-plan
+   ```
+
+## Passo 4 — Dúvida vira bloqueio, não pergunta
+
+Durante a execução **você não pergunta nada ao usuário**. Se uma task não pode seguir sem uma decisão:
+
+1. Registre o bloqueio em `docs/trabalhos/<id>/BLOQUEIOS.md` (crie a partir de `templates/BLOQUEIOS.md`):
+   pergunta, contexto, opções e o que destrava.
+2. Troque o status da task para `bloqueada` e registre:
+
+   ```bash
+   npx @fontdata/ai-harness evento bloqueio_aberto --trabalho <id> --task <T-SS.NN> --nome executar-plan --dados '{"bloqueio_id":"B-01"}'
+   ```
+
+3. **Pule a task e as que dependem dela** e siga com o restante.
+
+## Passo 5 — Gate de cada task
+
+Quando o sub-agent disser que terminou:
+
+1. **`revisor-testes`** (no plugin, `fontdata:revisor-testes`): os testes críticos existem e falhariam com a
+   implementação errada?
+2. **`qa`** (no plugin, `fontdata:qa`): critérios de aceite com evidência e suíte completa. O `qa` registra
+   `suite_verde` ou `suite_vermelha` no rastro.
+3. **Portões extras** de `.claude/rules/harness-projeto.md`, na ordem declarada. Com o portão **code-reviewer por
+   task em contexto limpo**:
+   - delegue ao agent `code-reviewer` do projeto num **sub-agent novo**, passando só a task, o diff e a `SPEC.md` —
+     nunca a conversa de implementação (sem o agent, registre um bloqueio sugerindo `/evoluir-harness code-reviewer`);
+   - item **BLOQUEANTE** volta ao implementador e, depois da correção, a task passa de novo por `revisor-testes` e
+     `qa`; IMPORTANTE e SUGESTÃO entram no relatório da fase;
+   - registre o veredito no rastro:
+
+     ```bash
+     npx @fontdata/ai-harness evento agent_veredito --trabalho <id> --task <T-SS.NN> --nome code-reviewer --dados '{"veredito":"aprovado","motivo":"..."}'
+     ```
+
+4. Só com os vereditos `APROVADO` (inclusive dos portões extras) e `suite_verde` registrado, troque o status da task
+   para `concluida` e registre `task_concluida`. Reprovada: devolva ao implementador com os achados — no máximo
+   **2 voltas**; na terceira, vira bloqueio (Passo 4).
+
+## Passo 6 — Gate de fase e progresso
+
+Ao fim de cada fase, rode o critério de gate da fase. Só avance se passar; se falhar, registre um bloqueio e
+siga com o que não depende da fase. Exiba: tasks concluídas, bloqueadas (com o motivo), vereditos dos gates e dos
+portões extras (com os achados IMPORTANTE e SUGESTÃO do `code-reviewer`), estado da suíte e a próxima fase.
+
+## Passo 7 — Encerramento
+
+1. Com todas as tasks `concluida`, troque o status do plano para `concluido` e registre:
+
+   ```bash
+   npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome executar-plan
+   ```
+
+2. Grave `{"trabalho_ativo": null}` em `.ai-harness/estado.json`.
+3. Com bloqueios abertos, apresente cada um ao usuário. Cada resposta vira decisão em `DECISOES.md`
+   (`decisao_registrada`), o bloqueio é fechado (`bloqueio_fechado`) e a task volta para `pendente` numa nova
+   rodada desta skill.
+
+## Restrições
+
+- **Não** modifique `SPEC.md`, `CLAUDE.md` nem o conteúdo do plano — só o status das tasks e do plano.
+- **Não** implemente fora do escopo do plano nem invente solução alternativa para task bloqueada.
+- **Não** feche task sem `suite_verde` no rastro.
+- Conteúdo em **pt-BR**.

package/templates/skills/executar-plan/references/delegacao.md

@@ -0,0 +1,43 @@
+# Delegação de uma task
+
+## Contexto passado ao sub-agent
+
+> Você é responsável pela task **T-SS.NN — [título]** do trabalho `docs/trabalhos/<id>/`.
+>
+> - **Input:** [o que já está pronto]
+> - **Output esperado:** [arquivo, função ou estrutura exata]
+> - **Testes críticos:**
+>   - [teste 1]
+>   - [teste 2]
+> - **Critério de aceite:** [verificável com sim ou não]
+>
+> Siga as convenções do `CLAUDE.md` e as rules do projeto. Escreva os testes primeiro (RED), confirme que falham,
+> implemente o mínimo para passar (GREEN) e rode a suíte do módulo.
+>
+> **Não** altere `SPEC.md`, `CLAUDE.md` nem o `PLAN.md`: quem atualiza o status é o orquestrador.
+> **Não** pergunte nada ao usuário: se precisar de uma decisão, pare e descreva a dúvida, as opções e o que
+> destrava — o orquestrador registra como bloqueio.
+>
+> Comentários: o padrão é não comentar (bloco interno até 3 linhas, docstring pública até 5, sem cabeçalho de
+> arquivo). **Não** escreva no código o número da task, a fase, o plano, a data nem o que você investigou.
+>
+> Na área de código legado tocada, preserve o padrão local do arquivo; convenções novas valem para arquivo novo.
+
+## Gates depois da implementação
+
+1. **revisor-testes** recebe a task e os arquivos alterados. Veredito `REPROVADO` → volta ao implementador com os
+   achados.
+2. **qa** recebe a task, os critérios de aceite e o comando da suíte completa. Ele registra a suíte no rastro:
+   - `suite_verde` com `--resultado ok` e `{"comando", "total", "falhas": 0}`;
+   - `suite_vermelha` com `--resultado falha` e o número de falhas.
+3. **Voltas:** no máximo 2 retornos ao implementador por task. Na terceira reprovação, a task vira bloqueio.
+
+## Fechamento
+
+Só com `revisor-testes` e `qa` aprovados e `suite_verde` no rastro:
+
+```bash
+npx @fontdata/ai-harness evento task_concluida --trabalho <id> --task <T-SS.NN> --nome executar-plan
+```
+
+e troque o status da task para `concluida` no frontmatter do `PLAN.md`.

package/templates/skills/executar-plan/references/retomada.md

@@ -0,0 +1,33 @@
+# Retomada da execução
+
+A execução pode parar a qualquer momento — sessão encerrada, contexto esgotado, máquina desligada. A skill não
+depende de memória da conversa: o estado está em disco.
+
+## De onde vem o estado
+
+1. **Frontmatter do `PLAN.md`:** `status` do plano e `tasks[].status`
+   (`pendente`, `em-andamento`, `concluida`, `bloqueada`, `pulada`).
+2. **`BLOQUEIOS.md`:** bloqueios com `status: aberto` e a task que cada um parou.
+3. **Rastro do trabalho** (`docs/eventos/<id>.jsonl`, incluindo `<id>.N.jsonl`): último evento de cada task —
+   `task_iniciada`, `suite_verde`, `suite_vermelha`, `agent_veredito`, `task_concluida`.
+
+Quando frontmatter e rastro divergem, **o frontmatter define o status** e o rastro explica o que aconteceu.
+
+## Como decidir o próximo passo
+
+| Situação da task | O que fazer |
+|---|---|
+| `concluida` | Nada |
+| `bloqueada` com bloqueio aberto | Continua parada até a decisão do usuário |
+| `bloqueada` com bloqueio resolvido | Voltar para `pendente` |
+| `em-andamento` sem `task_concluida` no rastro | **Retomar do começo**: o trabalho parcial pode estar inconsistente; confira o `git status` antes |
+| `em-andamento` com `suite_verde` e vereditos aprovados | Faltou só fechar: gravar `concluida` e `task_concluida` |
+| `pendente` com dependências concluídas | Pronta para executar |
+| `pendente` com dependência bloqueada | Continua esperando |
+
+A próxima task é a primeira `pendente` cujas dependências estão todas `concluida`, respeitando a ordem das fases.
+
+## Sem rastro nesta máquina
+
+O rastro não é versionado por padrão. Num clone novo, confie no frontmatter e trate `em-andamento` como
+"retomar do começo".

package/templates/skills/executar-plan/templates/BLOQUEIOS.md

@@ -0,0 +1,30 @@
+---
+schema_versao: 1
+tipo: bloqueios
+id: "{{id}}"
+trabalho_tipo: "{{trabalho_tipo}}"
+titulo: "Bloqueios — {{titulo}}"
+status: aberto
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+bloqueios:
+  - id: B-01
+    task: T-01.02
+    status: aberto
+    aberto_em: "{{data}}"
+    resolvido_em: null
+    decisao: null
+---
+
+# Bloqueios — {{titulo}}
+
+Dúvidas que pararam uma task durante a execução. Cada bloqueio é resolvido por uma decisão registrada em
+`DECISOES.md`; depois disso, a task volta para `pendente`.
+
+## B-01 — Pergunta objetiva que precisa de resposta
+
+- **Task:** T-01.02
+- **Contexto:** o que foi encontrado e por que a task não pode seguir.
+- **Opções:** as alternativas possíveis, com a consequência de cada uma.
+- **O que destrava:** a informação ou a escolha necessária.

package/templates/skills/harness/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: harness
+description: Conduz o setup do harness em ordem, uma etapa por vez com confirmação entre elas (ideia, contexto, ignores, plano, scaffold, montagem, auto-tag, execução). Com argumento, roda só a etapa pedida.
+argument-hint: "[etapa: ideia|contexto|ignores|plano|scaffold|montar|auto-tag|executar]"
+---
+
+# /harness — setup guiado do projeto
+
+Etapa ou contexto inicial (opcional): $ARGUMENTS
+
+Você conduz a configuração do harness **em ordem**, parando para validar com o usuário antes de cada avanço. Cada
+etapa usa uma skill do catálogo ou uma referência desta skill. **Leia a referência de uma etapa só quando ela
+chegar**, nunca todas de uma vez.
+
+## Etapa isolada
+
+Com uma etapa em `$ARGUMENTS` (`ideia`, `contexto`, `ignores`, `plano`, `scaffold`, `montar`, `auto-tag` ou
+`executar`), rode **só essa etapa**, lendo só a referência dela, e encerre com o `doctor`. Sem argumento de etapa,
+siga o fluxo completo abaixo.
+
+## Antes de começar
+
+1. Pergunte se é um **projeto novo** ou **existente** (se não foi dito).
+   - **Novo:** todas as etapas.
+   - **Existente:** pule `ideia`, `scaffold` e `executar`. Em `contexto` e `ignores`, leve o código atual em conta.
+2. Em projeto existente, comece por `npx @fontdata/ai-harness doctor` e trate os erros antes de seguir.
+3. Se o projeto ainda usa o **layout de documentos anterior à 2.1** (pastas separadas por tipo de documento dentro
+   de `docs/`), proponha `npx @fontdata/ai-harness migrar`, que move tudo para `docs/trabalhos/<id>/`.
+
+## Sequência
+
+As referências ficam na pasta `references` desta skill.
+
+1. **ideia** — siga a referência `validar-ideia.md`: o escopo cabe no tempo previsto com multi-agents? Com veredito
+   AJUSTAR ou REPROVAR, pare e ajuste antes de seguir.
+2. **contexto** — `/sincronizar-claude-md`: gera o `SPEC.md` principal (entrevista de requisitos), o `CLAUDE.md` e
+   a seção de orquestração que faltarem, e reconcilia o que já existe.
+3. **ignores** — siga a referência `ignores.md`: `.claudeignore` e `.gitignore` conforme a stack.
+4. **plano** — `/nova-tarefa start`: cria o trabalho em `docs/trabalhos/<id>/` com `SPEC.md` e `PLAN.md`
+   auditados. **Não** dispare a execução: o scaffold vem antes.
+5. **scaffold** — siga a referência `scaffold.md`: estrutura inicial, rota `/health` e testes de smoke. Confirme que
+   o servidor sobe.
+6. **montar** — monte o harness com `/evoluir-harness`, nesta ordem:
+   1. `/evoluir-harness` sem argumento — audita a pasta `.claude` e mostra o que falta;
+   2. preencha `.claude/rules/harness-projeto.md` (instalada pelo init): mapa de agents por domínio, portões
+      extras, comando da suíte e verificação manual; apague as seções que não valem;
+   3. `/evoluir-harness skill` — skills antes dos agents, que dependem delas;
+   4. `/evoluir-harness agent` — só os agents de domínio: `revisor-testes`, `qa`, `investigador` e
+      `auditor-plano` já vêm instalados;
+   5. `/evoluir-harness code-reviewer`;
+   6. `/evoluir-harness rule` — incluindo a de precedência em código legado, quando houver legado;
+   7. `/evoluir-harness hook` — só hooks específicos dos agents; os hooks do harness já estão ativos;
+   8. `/evoluir-harness design-system`, quando o projeto tiver interface.
+
+   O padrão de comentários (rule, hook e catraca) já vem do `npx @fontdata/ai-harness init`: não recrie. Sugira
+   pular o que não fizer sentido para o projeto.
+7. **auto-tag** (opcional) — siga a referência `auto-tag.md`: GitHub Action que cria a tag quando a versão chega na
+   branch de produção.
+8. **executar** — `/executar-plan <id>`, **só com a confirmação explícita** do usuário.
+
+Ao final (fluxo completo ou etapa isolada), rode `npx @fontdata/ai-harness doctor` e mostre o resultado.
+
+## 🚦 GATE entre etapas
+
+Ao concluir cada etapa, apresente o que foi feito, o que vem a seguir e **aguarde confirmação explícita** antes de
+avançar. Nenhum arquivo é gravado sem aprovação do conteúdo proposto — nem nesta skill, nem nas referências.
+
+## Regras
+
+- **Não avance de etapa sem confirmação explícita.**
+- Relate sempre qual etapa e qual agent estão ativos.
+- Respeite TDD e os gates entre fases.
+- Etapa que não se aplica ao projeto é pulada só com o OK do usuário.
+- Não reescreva `SPEC.md`, `CLAUDE.md` nem planos fora da etapa que cuida deles.
+- Conteúdo gerado em **pt-BR**.

package/templates/skills/harness/references/auto-tag.md

@@ -0,0 +1,118 @@
+# Etapa auto-tag — tag automática quando a versão chega na produção
+
+Configure uma **GitHub Action** que **cria a tag** quando um novo número de versão chega na branch de produção
+(`main` por padrão; o usuário pode indicar outra). Separa dois papéis:
+
+- **Versionar** — humano, com `/versao` (bump e changelog, com aprovação). Sem tag, sem push.
+- **Taguear e deployar** — automático, por esta Action, quando o arquivo de versão muda na produção.
+
+A tag é a fonte única do release e a criação é **idempotente**. Esta etapa **não faz push nem cria tag**.
+
+## Passo 0 — Pré-checagem (somente leitura)
+
+1. `git remote -v`: o remoto é **GitHub**? Se não, avise que GitHub Actions não se aplica e pergunte como seguir.
+2. Branch de produção: a indicada, senão a padrão do remoto (`git symbolic-ref --short refs/remotes/origin/HEAD`).
+   **Confirme com o usuário.**
+3. Já existe `.github/workflows/auto-tag.yml`? Trate como **ajuste**, preservando o que for local.
+
+## Passo 1 — Fonte de verdade da versão
+
+Identifique **todas** as fontes lendo o projeto (não assuma). Para cada uma: arquivo, campo, formato (`X.Y.Z` ou
+`X.Y.Z.W`) e a extração via shell.
+
+- **Node / JS-TS:** `package.json` → `jq -r '.version' package.json`; Expo: `jq -r '.expo.version' app.json`.
+- **.NET:** `*.csproj` ou `Directory.Build.props` → `grep -oPm1 '(?<=<Version>)[^<]+' App.csproj`
+  (senão `<FileVersion>`).
+- **Delphi:** `*.dproj` (`VerInfo_Keys` com `FileVersion`/`ProductVersion`, ou `MajorVersion`/`MinorVersion`/
+  `Release`/`Build`) e/ou constante `.pas` (ex.: `cVersao`). Escolha **uma** fonte canônica e cite o arquivo:linha.
+  - `grep -oPm1 'FileVersion=\K[0-9.]+' Projeto.dproj`
+  - ou as quatro partes com `grep`/`sed`, concatenadas;
+  - ou `grep -oPm1 "cVersao\s*=\s*'\K[0-9.]+" Sobre.pas`
+- **Flutter:** `grep -oPm1 '(?<=^version: )[0-9.+]+' pubspec.yaml`
+- **Python:** `grep -oPm1 '(?<=^version = ")[^"]+' pyproject.toml` (ou `__version__`).
+- **Genérico:** `cat VERSION`, constante `VERSION`/`APP_VERSION`.
+
+Sem fonte encontrada, **pergunte** onde a versão é registrada. Determine também:
+
+- **App único** → tag `v<versão>`; **monorepo** → `<app>-v<versão>`, um arquivo de versão por app.
+- Se o `/versao` está instalado (é ele quem gera o commit de release que dispara a Action).
+- Como o deploy é disparado pela tag (`deploy-*.yml` ou webhook externo, ex.: Expo/EAS): define o `RELEASE_PAT`.
+
+## Passo 2 — Rascunho da Action (sem gravar)
+
+```yaml
+name: Auto-tag na <BRANCH_PRODUCAO>
+
+on:
+  push:
+    branches: [<BRANCH_PRODUCAO>]
+    paths:
+      - <ARQUIVO(S)_DE_VERSAO>
+
+permissions:
+  contents: write
+
+jobs:
+  auto-tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT || github.token }}
+
+      - name: Criar tag se a versão for nova
+        run: |
+          set -euo pipefail
+          VERSION="$(jq -r '.version' package.json)"   # troque pela extração da fonte detectada
+          if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
+            echo "Não consegui ler a versão"; exit 1
+          fi
+          TAG="v$VERSION"                               # monorepo: TAG="<app>-v$VERSION"
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "Tag $TAG já existe, nada a fazer."; exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+```
+
+- `paths:` lista **exatamente** os arquivos de versão, para rodar só quando a versão muda.
+- Troque a linha `VERSION=` pela extração da stack; **não** use `jq` fora de JSON (Delphi e .NET usam `grep -oP`/`sed`).
+- Monorepo: loop pelos apps, uma tag por app, com a checagem de idempotência dentro do loop.
+- A checagem `git rev-parse --verify refs/tags/$TAG` é obrigatória: nunca recrie tag.
+
+## Passo 3 — `RELEASE_PAT` (documentar, nunca criar)
+
+- O `GITHUB_TOKEN` padrão **não dispara outras Actions**. Se o deploy é um workflow disparado pela tag, a Action
+  precisa empurrar a tag com um **`RELEASE_PAT`**.
+- Deploy por webhook externo dispensa o PAT.
+- Como o usuário cria: PAT fine-grained com _Contents: Read and write_ no repositório (ou classic com `repo`), salvo
+  em **Settings → Secrets and variables → Actions** como `RELEASE_PAT`.
+- **Nunca** coloque token em arquivo versionado nem crie o secret por conta própria.
+
+## Passo 4 — 🚦 GATE antes de gravar
+
+Apresente: branch de produção e formato de tag; fontes de versão e linha de extração; o `auto-tag.yml` completo; se
+o `RELEASE_PAT` é necessário e por quê. **Grave só após aprovação explícita.**
+
+## Passo 5 — Gravar e verificar
+
+1. Escreva `.github/workflows/auto-tag.yml`.
+2. Crie ou atualize `docs/versionamento-tags.md`: a tag aponta um commit (o commit de release precisa estar na
+   produção antes da tag), o fluxo abaixo, a pegadinha `GITHUB_TOKEN` × `RELEASE_PAT` e a tabela app → arquivo de
+   versão → formato da tag → workflow de deploy.
+3. Ajuste docs ou comandos que mandavam criar ou empurrar tag manualmente.
+4. Valide a sintaxe do YAML. **Não** rode `git push` nem crie tag; sugira o commit
+   `chore: Configura auto-tag na <branch> via GitHub Actions` (ou `/git-commit-push`, se instalado).
+
+```
+/versao → push do commit de release → merge na produção → Action cria a tag → deploy dispara pela tag
+```
+
+## Guardrails
+
+- Replique o padrão do projeto (formato de versão e de tag); nunca imponha um novo.
+- Para refazer deploy, use o gatilho manual do workflow de deploy, nunca recrie a tag.
+- A branch de produção é produção: trate-a como tal.

package/templates/skills/harness/references/ignores.md

@@ -0,0 +1,40 @@
+# Etapa ignores — `.claudeignore` e `.gitignore`
+
+Analise a estrutura do projeto e proponha os arquivos de exclusão de contexto. Se a stack não estiver clara, leia
+o `SPEC.md` e o `CLAUDE.md` da raiz ou pergunte antes.
+
+## `.claudeignore`
+
+Seções obrigatórias, nesta ordem:
+
+```
+# Dependências
+[diretórios de dependências da stack]
+
+# Build e arquivos gerados
+[diretórios de build e arquivos gerados]
+
+# Segredos e variáveis de ambiente
+[todos os padrões de arquivos com credenciais]
+
+# Banco de dados local
+[arquivos de banco de desenvolvimento]
+
+# Uploads e mídia
+[diretórios de arquivos enviados pelo usuário]
+
+# Cache e logs
+[diretórios de cache e arquivos de log]
+```
+
+## `.gitignore`
+
+Versão reforçada cobrindo as mesmas categorias. Se já existir, **reconcilie**: acrescente o que falta e preserve o
+que o projeto já tem. Mantenha versionados `.ai-harness/` e `.claude/`; o rastro em `docs/eventos/` fica fora do
+versionamento por padrão.
+
+## Regras
+
+- Seja conservador: em caso de dúvida, exclua.
+- Nunca exclua código-fonte, testes ou documentação (`SPEC.md`, `CLAUDE.md`, `docs/trabalhos/`).
+- 🚦 Mostre o conteúdo proposto dos dois arquivos e grave só após aprovação.

package/templates/skills/harness/references/scaffold.md

@@ -0,0 +1,29 @@
+# Etapa scaffold — estrutura inicial do projeto
+
+Leia o `SPEC.md` e o `CLAUDE.md` da raiz e o `PLAN.md` do trabalho de start em `docs/trabalhos/<id>/` (criado na
+etapa plano, com `/nova-tarefa start`). Sem esse plano, pare e volte à etapa plano.
+
+## O que gerar
+
+1. **Estrutura de pastas** — todos os diretórios definidos na seção de estrutura do `CLAUDE.md`, cada um com um
+   `README.md` de uma linha descrevendo sua responsabilidade.
+2. **Configuração** — os arquivos da stack (`package.json`, `tsconfig.json`, `requirements.txt`, `.env.example` e
+   o que mais for necessário). Instale as dependências depois de criá-los. `.gitignore` e `.claudeignore` já vêm da
+   etapa ignores: só complemente.
+3. **Ponto de entrada mínimo** — `main.py`, `index.ts` ou `server.js`, conforme a stack, com o servidor
+   inicializado e uma rota `/health` que responde 200. Nenhuma lógica de negócio.
+4. **Testes** — o framework definido no `CLAUDE.md`, a pasta de testes espelhando a estrutura do projeto e um teste
+   de smoke que verifica se o servidor sobe.
+
+## O que não fazer
+
+- Nenhuma lógica de negócio, modelo de dados ou endpoint além de `/health`.
+- Nenhum componente de UI além do layout base.
+- Não disparar a execução do plano: isso é a etapa executar, com confirmação.
+
+## Critério de conclusão
+
+- 🚦 Antes de gravar, apresente a árvore de pastas e a lista de arquivos e aguarde aprovação.
+- Ao terminar, rode os comandos de verificação do `CLAUDE.md` e confirme que o servidor sobe e o smoke passa.
+- Registre o comando da suíte em `.claude/rules/harness-projeto.md`, na seção "Suíte de testes", ou deixe anotado
+  para a etapa montar.

package/templates/skills/harness/references/validar-ideia.md

@@ -0,0 +1,42 @@
+# Etapa ideia — validar se o escopo cabe na janela
+
+Aja como **arquiteto de software sênior**, especialista em dimensionar escopo de projetos construídos com Claude
+Code e multi-agents. Dê um diagnóstico **honesto e acionável**. Na dúvida, erre para o lado pessimista.
+
+## Contexto
+
+- **Ideia:** o que o usuário descreveu ao chamar o `/harness` ou nesta conversa.
+- **Janela de tempo:** se não foi informada, assuma **~4 horas** (formato imersão) e **diga que assumiu**.
+- **Modo de execução:** TDD obrigatório e sub-agents implementando módulos independentes em paralelo.
+
+Ideia ausente ou vaga demais: **pare e faça as perguntas mínimas**, uma por vez, antes de avaliar.
+
+## Critérios
+
+Para cada um, um veredito curto com a **evidência ou o risco concreto**, sem respostas genéricas.
+
+1. **Decomposição em módulos** — 2 a 4 módulos que agents separados implementariam de forma **genuinamente
+   independente** (não tocam os mesmos arquivos nem dependem um do outro para começar). Não dar para quebrar assim
+   já é alerta sobre o escopo.
+2. **Fatia vertical entregável** — o menor caminho ponta a ponta **funcionando** ao fim da janela, mesmo simples.
+   Sem fatia demonstrável, o escopo está errado.
+3. **Complexidade oculta** — autenticação de terceiros, pagamentos, uploads, tempo real, integrações externas,
+   processamento pesado, mobile nativo, infra e deploy. Para cada uma presente, diga como **cortar, simular ou
+   adiar**.
+4. **Stack** — está clara e é dominada? Se precisa ser decidida antes, sinalize como pré-requisito bloqueante.
+5. **Testabilidade (TDD)** — para pelo menos 2 módulos, os **testes críticos** (um de entrada válida e um de caso
+   de erro) escritos antes do código. Se o comportamento essencial é difícil de testar, explique por quê.
+6. **Estimativa realista** — esforço por módulo, soma e comparação com a janela, pessimista onde houver incerteza.
+
+## Veredito
+
+Feche com **um** dos três, justificado em até 3 linhas:
+
+- ✅ **APROVADO** — cabe na janela. Liste em 1 linha os módulos e a fatia vertical alvo e siga para a etapa
+  contexto (`/sincronizar-claude-md`), após confirmação.
+- ✂️ **AJUSTAR** — boa ideia, grande demais. **Reescreva a ideia recortada em 2 a 3 frases**, preservando a
+  essência, pronta para virar SPEC. Diga o que ficou de fora (backlog).
+- ❌ **REPROVAR** — inviável mesmo recortada. Explique o porquê e **proponha uma alternativa no mesmo domínio**
+  que caiba, com a mesma estrutura de módulos.
+
+Com AJUSTAR ou REPROVAR, o `/harness` não avança até o usuário aceitar a nova ideia.

package/templates/skills/memoria/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: memoria
+description: Mostra quem já mexeu num arquivo e por quê — trabalhos anteriores, tipo, status e causa raiz — e aponta regressões candidatas de um bug a partir do histórico registrado nos trabalhos do projeto.
+argument-hint: "[caminho de arquivo ou id de um bug]"
+---
+
+# Memória do projeto
+
+Pergunta: $ARGUMENTS
+
+A memória é um **índice** gerado a partir do frontmatter dos trabalhos em `docs/trabalhos/` e do rastro de eventos.
+Não é busca semântica: toda resposta aponta um trabalho e os documentos dele, e pode ser conferida.
+
+## Passo 1 — Atualizar o índice
+
+```bash
+npx @fontdata/ai-harness memoria
+```
+
+O índice fica em `.ai-harness/memoria/indice.json` (gerado, fora do controle de versão). Artefatos fora do contrato
+aparecem como aviso e não entram no índice.
+
+## Passo 2 — Quem mexeu neste arquivo?
+
+```bash
+npx @fontdata/ai-harness memoria --arquivo <caminho>
+```
+
+A saída lista os trabalhos em ordem cronológica, com tipo, status e causa raiz. Para explicar **por quê**, leia os
+documentos de cada trabalho listado (`SPEC.md`, `PLAN.md`, `DECISOES.md` e relatórios) e cite o trecho.
+
+## Passo 3 — Este bug é regressão?
+
+```bash
+npx @fontdata/ai-harness memoria --regressao <id-do-bug>
+```
+
+Um trabalho anterior que tocou os mesmos arquivos é **coincidência** até que valham as três condições juntas:
+
+1. o arquivo está na **causa raiz** do bug — o campo `arquivos` do trabalho do bug;
+2. a **ordem cronológica** está estabelecida — o trabalho anterior terminou antes de o bug aparecer;
+3. a causa raiz foi **comprovada** — `causa_raiz: comprovada` no `PLAN.md` do bug.
+
+A saída marca cada trabalho como `candidata` ou `descartada`, com o motivo. Mesmo com uma candidata, confirme lendo o
+que o trabalho anterior mudou antes de afirmar a regressão; sem as três condições, diga explicitamente que é
+coincidência.
+
+## Limites
+
+- Só enxerga trabalhos cujo frontmatter segue o contrato e tem `arquivos` preenchido.
+- Sem o rastro nesta máquina, a data de cada trabalho vem da última atualização dos documentos.
+- Conteúdo em **pt-BR**.