agent-quality-police 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-police",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Strict governance framework for coding agents that blocks testing and typing bypasses.",
   "author": {
     "name": "Davy Massoneto",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-police",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Strict governance framework for coding agents that blocks testing and typing bypasses.",
   "author": {
     "name": "Davy Massoneto",

package/AGENTS.md

@@ -13,6 +13,7 @@
 2. Leia [quality-definition](docs/policy/quality-definition.md) quando a tarefa precisar de contexto de política do repositório.
 3. Leia [workflow](docs/policy/workflow.md) quando o repositório definir um.
 4. Carregue o menor conjunto de skills exigido a partir de `skills/` antes de propor edits ou escrever código.
+5. Para mudanças de código, o agent principal coordena; a execução deve passar por `implementer`.
 
 ## Roteamento de Skills
 
@@ -35,6 +36,7 @@
 - Contratos públicos devem manter uma forma estável de topo; não retorne uniões como `T[] | { data: T[]; total: number }`.
 - Arquivos de responsabilidade única são exigidos: uma classe por arquivo sem funções de topo irmãs, ou múltiplas funções exportadas apenas quando o nome do arquivo nomeia uma responsabilidade compartilhada.
 - Nomes genéricos como `helpers.ts`, `utils.ts`, `common.ts` ou `shared.ts` são falhas automáticas quando escondem a razão para mudar.
+- Quando houver mudança de código, a execução deve passar pelo `implementer`; edição direta pelo agent principal é bloqueio.
 - Não invente arquivos, APIs, imports, chaves de config ou comportamento de biblioteca; verifique com ferramenta primeiro.
 - Quando incerto, pare e pergunte ao usuário em vez de adivinhar.
 - Cite a fonte (`arquivo:linha`, URL oficial ou quote literal do usuário) para cada escolha não trivial de implementação.
@@ -42,10 +44,12 @@
 
 ## Fluxo de Revisão
 
+- Para mudanças de código, execute a implementação via `implementer`; o agent principal coordena, não substitui esse papel.
 - Para mudanças de código, invoque explicitamente os auditores exigidos antes da aprovação final.
 - Para mudanças de código, não finalize até que os auditores exigidos tenham rodado e seus resultados tenham sido revisados.
 - Não substitua invocação de agent de auditoria nominal por autorreview inline.
+- Antes de commit, push, merge request, release ou aprovação, valide os receipts exigidos em `.aqp/receipts/`.
 - Para tipagem, config, mocks, helpers ou diffs suspeitos, rode `bypass-auditor`.
 - Para mudanças de comportamento ou bug fixes, rode `tdd-warden` e `bypass-auditor`.
 - Para aprovação final, release ou decisão de merge, rode `pr-gatekeeper` após os demais auditores exigidos.
-- Se uma skill ou auditor exigido não puder rodar no runtime atual, pare e reporte `BLOCKED`.
+- Se `implementer`, algum auditor exigido, ou a validação de receipts não puder rodar no runtime atual, pare e reporte `BLOCKED`.

package/CLAUDE.md

@@ -13,6 +13,7 @@
 2. Leia [quality-definition](docs/policy/quality-definition.md) quando a tarefa precisar de contexto de política do repositório.
 3. Leia [workflow](docs/policy/workflow.md) quando o repositório definir um.
 4. Carregue o menor conjunto de skills exigido a partir de `skills/` antes de propor edits ou escrever código.
+5. Para mudanças de código, o agent principal coordena; a execução deve passar por `implementer`.
 
 ## Roteamento de Skills
 
@@ -35,6 +36,7 @@
 - Contratos públicos devem manter uma forma estável de topo; não retorne uniões como `T[] | { data: T[]; total: number }`.
 - Arquivos de responsabilidade única são exigidos: uma classe por arquivo sem funções de topo irmãs, ou múltiplas funções exportadas apenas quando o nome do arquivo nomeia uma responsabilidade compartilhada.
 - Nomes genéricos como `helpers.ts`, `utils.ts`, `common.ts` ou `shared.ts` são falhas automáticas quando escondem a razão para mudar.
+- Quando houver mudança de código, a execução deve passar pelo `implementer`; edição direta pelo agent principal é bloqueio.
 - Não invente arquivos, APIs, imports, chaves de config ou comportamento de biblioteca; verifique com ferramenta primeiro.
 - Quando incerto, pare e pergunte ao usuário em vez de adivinhar.
 - Cite a fonte (`arquivo:linha`, URL oficial ou quote literal do usuário) para cada escolha não trivial de implementação.
@@ -42,10 +44,12 @@
 
 ## Fluxo de Revisão
 
+- Para mudanças de código, execute a implementação via `implementer`; o agent principal coordena, não substitui esse papel.
 - Para mudanças de código, invoque explicitamente os auditores exigidos antes da aprovação final.
 - Para mudanças de código, não finalize até que os auditores exigidos tenham rodado e seus resultados tenham sido revisados.
 - Não substitua invocação de agent de auditoria nominal por autorreview inline.
+- Antes de commit, push, merge request, release ou aprovação, valide os receipts exigidos em `.aqp/receipts/`.
 - Para tipagem, config, mocks, helpers ou diffs suspeitos, rode `bypass-auditor`.
 - Para mudanças de comportamento ou bug fixes, rode `tdd-warden` e `bypass-auditor`.
 - Para aprovação final, release ou decisão de merge, rode `pr-gatekeeper` após os demais auditores exigidos.
-- Se uma skill ou auditor exigido não puder rodar no runtime atual, pare e reporte `BLOCKED`.
+- Se `implementer`, algum auditor exigido, ou a validação de receipts não puder rodar no runtime atual, pare e reporte `BLOCKED`.

package/bin/aqp.mjs

@@ -6,6 +6,7 @@ import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 import { installGlobal, supportedTargets } from "../lib/install.mjs";
+import { validateRequiredReceipts } from "../lib/receipts.mjs";
 import { formatInstallResult } from "../lib/cli-output.mjs";
 
 function usage() {
@@ -13,7 +14,8 @@ function usage() {
     [
       "Usage:",
       "  aqp install",
-      "  aqp install --targets claude,codex,opencode [--manage-global-root claude,codex] [--home <dir>] [--json]"
+      "  aqp install --targets claude,codex,opencode [--manage-global-root claude,codex] [--home <dir>] [--json]",
+      "  aqp validate-receipts --repo <dir> --required implementer,bypass-auditor,tdd-warden,pr-gatekeeper [--json]"
     ].join("\n")
   );
 }
@@ -63,6 +65,54 @@ async function main(argv) {
     return 0;
   }
 
+  if (command === "validate-receipts") {
+    let repoRoot;
+    let requiredAgents;
+    let useJson = false;
+
+    for (let index = 0; index < rest.length; index += 1) {
+      const current = rest[index];
+      if (current === "--repo") {
+        repoRoot = rest[index + 1];
+        index += 1;
+        continue;
+      }
+      if (current === "--required") {
+        requiredAgents = parseCommaList(rest[index + 1]);
+        index += 1;
+        continue;
+      }
+      if (current === "--json") {
+        useJson = true;
+        continue;
+      }
+      throw new Error(`Unknown argument: ${current}`);
+    }
+
+    if (!repoRoot || !requiredAgents || requiredAgents.length === 0) {
+      usage();
+      return 1;
+    }
+
+    const result = await validateRequiredReceipts(path.resolve(repoRoot), requiredAgents);
+    if (useJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.valid) {
+      console.log("receipts-ok");
+    } else {
+      if (result.missing.length > 0) {
+        console.log(`Missing receipts: ${result.missing.join(", ")}`);
+      }
+      for (const entry of result.invalid) {
+        console.log(`Invalid receipt: ${entry.agent}`);
+        for (const error of entry.errors) {
+          console.log(`- ${error}`);
+        }
+      }
+    }
+    return result.valid ? 0 : 1;
+  }
+
   if (command !== "install") {
     usage();
     return 1;

package/docs/policy/quality-definition.md

@@ -4,6 +4,8 @@
 
 Qualidade neste framework não é "o build passou". Qualidade significa que a mudança é provada em comportamento, tem tipagem honesta, escopo estreito, organização em que cada arquivo tem uma razão para mudar, e é revisável sem trabalho de investigação.
 
+Quando o runtime suporta agents nominais e enforcement local, qualidade também exige trilho operacional: mudança de código executada pelo papel de execução correto, gates auditáveis e receipts rastreáveis antes de commit, push, merge request, release ou aprovação.
+
 Qualidade também exige grounding: cada afirmação e decisão precisa estar ancorada em instrução explícita do usuário, em código ou documentação do repositório, ou em documentação oficial consultada no momento da tarefa. Dados de treinamento não são fonte de verdade.
 
 ## Teste Válido
@@ -106,6 +108,8 @@ Rejeitar imediatamente quando um diff introduz qualquer um dos itens abaixo, a m
 - branching que altera semântica de runtime sem justificativa de produto ou domínio
 - qualquer código cuja correção dependa de inferência não verificada (comportamento de biblioteca, formato de API, layout de arquivo, intenção do usuário) sem citação
 - qualquer afirmação sobre o repositório, biblioteca ou usuário apresentada sem citação, resultado de ferramenta ou quote literal
+- mudança de código executada fora do `implementer` quando o runtime suporta agent nominal para execução
+- aprovação, commit, push, merge request ou release sem validação dos receipts exigidos em `.aqp/receipts/` quando o runtime suporta receipts
 
 ## Refactor Seguro
 

package/docs/policy/receipt-contract.md

@@ -0,0 +1,48 @@
+# Contrato de Receipts
+
+Receipts são artefatos locais que provam que um papel nominal do framework realmente rodou.
+
+## Localização
+
+- Diretório padrão: `.aqp/receipts/`
+- Um arquivo JSON por agent nominal
+
+## Arquivos Esperados
+
+- `.aqp/receipts/implementer.json`
+- `.aqp/receipts/bypass-auditor.json`
+- `.aqp/receipts/tdd-warden.json`
+- `.aqp/receipts/pr-gatekeeper.json`
+
+## Forma Mínima
+
+```json
+{
+  "schemaVersion": 1,
+  "agent": "implementer",
+  "verdict": "COMPLETED",
+  "task": "short task summary",
+  "timestamp": "2026-04-21T12:34:56.000Z"
+}
+```
+
+## Campos Obrigatórios
+
+- `schemaVersion`: inteiro; atualmente `1`
+- `agent`: nome nominal do agent que executou o passo
+- `verdict`: resultado final daquele agent
+- `task`: resumo curto da tarefa auditada ou implementada
+- `timestamp`: timestamp ISO 8601
+
+## Verdicts Aceitos por Agent
+
+- `implementer` → `COMPLETED`
+- `bypass-auditor` → `PASS`
+- `tdd-warden` → `PASS`
+- `pr-gatekeeper` → `APPROVED`
+
+## Regra de Falha Fechada
+
+- Se um receipt exigido está ausente, o gate falha.
+- Se o receipt existe mas não bate com o agent ou com o verdict esperado, o gate falha.
+- Se o runtime não consegue emitir o receipt exigido, o workflow deve parar em `BLOCKED`.

package/docs/policy/runtime-notes.md

@@ -11,6 +11,7 @@ Fontes oficiais consultadas: `https://developers.openai.com/codex/guides/agents-
 - Subagents em `.claude/agents/<nome>.md`. Skills em `.claude/skills/<skill-name>/SKILL.md` (project), `~/.claude/skills/...` (personal) ou `<plugin>/skills/...` (plugin). Custom commands vivem em `.claude/commands/` e estão sendo unificados com skills.
 - Suporta ferramentas estruturadas como `Read`, `Grep`, `Glob`, `WebFetch`, `Task`, `Skill` e integrações MCP. Nomes exatos de ferramentas variam por versão; confirme antes de chamar.
 - Memória persistente `~/.claude/projects/<project>/memory/MEMORY.md` (auto memory) precisa ser tratada como cache verificável, não como fonte de verdade.
+- Claude Code suporta hooks de subagent e `PreToolUse`, o que permite enforcement mais forte de runtime para bloquear operações sem receipt ou fora do papel esperado.
 
 ## Codex
 
@@ -26,6 +27,7 @@ Fontes oficiais consultadas: `https://developers.openai.com/codex/guides/agents-
 - Diretrizes vagas como "não alucine" são inúteis. Apenas regras concretas e verificáveis (por exemplo, "verifique com `Read` antes de afirmar que o arquivo existe") são aplicáveis.
 - Nunca divida a mesma regra em arquivos divergentes entre Claude Code e Codex. Regras canônicas vivem em `framework/rules/` e `docs/policy/`. Ambos os runtimes consomem a mesma projeção gerada.
 - Os arquivos `framework/rules/claude-code-specific.md` e `framework/rules/codex-specific.md` contêm apenas diferenças de runtime (discovery, ferramentas, limites). Política comportamental fica nos demais rules.
+- Se um runtime não suporta o enforcement operacional exigido pelo projeto, o comportamento correto é `BLOCKED`, não fallback silencioso para confiança textual.
 
 ## Projeções Geradas
 

package/docs/policy/system-layout.md

@@ -5,6 +5,7 @@
 - `framework/entrypoints/`: fonte canônica para prompts gerados e entrypoints do pacote
 - `docs/policy/quality-definition.md`: significado canônico de qualidade
 - `docs/policy/workflow.md`: sequência canônica de execução
+- `docs/policy/receipt-contract.md`: contrato canônico dos receipts operacionais
 - `docs/policy/runtime-notes.md`: notas canônicas de diferenças entre runtimes (Claude Code e Codex)
 - `framework/rules/`: regras canônicas sempre ativas
 - `framework/skills/`: fonte canônica das skills

package/docs/policy/workflow.md

@@ -7,13 +7,15 @@
 3. Leia `AGENTS.md` e `docs/policy/quality-definition.md`.
 4. Carregue a skill ou o conjunto de skills relevante.
 5. Defina o comportamento a ser provado.
-6. Escreva ou ajuste o teste que falha primeiro, quando testes forem viáveis.
-7. Implemente o mínimo de código necessário para passar.
-8. Refatore sem alterar o comportamento provado.
-9. Rode os agents de auditoria apropriados.
-10. Valide o repositório antes de commit ou publicação.
+6. Se a tarefa exige mudança de código, o agent principal coordena; a execução deve passar pelo `implementer`.
+7. Escreva ou ajuste o teste que falha primeiro, quando testes forem viáveis.
+8. Implemente o mínimo de código necessário para passar.
+9. Refatore sem alterar o comportamento provado.
+10. Rode os agents de auditoria apropriados.
+11. Valide os receipts exigidos em `.aqp/receipts/` antes de commit, push, merge request, release ou publicação.
+12. Valide o repositório antes de commit ou publicação.
 
-Autorreview inline não satisfaz requisito de auditoria. Quando um agent de auditoria é exigido, invoque o agent nominal. Se o agent exigido não puder rodar, reporte `BLOCKED` em vez de declarar conclusão.
+Autorreview inline não satisfaz requisito de auditoria. Quando um agent de auditoria é exigido, invoque o agent nominal. Se o `implementer`, algum auditor exigido, ou a validação de receipts não puder rodar, reporte `BLOCKED` em vez de declarar conclusão.
 
 ## Regra de Grounding
 
@@ -24,10 +26,18 @@ Autorreview inline não satisfaz requisito de auditoria. Quando um agent de audi
 
 ## Pareamento Obrigatório de Auditoria
 
+- Mudança de código: execute via `implementer`.
 - Mudança de TypeScript ou heavy em config: rode `bypass-auditor`.
 - Novo comportamento ou correção de bug com testes: rode `tdd-warden` e `bypass-auditor`.
 - Decisão final de merge ou publicação: rode `pr-gatekeeper`.
 
+## Contrato de Receipts
+
+- Receipts vivem em `.aqp/receipts/`.
+- Cada gate nominal exigido deve deixar um receipt JSON correspondente antes de commit, push, merge request, release ou aprovação.
+- Mínimo esperado por agent: `implementer`, `bypass-auditor`, `tdd-warden`, `pr-gatekeeper`.
+- Se o runtime ainda não consegue materializar o receipt exigido, a tarefa fica `BLOCKED` em vez de seguir por confiança textual.
+
 ## Manutenção do Repositório
 
 - Edite primeiro as fontes canônicas de política e skill.

package/lib/install.mjs

@@ -215,7 +215,8 @@ function globalPolicySections() {
       "1. Confirme literalmente o pedido do usuário; se ambíguo, pergunte antes de começar.",
       "2. Leia [quality-definition]({{quality_definition_path}}) quando a tarefa precisar de contexto de política do repositório.",
       "3. Leia [workflow]({{workflow_path}}) quando o repositório definir um.",
-      "4. Carregue o menor conjunto de skills exigido a partir de `{{primary_skill_root}}` antes de propor edits ou escrever código."
+      "4. Carregue o menor conjunto de skills exigido a partir de `{{primary_skill_root}}` antes de propor edits ou escrever código.",
+      "5. Para mudanças de código, o agent principal coordena; a execução deve passar por `implementer`."
     ].join("\n"),
     skillRoutingBody: [
       "- Use [grounding-first]({{grounding_first_skill_path}}) sempre que a tarefa exigir afirmação factual sobre repositório, biblioteca ou intenção do usuário.",
@@ -236,19 +237,22 @@ function globalPolicySections() {
       "- Contratos públicos devem manter uma forma estável de topo; não retorne uniões como `T[] | { data: T[]; total: number }`.",
       "- Arquivos de responsabilidade única são exigidos: uma classe por arquivo sem funções de topo irmãs, ou múltiplas funções exportadas apenas quando o nome do arquivo nomeia uma responsabilidade compartilhada.",
       "- Nomes genéricos como `helpers.ts`, `utils.ts`, `common.ts` ou `shared.ts` são falhas automáticas quando escondem a razão para mudar.",
+      "- Quando houver mudança de código, a execução deve passar pelo `implementer`; edição direta pelo agent principal é bloqueio.",
       "- Não invente arquivos, APIs, imports, chaves de config ou comportamento de biblioteca; verifique com ferramenta primeiro.",
       "- Quando incerto, pare e pergunte ao usuário em vez de adivinhar.",
       "- Cite a fonte (`arquivo:linha`, URL oficial ou quote literal do usuário) para cada escolha não trivial de implementação.",
       "- Prefira tipos nomeados e modelos explícitos em vez de atalhos estruturais inline."
     ].join("\n"),
     reviewFlowBody: [
+      "- Para mudanças de código, execute a implementação via `implementer`; o agent principal coordena, não substitui esse papel.",
       "- Para mudanças de código, invoque explicitamente os auditores exigidos antes da aprovação final.",
       "- Para mudanças de código, não finalize até que os auditores exigidos tenham rodado e seus resultados tenham sido revisados.",
       "- Não substitua invocação de agent de auditoria nominal por autorreview inline.",
+      "- Antes de commit, push, merge request, release ou aprovação, valide os receipts exigidos em `.aqp/receipts/`.",
       "- Para tipagem, config, mocks, helpers ou diffs suspeitos, rode `bypass-auditor`.",
       "- Para mudanças de comportamento ou bug fixes, rode `tdd-warden` e `bypass-auditor`.",
       "- Para aprovação final, release ou decisão de merge, rode `pr-gatekeeper` após os demais auditores exigidos.",
-      "- Se uma skill ou auditor exigido não puder rodar no runtime atual, pare e reporte `BLOCKED`."
+      "- Se `implementer`, algum auditor exigido, ou a validação de receipts não puder rodar no runtime atual, pare e reporte `BLOCKED`."
     ].join("\n")
   };
 }

package/lib/receipts.mjs

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const RECEIPT_DIRECTORY = path.join(".aqp", "receipts");
+
+export const REQUIRED_VERDICTS = {
+  "implementer": "COMPLETED",
+  "bypass-auditor": "PASS",
+  "tdd-warden": "PASS",
+  "pr-gatekeeper": "APPROVED"
+};
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function receiptPath(repoRoot, agent) {
+  return path.join(repoRoot, RECEIPT_DIRECTORY, `${agent}.json`);
+}
+
+export async function loadReceipt(repoRoot, agent) {
+  const raw = await readFile(receiptPath(repoRoot, agent), "utf8");
+  return JSON.parse(raw);
+}
+
+export function validateReceipt(agent, receipt) {
+  if (!isObject(receipt)) {
+    return ["Receipt must be a JSON object."];
+  }
+
+  const errors = [];
+  if (receipt.schemaVersion !== 1) {
+    errors.push("schemaVersion must be 1.");
+  }
+  if (receipt.agent !== agent) {
+    errors.push(`agent must equal ${agent}.`);
+  }
+  if (typeof receipt.task !== "string" || receipt.task.trim().length === 0) {
+    errors.push("task must be a non-empty string.");
+  }
+  if (typeof receipt.timestamp !== "string" || Number.isNaN(Date.parse(receipt.timestamp))) {
+    errors.push("timestamp must be a valid ISO 8601 string.");
+  }
+
+  const requiredVerdict = REQUIRED_VERDICTS[agent];
+  if (!requiredVerdict) {
+    errors.push(`Unknown agent: ${agent}.`);
+  } else if (receipt.verdict !== requiredVerdict) {
+    errors.push(`verdict must equal ${requiredVerdict}.`);
+  }
+
+  return errors;
+}
+
+export async function validateRequiredReceipts(repoRoot, requiredAgents) {
+  const missing = [];
+  const invalid = [];
+
+  for (const agent of requiredAgents) {
+    try {
+      const receipt = await loadReceipt(repoRoot, agent);
+      const errors = validateReceipt(agent, receipt);
+      if (errors.length > 0) {
+        invalid.push({ agent, errors });
+      }
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        missing.push(agent);
+        continue;
+      }
+      if (error instanceof SyntaxError) {
+        invalid.push({ agent, errors: ["Receipt is not valid JSON."] });
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  return {
+    valid: missing.length === 0 && invalid.length === 0,
+    missing,
+    invalid
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-police",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Strict governance framework for coding agents that blocks testing and typing bypasses.",
   "type": "module",
   "license": "MIT",

package/rules/review-and-gates.md

@@ -1,9 +1,11 @@
 # Revisão e Portas
 
+- Mudança de código deve ser executada pelo `implementer`; o agent principal coordena e não substitui esse papel.
 - Rode `tdd-warden` para verificação de comportamento e TDD quando testes mudaram ou deveriam ter mudado.
 - Rode `bypass-auditor` para qualquer superfície de revisão de TypeScript, lint, config, mock, helper ou suspeita.
 - Rode `pr-gatekeeper` antes de publicar ou declarar aprovação.
 - Autorreview inline não substitui invocação dos agents de auditoria nominais.
+- Antes de commit, push, merge request, release ou aprovação, valide os receipts exigidos em `.aqp/receipts/`.
 - Se um agent de auditoria exigido não puder rodar, reporte `BLOCKED` em vez de declarar conclusão.
 - Saídas de auditor devem ser concretas, curtas, baseadas em evidência e severas.
 - Um revisor que não consegue provar segurança deve rejeitar a mudança.