@jaimevalasek/aioson 1.22.0 → 1.23.1

package/docs/pt/5-referencia/loop-guardrails.md

@@ -0,0 +1,225 @@
+# Loop Guardrails — Contrato verificável para o self:loop
+
+> Controla o loop autônomo com fronteira de arquivos, orçamento aplicado, gates humanos e critérios avaliados — sem criar subsistemas novos.
+
+Introduzido na v1.22.0. O `self:loop` existente ganhava cap de iterações e circuit-breaker, mas nada impedia o agente de alterar arquivos fora do escopo, o `cost_ceiling_tokens` existia no schema e nunca era aplicado, e não havia aprovação humana no meio do loop. Os guardrails resolvem isso de forma retrocompatível: contratos antigos continuam válidos.
+
+---
+
+## O que são os guardrails
+
+Quatro camadas que o preflight do `self:loop` ativa automaticamente quando o `harness-contract.json` as declara (ou usa os defaults):
+
+| Camada | O que faz |
+|---|---|
+| **Scope guard** | Valida os arquivos alterados em cada iteração contra globs. Violação pausa o loop. |
+| **Budget enforcement** | Aplica `cost_ceiling_tokens` e `max_runtime_minutes`. 80% → warning; 100% → pausa. |
+| **Human gates** | Detecta alterações em áreas sensíveis (pagamentos, auth, migrations) e pausa o loop até decisão humana. |
+| **Criteria evaluation** | Executa comandos de verificação por critério; mesma assinatura de falha 2× → escala para humano. |
+
+---
+
+## Campos novos no harness-contract.json
+
+```json
+{
+  "feature": "minha-feature",
+  "contract_mode": "safe",
+  "governor": {
+    "max_steps": 10,
+    "cost_ceiling_tokens": 200000,
+    "max_runtime_minutes": 30,
+    "max_changed_files": 20,
+    "max_diff_lines": 1500
+  },
+  "allowed_files": ["src/modules/checkout/**", "tests/checkout/**"],
+  "forbidden_files": ["src/modules/auth/**"],
+  "human_gate": {
+    "required_for": ["payment_logic_change", "database_destructive_change"]
+  },
+  "criteria": [
+    {
+      "id": "tests-pass",
+      "description": "Suíte de testes passa sem erros",
+      "binary": true,
+      "verification": { "command": "npm test", "timeout_ms": 60000 }
+    }
+  ]
+}
+```
+
+Campos novos são **todos opcionais**. Contratos existentes sem eles continuam válidos: o scope guard aplica só os defaults proibidos, sem gates e sem orçamento.
+
+---
+
+## Presets de contract_mode
+
+Em vez de configurar cada campo do `governor` manualmente, use um preset:
+
+| Modo | max_steps | cost_ceiling_tokens | max_runtime_minutes | max_changed_files |
+|---|---|---|---|---|
+| `balanced` (padrão) | — | — | — | — |
+| `safe` | 10 | 200.000 | 30 min | 20 |
+| `builder` | 30 | 1.000.000 | 120 min | 60 |
+| `autopilot` | 50 | 3.000.000 | 360 min | — |
+
+Valor explícito no `governor` sempre vence o preset. `balanced` mantém o comportamento anterior.
+
+---
+
+## Scope guard
+
+### Globs proibidos por padrão (não-removíveis)
+
+```
+.env*      *.pem      *.key      secrets/**
+.git/**    node_modules/**      package-lock.json
+yarn.lock  pnpm-lock.yaml       npm-shrinkwrap.json    bun.lockb
+```
+
+Esses defaults são aplicados mesmo quando `forbidden_files` está ausente no contrato.
+
+### Campos
+
+- `allowed_files[]` — globs de arquivos que o loop pode alterar. Quando ausente, qualquer arquivo fora dos defaults proibidos é permitido.
+- `forbidden_files[]` — globs proibidos adicionais (mergeados com os defaults).
+
+### O que acontece numa violação
+
+1. Loop pausa com evento `scope_violation` listando os arquivos fora dos globs.
+2. A próxima iteração recebe instrução de reverter e refazer dentro do escopo.
+3. Reincidência: circuito abre e escala para humano.
+
+---
+
+## Human gates
+
+### Temas disponíveis
+
+| Tema | Paths monitorados (override possível) |
+|---|---|
+| `payment_logic_change` | `**/billing/**`, `**/payment/**` |
+| `auth_permission_change` | `**/auth/**` |
+| `database_destructive_change` | `**/migrations/**` |
+| `publish` | (gate de comando — detectado em `feature:close`, não por diff) |
+
+### Ciclo de gate
+
+```
+Loop detecta diff em migrations/** → HUMAN_GATE
+  ↓
+process.exitCode = persistido em .aioson/plans/{slug}/gates/{id}.json
+  ↓
+aioson harness:approve . --slug=billing --gate=migration-1
+  ↓  (ou harness:reject --reason="reverter mudança")
+Loop retoma da iteração atual
+```
+
+### Comandos
+
+```bash
+# Aprovar gate pendente
+aioson harness:approve . --slug=<feature> --gate=<id>
+
+# Rejeitar (encerra a tentativa, requer motivo)
+aioson harness:reject . --slug=<feature> --gate=<id> --reason="..."
+
+# Listar gates pendentes / estado do loop
+aioson harness:status . --slug=<feature>
+aioson harness:status . --slug=<feature> --json
+```
+
+---
+
+## Budget enforcement
+
+```json
+"governor": {
+  "cost_ceiling_tokens": 500000,
+  "max_runtime_minutes": 60
+}
+```
+
+- 80% dos tokens → warning em evento, loop continua.
+- 100% → pausa com resumo do que foi feito e do que falta. Edite o contrato e reexecute.
+- `max_runtime_minutes` → pausa quando o wall-clock ultrapassa o limite.
+
+A estimativa de tokens é best-effort (heurística chars/4 sobre o output do agente, erro típico 5–15%). É uma guarda de parada, não contabilidade exata.
+
+---
+
+## Criteria evaluation
+
+Cada critério pode declarar um comando de verificação:
+
+```json
+{
+  "id": "lint",
+  "description": "Sem erros de lint",
+  "verification": { "command": "npm run lint", "timeout_ms": 30000 }
+}
+```
+
+- O comando roda via `sandbox:exec` (timeout, kill de process tree) após cada iteração.
+- Logs gravados em `.aioson/plans/{slug}/attempts/{n}/checks/{id}.log`.
+- **Mesma assinatura de falha por 2 tentativas consecutivas** → circuito abre e escala para humano (detecção de loop estéril).
+
+---
+
+## Artefatos por tentativa
+
+Cada iteração produz:
+
+```
+.aioson/plans/{slug}/attempts/{n}/
+  changed-files.json   # arquivos alterados nesta tentativa
+  diff.patch           # patch da tentativa (arquivos rastreados)
+  checks/
+    {criterion-id}.log # stdout/stderr + exit_code de cada verificação
+```
+
+Esses artefatos são o insumo do `@qa` e do `@validator` — sem precisar reconstruir o que aconteceu.
+
+---
+
+## harness:status — visão do loop
+
+```bash
+aioson harness:status . --slug=<feature>
+```
+
+Exibe:
+- Estado do circuito (open / closed / half-open)
+- Iteração atual / máximo
+- Budget: tokens estimados, tempo decorrido
+- Checks da última tentativa: passados / falhos
+- Última assinatura de falha
+- Gates pendentes
+- Próxima ação recomendada
+
+---
+
+## git:guard (camada 2)
+
+O `git:guard` lê os `forbidden_files` do contrato ativo e os aplica como política de pre-commit. Uma segunda barreira: mesmo que o scope guard não capture algo (ex: commit manual fora do loop), o hook bloqueia.
+
+```bash
+aioson git:guard .   # inspecionar política ativa
+```
+
+---
+
+## Retrocompatibilidade
+
+- Contratos sem os novos campos: scope guard aplica defaults, sem orçamento, sem gates. ✅
+- Nenhum comando existente mudou de assinatura. ✅
+- Contratos novos com agentes mais antigos que não conhecem os guardrails: campos ignorados silenciosamente pelo agente, mas o CLI ainda aplica as checagens no preflight. ✅
+
+---
+
+## Próximos passos
+
+- [Referência de todos os comandos](./comandos-cli.md#harness)
+- [Motor Hardening](./motor-hardening.md) — gates técnicos e auto-cura
+- [Sandbox de Execução](./sandbox.md) — como os comandos de verificação rodam
+- [Retrospectiva de loop](./harness-retro.md) — minerar o histórico de falhas de uma feature

package/docs/pt/5-referencia/sdd-automation-scripts.md

@@ -349,7 +349,7 @@ project.context.md
 ## workflow:execute
 
 ```
-aioson workflow:execute [path] --feature=<slug> [--tool=<tool>] [--classification=<tier>] [--dry-run] [--start-from=<agent>] [--json]
+aioson workflow:execute [path] --feature=<slug> [--tool=<tool>] [--classification=<tier>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--start-from=<agent>] [--json]
 ```
 
 Monta e executa o plano de agentes para uma feature com base na classificação.
@@ -367,27 +367,39 @@ Monta e executa o plano de agentes para uma feature com base na classificação.
 | Flag | Descrição |
 |---|---|
 | `--tool=<tool>` | Ferramenta a usar (`claude`, `codex`, `opencode`) |
-| `--classification=<tier>` | Override manual da classificação |
-| `--dry-run` | Mostra o plano sem executar |
-| `--start-from=<agent>` | Pula agentes anteriores ao agente dado |
+| `--classification=<tier>` | Override manual da classificação |
+| `--agentic` | Emite/persiste `agentic_policy` para o gateway continuar handoffs determinísticos |
+| `--max-dev-qa-cycles=<n>` | Limite do loop `@dev` ↔ `@qa` no modo agentic (padrão: 3) |
+| `--max-tester-cycles=<n>` | Limite de correções após `@tester` no modo agentic (padrão: 3) |
+| `--max-pentester-cycles=<n>` | Limite de correções após `@pentester` no modo agentic (padrão: 3) |
+| `--dry-run` | Mostra o plano sem executar |
+| `--start-from=<agent>` | Pula agentes anteriores ao agente dado |
 
 **Exemplo dry-run:**
 
 ```bash
-aioson workflow:execute . \
-  --feature=checkout \
-  --classification=SMALL \
-  --dry-run \
-  --json
-```
+aioson workflow:execute . \
+  --feature=checkout \
+  --classification=SMALL \
+  --agentic \
+  --dry-run \
+  --json
+```
 
 ```json
 {
   "ok": true,
   "dry_run": true,
-  "feature": "checkout",
-  "classification": "SMALL",
-  "steps": [
+  "feature": "checkout",
+  "classification": "SMALL",
+  "agentic_policy": {
+    "enabled": true,
+    "review_cycle": {
+      "max_dev_qa_cycles": 3,
+      "feature_close": "human_gate"
+    }
+  },
+  "steps": [
     { "agent": "product", "skip": false, "reason": "prd not found" },
     { "agent": "analyst", "skip": false },
     { "agent": "dev", "skip": false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.22.0",
+  "version": "1.23.1",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agents.js

@@ -67,7 +67,7 @@ function buildAgentPrompt(agent, tool, options = {}) {
     '',
     `**Language boundary:** Agent instructions are canonical in English. All user-facing communication must be in ${interactionLanguage}.`,
     '',
-    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies, never past the `@dev` handoff.' : ''}`,
+    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies. The chain stops before the first `@dev` activation (human clears context and starts implementation) and continues through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`); it NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
   ].join('\n');
 
   if (safeTool === 'claude') {

package/src/cli.js

@@ -11,9 +11,10 @@ const { runInfo } = require('./commands/info');
 const { runDoctorCommand } = require('./commands/doctor');
 const { runI18nAdd } = require('./commands/i18n-add');
 const { runAgentsList, runAgentPrompt } = require('./commands/agents');
-const { runContextValidate } = require('./commands/context-validate');
-const { runContextPack } = require('./commands/context-pack');
-const { runContextLoad } = require('./commands/context-load');
+const { runContextValidate } = require('./commands/context-validate');
+const { runContextPack } = require('./commands/context-pack');
+const { runContextSelect } = require('./commands/context-select');
+const { runContextLoad } = require('./commands/context-load');
 const { runChainAudit } = require('./commands/chain-audit');
 const { runMemorySearch } = require('./commands/memory-search');
 const { runMemoryArchive } = require('./commands/memory-archive');
@@ -182,8 +183,9 @@ const { runPreflight } = require('./commands/preflight');
 const { runClassify } = require('./commands/classify');
 const { runSizing } = require('./commands/sizing');
 const { runDetectTestRunner } = require('./commands/detect-test-runner');
-const { runPulseUpdate } = require('./commands/pulse-update');
-const { runStateSave, runStateReset } = require('./commands/state-save');
+const { runPulseUpdate } = require('./commands/pulse-update');
+const { runAgentEpilogue } = require('./commands/agent-epilogue');
+const { runStateSave, runStateReset } = require('./commands/state-save');
 const { runOpIdentity } = require('./commands/op-identity');
 const { runOpCapture } = require('./commands/op-capture');
 const { runOpPromote } = require('./commands/op-promote');
@@ -203,7 +205,8 @@ const { runRevisionOpen, runRevisionList, runRevisionResolve } = require('./comm
 const { runGateCheck } = require('./commands/gate-check');
 const { runGateApprove } = require('./commands/gate-approve');
 const { runArtifactValidate } = require('./commands/artifact-validate');
-const { runWorkflowExecute } = require('./commands/workflow-execute');
+const { runWorkflowExecute } = require('./commands/workflow-execute');
+const { runReviewCycle } = require('./commands/review-cycle');
 const { runRunnerQueueFromPlan } = require('./commands/runner-queue-from-plan');
 const { runLearningAutoPromote } = require('./commands/learning-auto-promote');
 const { runBriefValidate } = require('./commands/brief-validate');
@@ -238,8 +241,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'agent-prompt',
   'agent:help',
   'agent-help',
-  'agent:invoke',
-  'agent-invoke',
+  'agent:invoke',
+  'agent-invoke',
+  'agent:epilogue',
+  'agent-epilogue',
   'setup:context',
   'setup-context',
   'locale:apply',
@@ -248,9 +253,11 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'doctor',
   'context:validate',
   'context-validate',
-  'context:pack',
-  'context-pack',
-  'context:load',
+  'context:pack',
+  'context-pack',
+  'context:select',
+  'context-select',
+  'context:load',
   'context-load',
   'chain:audit',
   'chain-audit',
@@ -268,6 +275,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'workflow-next',
   'workflow:status',
   'workflow-status',
+  'harness:retro',
+  'harness-retro',
+  'harness:preview',
+  'harness-preview',
   'agent:next',
   'agent-next',
   'parallel:init',
@@ -405,6 +416,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'harness-reject',
   'harness:status',
   'harness-status',
+  'harness:retro',
+  'harness-retro',
+  'harness:preview',
+  'harness-preview',
   'brief-gen',
   'verify:gate',
   'verify-gate',
@@ -679,8 +694,16 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'gate-approve',
   'artifact:validate',
   'artifact-validate',
-  'workflow:execute',
-  'workflow-execute',
+  'workflow:execute',
+  'workflow-execute',
+  'review-cycle:status',
+  'review-cycle-status',
+  'review-cycle:advance',
+  'review-cycle-advance',
+  'review-cycle:resolve',
+  'review-cycle-resolve',
+  'review-cycle:reset',
+  'review-cycle-reset',
   'runner:queue:from-plan',
   'runner-queue-from-plan',
   'learning:auto-promote',
@@ -783,11 +806,13 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_i18n_add');
   logHelpLine(t, logger, 'cli.help_agents');
   logHelpLine(t, logger, 'cli.help_agent_prompt');
-  logHelpLine(t, logger, 'cli.help_agent_help');
-  logHelpLine(t, logger, 'cli.help_agent_invoke');
-  logHelpLine(t, logger, 'cli.help_context_validate');
-  logHelpLine(t, logger, 'cli.help_context_pack');
-  logHelpLine(t, logger, 'cli.help_context_load');
+  logHelpLine(t, logger, 'cli.help_agent_help');
+  logHelpLine(t, logger, 'cli.help_agent_invoke');
+  logHelpLine(t, logger, 'cli.help_agent_epilogue');
+  logHelpLine(t, logger, 'cli.help_context_validate');
+  logHelpLine(t, logger, 'cli.help_context_pack');
+  logHelpLine(t, logger, 'cli.help_context_select');
+  logHelpLine(t, logger, 'cli.help_context_load');
   logHelpLine(t, logger, 'cli.help_memory_status');
   logHelpLine(t, logger, 'cli.help_memory_summary');
   logHelpLine(t, logger, 'cli.help_memory_search');
@@ -802,8 +827,9 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_test_package');
   logHelpLine(t, logger, 'cli.help_workflow_plan');
   logHelpLine(t, logger, 'cli.help_workflow_next');
-  logHelpLine(t, logger, 'cli.help_workflow_status');
-  logHelpLine(t, logger, 'cli.help_workflow_execute');
+  logHelpLine(t, logger, 'cli.help_workflow_status');
+  logHelpLine(t, logger, 'cli.help_workflow_execute');
+  logHelpLine(t, logger, 'cli.help_review_cycle');
   logHelpLine(t, logger, 'cli.help_parallel_init');
   logHelpLine(t, logger, 'cli.help_parallel_doctor');
   logHelpLine(t, logger, 'cli.help_parallel_assign');
@@ -817,6 +843,8 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_qa_run');
   logHelpLine(t, logger, 'cli.help_qa_scan');
   logHelpLine(t, logger, 'cli.help_qa_report');
+  logHelpLine(t, logger, 'cli.help_harness_retro');
+  logHelpLine(t, logger, 'cli.help_harness_preview');
   logHelpLine(t, logger, 'cli.help_web_map');
   logHelpLine(t, logger, 'cli.help_web_scrape');
   logHelpLine(t, logger, 'cli.help_scan_project');
@@ -1066,10 +1094,12 @@ async function main() {
       result = await runAgentPrompt({ args, options, logger: commandLogger, t });
     } else if (command === 'context:validate' || command === 'context-validate') {
       result = await runContextValidate({ args, options, logger: commandLogger, t });
-    } else if (command === 'context:pack' || command === 'context-pack') {
-      result = await runContextPack({ args, options, logger: commandLogger, t });
-    } else if (command === 'context:load' || command === 'context-load') {
-      result = await runContextLoad({ args, options, logger: commandLogger, t });
+    } else if (command === 'context:pack' || command === 'context-pack') {
+      result = await runContextPack({ args, options, logger: commandLogger, t });
+    } else if (command === 'context:select' || command === 'context-select') {
+      result = await runContextSelect({ args, options, logger: commandLogger, t });
+    } else if (command === 'context:load' || command === 'context-load') {
+      result = await runContextLoad({ args, options, logger: commandLogger, t });
     } else if (command === 'chain:audit' || command === 'chain-audit') {
       result = await runChainAudit({ args, options, logger: commandLogger, t });
     } else if (command === 'setup:context' || command === 'setup-context') {
@@ -1271,6 +1301,12 @@ async function main() {
     } else if (command === 'harness:status' || command === 'harness-status') {
       const { runHarnessStatus } = require('./commands/harness-status');
       result = await runHarnessStatus({ args, options, logger: commandLogger, t });
+    } else if (command === 'harness:retro' || command === 'harness-retro') {
+      const { runHarnessRetro } = require('./commands/harness-retro');
+      result = await runHarnessRetro({ args, options, logger: commandLogger, t });
+    } else if (command === 'harness:preview' || command === 'harness-preview') {
+      const { runHarnessPreview } = require('./commands/harness-preview');
+      result = await runHarnessPreview({ args, options, logger: commandLogger, t });
     } else if (command === 'verify:gate' || command === 'verify-gate') {
       result = await runVerifyGate({ args, options, logger: commandLogger, t });
 
@@ -1504,8 +1540,10 @@ async function main() {
       result = await runSizing({ args, options, logger: commandLogger });
     } else if (command === 'detect:test-runner' || command === 'detect-test-runner') {
       result = await runDetectTestRunner({ args, options, logger: commandLogger });
-    } else if (command === 'pulse:update' || command === 'pulse-update') {
-      result = await runPulseUpdate({ args, options, logger: commandLogger });
+    } else if (command === 'pulse:update' || command === 'pulse-update') {
+      result = await runPulseUpdate({ args, options, logger: commandLogger });
+    } else if (command === 'agent:epilogue' || command === 'agent-epilogue') {
+      result = await runAgentEpilogue({ args, options, logger: commandLogger, t });
     } else if (
       command === 'state:save' ||
       command === 'state-save' ||
@@ -1573,9 +1611,12 @@ async function main() {
       result = await runGateApprove({ args, options, logger: commandLogger });
     } else if (command === 'artifact:validate' || command === 'artifact-validate') {
       result = await runArtifactValidate({ args, options, logger: commandLogger });
-    } else if (command === 'workflow:execute' || command === 'workflow-execute') {
-      result = await runWorkflowExecute({ args, options, logger: commandLogger });
-    } else if (command === 'runner:queue:from-plan' || command === 'runner-queue-from-plan') {
+    } else if (command === 'workflow:execute' || command === 'workflow-execute') {
+      result = await runWorkflowExecute({ args, options, logger: commandLogger });
+    } else if (command.startsWith('review-cycle:') || command.startsWith('review-cycle-')) {
+      const sub = command.replace(/^review-cycle[:-]/, '');
+      result = await runReviewCycle({ args, options: { ...options, sub }, logger: commandLogger, t });
+    } else if (command === 'runner:queue:from-plan' || command === 'runner-queue-from-plan') {
       result = await runRunnerQueueFromPlan({ args, options, logger: commandLogger });
     } else if (command === 'learning:auto-promote' || command === 'learning-auto-promote') {
       result = await runLearningAutoPromote({ args, options, logger: commandLogger });