@fontdata/ai-harness 2.3.2 → 2.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdata",
-  "version": "2.3.2",
+  "version": "2.5.0",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },
   "commands": ["./templates/commands"],

package/README.md

@@ -103,6 +103,21 @@ npx @fontdata/ai-harness init --comandos resolver-bug,nova-tarefa --sem-harness
 Com o plugin `fontdata@ai-harness` habilitado, o `init` não instala os hooks no projeto, para eles não rodarem
 duas vezes.
 
+### Permissões para o modo auto
+
+O `init` e o `update` gravam em `.claude/settings.json` as permissões que os fluxos usam, para rodarem sem pedir
+aprovação, inclusive no modo auto do Claude Code:
+
+- `permissions.allow`: o rastro, a checagem de conflitos, o `doctor` e a `memoria` do harness; `git add`,
+  `git commit` e `git push` (o `/git-commit-push`); a abertura de sub-agents (`Agent`); e consultas só de leitura
+  (`git status`, `diff`, `log`, `show`, `blame`, `gh pr view`, `gh pr diff`, `npm outdated`...);
+- `permissions.deny`: o push forçado (`--force`, `-f`, `--force-with-lease` e refspec com `+`), que vence o `allow`.
+
+Ficam de fora os comandos de teste e build, que variam por projeto, e os que regravam a instalação (`init`,
+`update`, `migrar`). O projeto acrescenta os seus no próprio `settings.json`; o harness nunca remove regras.
+Nos modos 1 e 2 nada é gravado no projeto: rode `npx @fontdata/ai-harness update --yes` num projeto já instalado,
+ou `init`, para receber as regras.
+
 ## Subcomandos do CLI
 
 | Subcomando | O que faz |
@@ -127,7 +142,7 @@ duas vezes.
 | `docs/trabalhos/<id>/PLAN.md` | Plano: sprints, fases e tasks (as tasks também no frontmatter) |
 | `docs/trabalhos/<id>/DECISOES.md` | Decisões tomadas no planejamento e na execução |
 | `docs/trabalhos/<id>/BLOQUEIOS.md` | Dúvidas que pararam uma task |
-| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `CLIENTE.md` | Relatório para engenharia e para cliente ou gestão |
+| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `CLIENTE.md` | Relatório para engenharia e para cliente e suporte |
 | `docs/eventos/<id>.jsonl` | Rastro de eventos (não versionado por padrão) |
 | `.ai-harness/lock.json` e `config.json` | Lock da instalação e configuração dos hooks (versionar) |
 

package/dist/contratos/artefatos.js

@@ -154,6 +154,9 @@ function validatePlan(file, data) {
     if ('condensado' in data && typeof data.condensado !== 'boolean') {
         problems.push(problem(file, 'formato-invalido', 'condensado deve ser true ou false.'));
     }
+    if ('relatorios_entrega' in data && typeof data.relatorios_entrega !== 'boolean') {
+        problems.push(problem(file, 'formato-invalido', 'relatorios_entrega deve ser true ou false.'));
+    }
     if ('auditoria_plano' in data && !['pendente', 'aprovado', 'reprovado'].includes(String(data.auditoria_plano))) {
         problems.push(problem(file, 'status-invalido', 'auditoria_plano inválida. Use: pendente, aprovado, reprovado.'));
     }
@@ -261,7 +264,10 @@ export function validateWork(root, folderId) {
     const migrated = [...parsed.values()].some((data) => data.migrado === true);
     if (typeof declared === 'string' && !migrated) {
         const required = [...(REQUIRED_BY_WORK_TYPE[declared] ?? [])];
-        if (declared === 'bug' && parsed.get('PLAN.md')?.status === 'concluido') {
+        const plan = parsed.get('PLAN.md');
+        // Feature só exige relatórios quando o plano nasceu com relatorios_entrega; as anteriores ficam como estão.
+        const reportsDue = declared === 'bug' || (declared === 'feature' && plan?.relatorios_entrega === true);
+        if (reportsDue && plan?.status === 'concluido') {
             required.push('relatorios/TECNICO.md', 'relatorios/CLIENTE.md');
         }
         for (const rel of required) {

package/dist/install/plan.js

@@ -7,7 +7,7 @@ import { buildLockItem, LOCK_VERSION, readLock, writeLock } from './lock.js';
 import { HOOKS_ITEM_ID, PROJECT_HOOKS_DIR, projectHooksConfig } from './hooks.js';
 import { neededSkillsFor, resolveSelection } from './selection.js';
 import { COMMENTS_RULE_PATH, commentsHooksConfig, ensureCommentsBaseline } from '../comentarios/instalar.js';
-import { combineHooks, HARNESS_PERMISSIONS, mergeSettings } from './settings.js';
+import { combineHooks, HARNESS_DENY, HARNESS_PERMISSIONS, mergeSettings } from './settings.js';
 /** Rule de convenção com o que é específico do projeto (D-38): é do projeto, então fica fora do lock. */
 export const PROJECT_RULE_PATH = '.claude/rules/harness-projeto.md';
 /** Esqueleto da rule de projeto; os comandos `-legado` renomeados pelo update entram na última seção. */
@@ -161,8 +161,9 @@ export function executePlan(root, plan, pkg, now = new Date()) {
     applyAtomically(root, plan.files);
     const permission = needsEventPermission(plan);
     const hooks = combineHooks(plan.registerHooks ? projectHooksConfig() : {}, plan.registerComments ? commentsHooksConfig() : {});
-    if (Object.keys(hooks).length || permission)
-        mergeSettings(root, { hooks, allow: permission ? HARNESS_PERMISSIONS : [] }, now);
+    if (Object.keys(hooks).length || permission) {
+        mergeSettings(root, { hooks, allow: permission ? HARNESS_PERMISSIONS : [], deny: permission ? HARNESS_DENY : [] }, now);
+    }
     if (plan.registerComments)
         ensureCommentsBaseline(root);
     const items = new Map();
@@ -200,8 +201,11 @@ export function describePlan(plan) {
         lines.push('O CLAUDE.md atual será copiado para CLAUDE.md.bak.');
     if (plan.registerHooks)
         lines.push('Hooks do harness registrados em .claude/settings.json (sem duplicar os existentes).');
-    if (needsEventPermission(plan))
-        lines.push(`Permissões ${HARNESS_PERMISSIONS.join(' e ')} em .claude/settings.json, para o rastro e a checagem de conflitos não pedirem aprovação.`);
+    if (needsEventPermission(plan)) {
+        lines.push(`Permissões ${HARNESS_PERMISSIONS.join(', ')} em .claude/settings.json, para o rastro, a checagem de conflitos, ` +
+            'o /git-commit-push, os sub-agents e as consultas de leitura não pedirem aprovação (inclusive no modo auto); ' +
+            'o push forçado fica bloqueado em permissions.deny.');
+    }
     if (plan.registerComments) {
         lines.push('Padrão de comentários: rule carregada em toda sessão, hook que bloqueia a violação e catraca do legado (gerada só na primeira instalação).');
     }

package/dist/install/settings.js

@@ -5,8 +5,43 @@ export const SETTINGS_PATH = join('.claude', 'settings.json');
 export const EVENT_PERMISSION = 'Bash(npx @fontdata/ai-harness evento:*)';
 /** O /executar-plan checa (e aguarda) conflito de arquivos com outros trabalhos por este comando. */
 export const CONFLICTS_PERMISSION = 'Bash(npx @fontdata/ai-harness conflitos:*)';
+/** O /git-commit-push roda sem confirmação, o que inclui o modo auto do Claude Code. */
+export const GIT_PERMISSIONS = ['Bash(git add:*)', 'Bash(git commit:*)', 'Bash(git push:*)'];
+/** O /executar-plan e as skills de fluxo delegam a sub-agents a cada task e gate. */
+export const AGENT_PERMISSION = 'Agent';
+/**
+ * Comandos só de leitura que as skills, os comandos e os agents rodam. Ficam de fora os que regravam a instalação
+ * (`init`, `update`, `migrar`), os de teste e build, que variam por projeto, e o `npm audit`, cujo prefixo
+ * liberaria também o `npm audit fix`.
+ */
+export const READ_PERMISSIONS = [
+    'Bash(npx @fontdata/ai-harness doctor:*)',
+    'Bash(npx @fontdata/ai-harness memoria:*)',
+    'Bash(git status:*)',
+    'Bash(git diff:*)',
+    'Bash(git log:*)',
+    'Bash(git show:*)',
+    'Bash(git blame:*)',
+    'Bash(git describe:*)',
+    'Bash(git rev-list:*)',
+    'Bash(git rev-parse:*)',
+    'Bash(git remote -v)',
+    'Bash(git symbolic-ref --short refs/remotes/origin/HEAD)',
+    'Bash(gh pr view:*)',
+    'Bash(gh pr diff:*)',
+    'Bash(npm outdated:*)',
+];
 /** Regras de `permissions.allow` que o init e o update gravam para as skills e os agents do harness. */
-export const HARNESS_PERMISSIONS = [EVENT_PERMISSION, CONFLICTS_PERMISSION];
+export const HARNESS_PERMISSIONS = [EVENT_PERMISSION, CONFLICTS_PERMISSION, ...GIT_PERMISSIONS, AGENT_PERMISSION, ...READ_PERMISSIONS];
+/** O push liberado não vale para reescrever o histórico remoto: `deny` vence o `allow`. */
+export const HARNESS_DENY = [
+    'Bash(git push --force:*)',
+    'Bash(git push *--force*)',
+    'Bash(git push -f:*)',
+    'Bash(git push * -f)',
+    'Bash(git push * -f *)',
+    'Bash(git push * +*)',
+];
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -24,12 +59,12 @@ export function combineHooks(...configs) {
     }
     return combined;
 }
-/** A regra já está em `permissions.allow` do `.claude/settings.json` do projeto? */
-export function hasAllowRule(root, rule) {
+/** A regra já está em `permissions.allow` (ou na lista pedida) do `.claude/settings.json` do projeto? */
+export function hasAllowRule(root, rule, key = 'allow') {
     try {
         const settings = JSON.parse(readFileSync(join(root, SETTINGS_PATH), 'utf8'));
-        const allow = settings.permissions?.allow;
-        return Array.isArray(allow) && allow.includes(rule);
+        const list = settings.permissions?.[key];
+        return Array.isArray(list) && list.includes(rule);
     }
     catch {
         return false;
@@ -60,7 +95,11 @@ export function mergeSettings(root, additions, now = new Date()) {
         const invalid = !isPlainObject(parsed) ||
             (parsed.hooks !== undefined && !isPlainObject(parsed.hooks)) ||
             (parsed.permissions !== undefined && !isPlainObject(parsed.permissions)) ||
-            (isPlainObject(parsed.permissions) && parsed.permissions.allow !== undefined && !Array.isArray(parsed.permissions.allow));
+            (isPlainObject(parsed.permissions) &&
+                ['allow', 'deny'].some((key) => {
+                    const list = parsed.permissions[key];
+                    return list !== undefined && !Array.isArray(list);
+                }));
         if (invalid) {
             throw new Error(`O ${SETTINGS_PATH} está com JSON inválido; corrija-o antes de instalar os hooks.`);
         }
@@ -87,17 +126,19 @@ export function mergeSettings(root, additions, now = new Date()) {
         }
         next.hooks = merged;
     }
-    const rules = additions.allow ?? [];
-    if (rules.length) {
-        const permissions = { ...(settings.permissions ?? {}) };
-        const allow = [...(permissions.allow ?? [])];
+    for (const key of ['allow', 'deny']) {
+        const rules = additions[key] ?? [];
+        if (!rules.length)
+            continue;
+        const permissions = { ...(next.permissions ?? {}) };
+        const list = [...(permissions[key] ?? [])];
         for (const rule of rules) {
-            if (allow.includes(rule))
+            if (list.includes(rule))
                 continue;
-            allow.push(rule);
+            list.push(rule);
             changed = true;
         }
-        next.permissions = { ...permissions, allow };
+        next.permissions = { ...permissions, [key]: list };
     }
     if (!changed)
         return { changed: false, backup: null };

package/dist/update/update.js

@@ -9,7 +9,7 @@ import { HOOKS_ITEM_ID, isHarnessPluginEnabled, projectHooksConfig } from '../in
 import { hashContent, LOCK_PATH, LOCK_VERSION, readLock, writeLock } from '../install/lock.js';
 import { itemSources, packageInfo, PROJECT_RULE_PATH, projectRuleContent } from '../install/plan.js';
 import { neededSkillsFor } from '../install/selection.js';
-import { combineHooks, HARNESS_PERMISSIONS, hasAllowRule, mergeSettings } from '../install/settings.js';
+import { combineHooks, HARNESS_DENY, HARNESS_PERMISSIONS, hasAllowRule, mergeSettings } from '../install/settings.js';
 import { adoptLegacyInstall } from './legado.js';
 /** `<id>-legado.md`, com sufixo numérico quando o nome já está em uso. */
 function legacyPath(root, path) {
@@ -108,6 +108,10 @@ export function checkUpdate(root, catalog = loadCatalog(), legacy, home) {
         addItem('rule', 'comentarios', true);
         addItem('hook', 'comentarios', true);
     }
+    const permissoesFaltando = [
+        ...HARNESS_PERMISSIONS.filter((rule) => !hasAllowRule(root, rule)),
+        ...HARNESS_DENY.filter((rule) => !hasAllowRule(root, rule, 'deny')).map((rule) => `deny ${rule}`),
+    ];
     return {
         changes,
         lock,
@@ -115,7 +119,8 @@ export function checkUpdate(root, catalog = loadCatalog(), legacy, home) {
         adotada,
         registrarHooks: adotada && !pluginHooks,
         registrarComentarios: adotada,
-        permissaoAusente: !HARNESS_PERMISSIONS.every((rule) => hasAllowRule(root, rule)),
+        permissaoAusente: permissoesFaltando.length > 0,
+        permissoesFaltando,
     };
 }
 /**
@@ -154,7 +159,7 @@ export function applyUpdate(root, report, options, pkg, now = new Date()) {
         return { de: path, para };
     });
     const hooks = combineHooks(report.registrarHooks ? projectHooksConfig() : {}, report.registrarComentarios ? commentsHooksConfig() : {});
-    mergeSettings(root, { hooks, allow: HARNESS_PERMISSIONS }, now);
+    mergeSettings(root, { hooks, allow: HARNESS_PERMISSIONS, deny: HARNESS_DENY }, now);
     if (report.registrarComentarios)
         ensureCommentsBaseline(root);
     if (report.adotada) {
@@ -220,7 +225,11 @@ export function describeUpdate(report) {
                 'a rule de projeto e a permissão do `ai-harness evento`.',
         ]
         : [];
-    const permission = report.permissaoAusente && !report.adotada ? [`Faltam permissões do harness (${HARNESS_PERMISSIONS.join(', ')}) em .claude/settings.json; o --yes as acrescenta.`] : [];
+    const permission = report.permissaoAusente && !report.adotada
+        ? [
+            `Faltam permissões do harness em .claude/settings.json (${report.permissoesFaltando.join(', ')}); o --yes as acrescenta.`,
+        ]
+        : [];
     if (!report.changes.length) {
         const status = adopted.length || permission.length ? 'Nenhum arquivo a atualizar.' : 'A instalação está em dia: nenhum arquivo a atualizar.';
         return [...adopted, ...permission, status].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fontdata/ai-harness",
-  "version": "2.3.2",
+  "version": "2.5.0",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code: roda os slash commands direto na pasta do projeto via npx, sem instalar nada — ou instala-os em .claude/commands.",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -26,7 +26,7 @@ Comece por `/harness`, que conduz o setup em etapas.
 | `docs/trabalhos/<id>/PLAN.md` | Plano: sprints, fases e tasks (as tasks também no frontmatter) |
 | `docs/trabalhos/<id>/DECISOES.md` | Decisões tomadas no planejamento e na execução |
 | `docs/trabalhos/<id>/BLOQUEIOS.md` | Dúvidas que pararam uma task |
-| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `relatorios/CLIENTE.md` | Relatório para engenharia e para cliente ou gestão |
+| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `relatorios/CLIENTE.md` | Relatório para engenharia e para cliente e suporte (sem jargão) |
 | `docs/eventos/<id>.jsonl` | Rastro de eventos (não versionado por padrão) |
 | `.ai-harness/` | Lock da instalação e configuração dos hooks (versionar) |
 

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

@@ -116,15 +116,32 @@ portões extras (com os achados IMPORTANTE e SUGESTÃO do `code-reviewer`), esta
    npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome executar-plan
    ```
 
-2. Retire `<id>` da lista `trabalhos_ativos` de `.ai-harness/estado.json`, lendo o arquivo logo antes de gravar
+2. **Relatórios da entrega** (só trabalho do tipo `feature`; o de `bug` é escrito pelo `/resolver-bug`). Siga
+   `references/relatorios-da-entrega.md` e grave, a partir dos templates:
+
+   - **`relatorios/CLIENTE.md`** (`templates/relatorios/CLIENTE.md`): o que há de novo, para quem, o que preparar,
+     como usar, situações comuns e o que ainda não faz — **sem jargão técnico**. É o texto entregue ao cliente e
+     aos técnicos de suporte.
+   - **`relatorios/TECNICO.md`** (`templates/relatorios/TECNICO.md`): onde está no código, configuração e
+     implantação, testes que protegem e o diagnóstico para o suporte.
+
+   Preencha `arquivos` com os arquivos tocados, grave `status: final` e registre cada um:
+
+   ```bash
+   npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome executar-plan --dados '{"caminho":"docs/trabalhos/<id>/relatorios/CLIENTE.md"}'
+   npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome executar-plan --dados '{"caminho":"docs/trabalhos/<id>/relatorios/TECNICO.md"}'
+   ```
+
+3. Retire `<id>` da lista `trabalhos_ativos` de `.ai-harness/estado.json`, lendo o arquivo logo antes de gravar
    e preservando os ids das outras sessões.
-3. Com bloqueios abertos, apresente cada um ao usuário. Cada resposta vira decisão em `DECISOES.md`
+4. 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** modifique `SPEC.md`, `CLAUDE.md` nem o conteúdo do plano — só o status das tasks e do plano. Os
+  relatórios da entrega são arquivos novos, não alteração 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/relatorios-da-entrega.md

@@ -0,0 +1,51 @@
+# Relatórios da entrega
+
+Ao concluir um trabalho do tipo `feature`, o orquestrador entrega dois relatórios. Eles são escritos **depois** da
+execução, a partir do que foi de fato entregue, não do que foi planejado.
+
+| Relatório | Quem lê | Para quê |
+|---|---|---|
+| `relatorios/CLIENTE.md` | cliente e técnico de suporte | saber o que mudou, como usar e o que responder |
+| `relatorios/TECNICO.md` | engenharia e suporte avançado | manter, implantar e diagnosticar |
+
+## De onde tirar o conteúdo
+
+1. **`SPEC.md`**, seção *Como vai operar*: perfis, preparação, passo a passo e dúvidas previsíveis.
+2. **O código entregue** (diff do trabalho): nomes reais de telas, botões, mensagens e parâmetros. Onde o código
+   diverge da `SPEC.md`, vale o código, e a divergência entra em *Pendências e riscos* do `TECNICO.md`.
+3. **`DECISOES.md`**: regras de negócio escolhidas durante o trabalho que mudam o comportamento para quem usa.
+4. **`BLOQUEIOS.md`** e *Fora do escopo* da `SPEC.md`: o que **não** foi entregue vai para *O que ainda não faz*.
+
+Não invente passo, mensagem ou tela que não esteja no código. Sem informação para uma seção, escreva o que falta
+e avise o usuário no encerramento em vez de preencher com suposição.
+
+## Como escrever o relatório para o cliente
+
+O mesmo texto vai para o cliente e para o técnico de suporte: ele precisa bastar para o técnico atender um
+chamado sem abrir o código. O hook `sem-jargao` avisa quando aparecem termos técnicos.
+
+- Frases curtas, voz ativa, sem siglas.
+- Use os nomes como aparecem na tela, entre aspas: clique em "Salvar pedido".
+- Troque o termo técnico pelo efeito: em vez de "o endpoint retorna 404", "o sistema avisa que o pedido não foi
+  encontrado".
+- Não cite arquivos, funções, versões, commits ou nomes de sistema interno.
+- Em *Situações comuns*, liste as mensagens de aviso e erro que a funcionalidade mostra, com o texto exato.
+- Em *Perguntas frequentes*, parta das dúvidas previsíveis da `SPEC.md` e das regras de `DECISOES.md`.
+
+## Diagnóstico para o suporte (relatório técnico)
+
+Para cada situação comum do relatório para o cliente, diga onde o técnico confirma a causa: o log, a tela de
+configuração, o parâmetro ou o registro a conferir. É a ponte entre o que o cliente relata e o que engenharia
+precisaria investigar.
+
+## Exemplo — relatório para o cliente
+
+> **O que há de novo.** Agora é possível consultar um pedido direto pelo número, sem percorrer a lista inteira.
+>
+> **Antes de começar.** Não é preciso preparar nada.
+>
+> **Como usar.** 1. No menu "Pedidos", clique em "Consultar". 2. Digite o número do pedido. 3. O sistema mostra os
+> itens, o frete e o total.
+>
+> **Situações comuns.** "Pedido não encontrado": o número não existe ou foi digitado errado — confira o número no
+> comprovante do cliente.

package/templates/skills/executar-plan/templates/relatorios/CLIENTE.md

@@ -0,0 +1,51 @@
+---
+schema_versao: 1
+tipo: relatorio_cliente
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## O que há de novo
+
+Em duas ou três frases, o que a pessoa passa a conseguir fazer e por que isso ajuda.
+
+## Para quem é
+
+Perfis e setores que vão usar, e onde a funcionalidade aparece (tela, menu, relatório).
+
+## Antes de começar
+
+Permissão, parâmetro, cadastro ou configuração que precisa estar pronto, e quem faz isso — ou "Não é preciso
+preparar nada".
+
+## Como usar
+
+1. Primeiro passo, com o nome da tela ou do botão como aparece para quem usa.
+2. Próximo passo.
+3. O resultado esperado ao final.
+
+## O que muda no que você já fazia
+
+Telas, relatórios ou rotinas que passam a se comportar diferente — ou "Nada muda no que já existia".
+
+## Situações comuns
+
+| O que aparece ou acontece | O que significa | O que fazer |
+|---|---|---|
+| Mensagem ou situação | Explicação simples | Ação recomendada |
+
+## O que ainda não faz
+
+O que ficou para depois, para ninguém prometer ao cliente o que não foi entregue.
+
+## Perguntas frequentes
+
+**Pergunta que o suporte provavelmente vai ouvir?**
+Resposta curta.

package/templates/skills/executar-plan/templates/relatorios/TECNICO.md

@@ -0,0 +1,44 @@
+---
+schema_versao: 1
+tipo: relatorio_tecnico
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Relatório técnico — {{titulo}}
+
+## O que foi entregue
+
+Resumo do comportamento implementado, com referência aos critérios de aceite do `SPEC.md`.
+
+## Onde está no código
+
+Módulos, arquivos e pontos de entrada, com `arquivo:linha`.
+
+## Configuração e implantação
+
+Variáveis de ambiente, migrações, permissões, parâmetros e a ordem de implantação — ou "nenhuma".
+
+## Decisões
+
+As decisões de `DECISOES.md` que afetam quem mantém ou dá suporte, com o id (`D-NN`).
+
+## Testes que protegem
+
+- Testes críticos: caminho e o que cada um verifica.
+- Suíte completa: comando e resultado.
+
+## Diagnóstico para o suporte
+
+| Sintoma relatado | Onde olhar | Causa provável |
+|---|---|---|
+| O que o cliente diz | Log, tela, tabela ou parâmetro | O que costuma estar errado |
+
+## Pendências e riscos
+
+Itens fora do escopo, bloqueios resolvidos com ressalva e pontos de atenção.

package/templates/skills/nova-tarefa/SKILL.md

@@ -37,8 +37,11 @@ os trabalhos que já os tocaram e por quê.
 
 ## Passo 2 — Recorte
 
-- **Nova tarefa:** faça de 2 a 3 perguntas, uma por vez, para entender o que deve ser feito.
-- Resuma o que foi entendido (o que entra, o que fica fora, critérios de aceite) e **aguarde aprovação**.
+- **Nova tarefa:** faça de 2 a 3 perguntas, uma por vez, para entender o que deve ser feito. Uma delas cobre a
+  **operação**: quem vai usar, o que precisa estar configurado ou liberado antes e o que muda no que as pessoas já
+  fazem. Pule a pergunta só quando o pedido já responder.
+- Resuma o que foi entendido (o que entra, o que fica fora, critérios de aceite, como vai operar) e **aguarde
+  aprovação**.
 
 Toda ambiguidade que você resolver por conta própria vira decisão registrada (Passo 5), sempre com a escolha
 mais conservadora.
@@ -48,6 +51,8 @@ mais conservadora.
 1. Defina o id `AAAA-MM-DD-<slug>` (data de hoje, slug curto em minúsculas, sem acento).
 2. Crie `docs/trabalhos/<id>/SPEC.md` a partir de `templates/SPEC.md`, preenchendo `{{id}}`, `{{titulo}}` e
    `{{data}}`. Os nomes dos arquivos da pasta são sempre em caixa alta.
+   A seção **Como vai operar** é obrigatória: é dela que o `/executar-plan` tira o relatório para o cliente e para
+   o suporte. Funcionalidade sem efeito visível para quem usa (ajuste interno, rotina técnica) diz isso na seção.
 3. Registre o início do trabalho:
 
    ```bash
@@ -63,6 +68,8 @@ Crie `docs/trabalhos/<id>/PLAN.md` a partir de `templates/PLAN.md`, seguindo `re
 - tasks paralelizáveis da mesma fase não tocam os mesmos arquivos;
 - `arquivos` do frontmatter lista todos os arquivos (ou pastas) que as tasks vão criar ou alterar — é por ele que
   o `/executar-plan` impede dois trabalhos de mexerem no mesmo código ao mesmo tempo;
+- `relatorios_entrega: true` fica no frontmatter, como vem do template: com ela, o `doctor` exige
+  `relatorios/TECNICO.md` e `relatorios/CLIENTE.md` quando o plano chega a `concluido`;
 - **plano condensado:** com 1 sprint e 1 fase, use `condensado: true` e omita os títulos de sprint e fase — o
   contrato das tasks continua completo.
 
@@ -85,7 +92,8 @@ npx @fontdata/ai-harness evento decisao_registrada --trabalho <id> --nome nova-t
 ## Passo 7 — 🚦 GATE de aprovação
 
 Mostre ao usuário: os caminhos gravados, as tasks por fase (quais rodam em paralelo), quantos agents serão
-necessários e as decisões registradas. **Peça aprovação explícita.**
+necessários, as decisões registradas e o resumo de **como vai operar**. Avise que, ao concluir, o `/executar-plan`
+entrega `relatorios/TECNICO.md` e `relatorios/CLIENTE.md`. **Peça aprovação explícita.**
 
 - Com aprovação, grave `status: aprovado` no `SPEC.md`.
 - **Start inicial (fluxo `/harness`):** o próximo passo normalmente é a etapa scaffold do `/harness` — **não** dispare a execução.

package/templates/skills/nova-tarefa/templates/PLAN.md

@@ -11,6 +11,7 @@ arquivos: []
 condensado: false
 auditoria_plano: pendente
 causa_raiz: null
+relatorios_entrega: true
 tasks:
   - id: T-01.01
     titulo: "Nome curto da primeira task"

package/templates/skills/nova-tarefa/templates/SPEC.md

@@ -24,6 +24,17 @@ Conclusão (não existe, existe parcialmente ou já existe) e a evidência encon
 
 - Comportamento 1, descrito do ponto de vista de quem usa.
 
+## Como vai operar
+
+Base do relatório para o cliente, escrito no encerramento do `/executar-plan`. Responda do ponto de vista de quem
+usa o sistema e de quem dá suporte.
+
+- **Quem usa:** perfis, telas ou menus onde a funcionalidade aparece.
+- **Antes de usar:** permissão, parâmetro, cadastro ou configuração necessários — ou "nada".
+- **Passo a passo esperado:** o caminho principal, em poucas etapas.
+- **O que muda no que já existe:** telas, relatórios ou rotinas que passam a se comportar diferente.
+- **Dúvidas previsíveis:** o que o suporte provavelmente vai ouvir e a resposta.
+
 ## Fora do escopo
 
 - O que fica explicitamente para depois.