@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/deyvin-subtask-scout/README.md

@@ -0,0 +1,109 @@
+# Deyvin Sub-Task Scout — guia em português
+
+> **Sub-task scout** é a primitiva de diagnóstico estruturado do `@deyvin`. Quando uma pergunta exige inspecionar mais de 5 arquivos ou rastrear um fluxo de runtime, o agente não lê tudo inline (queimando contexto) — ele despacha um scout. O scout roda em contexto isolado, inspeciona o escopo, e devolve um JSON com findings, confiança e recomendação. O agente lê o relatório (~500 tokens) em vez dos arquivos (~10k+ tokens).
+
+Esta pasta documenta a feature completa — 3 fases, 3 verbos CLI, 1 check advisory no doctor.
+
+---
+
+## Para que serve
+
+- **Preservar o contexto do agente pai** — surveys de >5 arquivos entram no contexto como relatório compacto, não como conteúdo bruto.
+- **Rastreabilidade de diagnóstico** — scouts são persistidos em `.aioson/runtime/scouts/` e (após `feature:close`) arquivados em `.aioson/context/features/{slug}/scouts/`.
+- **Fallback sem CLI** — `deyvin.md` carrega uma versão manual do scout para ambientes sem o binário `aioson` instalado.
+- **Cap discipline** — limites configuráveis impedem explosão de sub-tarefas: `max_scouts_per_session=3`, `max_files_in_scope=20`.
+
+---
+
+## Pré-requisitos
+
+- AIOSON instalado (versão que incluiu esta feature)
+- Harness com suporte a sub-agentes: Claude Code (Agent tool) ou Codex (MultiAgentV2)
+- `.aioson/config/scout-engine.json` no projeto (copiado automaticamente pelo installer como `{}`, defaults ativos)
+
+> **Gemini CLI / OpenCode:** emitem `harness_unsupported` e caem automaticamente para o fluxo CLI-less inline do `deyvin.md`. Paridade de harness completa é V2.
+
+---
+
+## Roteiro de leitura
+
+### Quero entender o que mudou no @deyvin (10 min)
+1. [O que é o sub-task scout](./sub-task-scout.md) — o problema, as 3 fases, o ciclo de vida completo
+2. [Diagramas](./diagramas.md) — fluxo ASCII do despacho: `scout:prep` → sub-agente → `scout:validate` → `scout:commit`
+
+### Quero ver o @deyvin usando um scout
+3. [Como usar](./como-usar.md) — fluxo happy-path, recuperação de JSON inválido, cap exceeded
+
+### Quero configurar ou entender os limites
+4. [Referência CLI](./comandos-cli.md) — flags completos dos 3 verbos (`scout:prep`, `scout:validate`, `scout:commit`)
+
+### Algo deu errado / quero ajustar os limites
+5. [Troubleshooting](./troubleshooting.md) — cap exceeded, JSON malformado, harness sem sub-agente, scouts órfãos
+
+---
+
+## Comandos canônicos
+
+| Comando | O que faz | Tier | Doc |
+|---|---|---|---|
+| `aioson scout:prep --question="..." --scope-paths="..." --parent-agent=deyvin --parent-session-id=<id>` | Valida inputs, aplica caps, gera prompt padronizado para o sub-agente | tier-1 silencioso | [Referência CLI](./comandos-cli.md) |
+| `aioson scout:validate --input=<path>` | Valida o JSON retornado pelo sub-agente contra o output schema | tier-1 silencioso | [Referência CLI](./comandos-cli.md) |
+| `aioson scout:commit --input=<path>` | Persiste o relatório validado, emite telemetria, decrementa cap | tier-1 silencioso | [Referência CLI](./comandos-cli.md) |
+| `aioson doctor .` | Inclui o advisory `scouts_directory_pruning` (scouts órfãos >90d) | tier-1 silencioso | [Troubleshooting](./troubleshooting.md) |
+
+---
+
+## Onde os artefatos vivem
+
+| Caminho | Papel |
+|---|---|
+| `.aioson/runtime/scouts/{id}.json` | Scout report ativo (ephemeral; poda pelo doctor após 90d se órfão) |
+| `.aioson/runtime/scouts/.state.json` | Estado de caps por session_id; lock em `.state.json.lock` |
+| `.aioson/config/scout-engine.json` | Configuração por projeto (override de defaults) |
+| `.aioson/context/features/{slug}/scouts/{id}.json` | Scout arquivado após `feature:close --verdict=PASS` |
+| `.aioson/context/features/{slug}/dossier.md` → `## Sub-task scouts` | Bullets de scouts arquivados (append-only, idempotente) |
+| `agent_events` (SQLite) | Telemetria: `event_type='sub_task'`, `action ∈ {prepared, validation_failed, retry_exhausted, committed, slow_completion, cap_exceeded}` |
+
+---
+
+## Configuração
+
+`.aioson/config/scout-engine.json` é copiado como `{}` no primeiro install — todos os defaults se aplicam:
+
+| Campo | Default | O que controla |
+|---|---|---|
+| `max_scouts_per_session` | 3 | Scouts por `parent_session_id` |
+| `max_files_in_scope` | 20 | Arquivos na soma de `scope_paths` |
+| `max_retries_on_malformed_json` | 1 | Re-validações antes de `retry_exhausted` |
+| `max_depth` | 2 | Profundidade de scouts aninhados (1 sub-scout por scout) |
+| `prune_unattached_after_days` | 90 | Dias para poda de scouts sem `feature_slug` pelo `doctor --fix` |
+| `slow_completion_warn_seconds` | 300 | Threshold para emissão de `slow_completion` |
+
+Exemplo de override:
+
+```json
+{
+  "max_scouts_per_session": 5,
+  "max_files_in_scope": 30
+}
+```
+
+> Chaves desconhecidas são **rejeitadas** (validação estrita). Use apenas os campos acima.
+
+---
+
+## Status
+
+A feature `deyvin-subtask-scout` foi entregue em 3 fases:
+
+| Fase | Slug | Entrega | Status |
+|---|---|---|---|
+| 1 | `core-engine` | `src/sub-task-engine.js` + schemas + validador hand-rolled | PASS |
+| 2 | `cli-verbs` | `scout:prep` + `scout:validate` + `scout:commit` + estado com file-lock | PASS |
+| 3 | `wiring-and-lifecycle` | `deyvin.md` atualizado (CLI + CLI-less), archival no `feature:close`, `memory:summary` row, doctor advisory | PASS |
+
+80 testes determinísticos passando. QA aprovado.
+
+Artefatos de especificação (arquivados):
+- [PRD](../../.aioson/context/done/deyvin-subtask-scout/prd-deyvin-subtask-scout.md)
+- [Spec](../../.aioson/context/done/deyvin-subtask-scout/spec-deyvin-subtask-scout.md)

package/docs/pt/deyvin-subtask-scout/comandos-cli.md

@@ -0,0 +1,248 @@
+# Referência CLI — Sub-task Scout
+
+> Três verbos. Cada seção cobre o contrato completo: flags, comportamento, exit codes, exemplos de saída.
+
+---
+
+## `aioson scout:prep`
+
+Prepara um scout: valida inputs, verifica caps, gera o prompt padronizado para o sub-agente.
+
+**Tier:** 1 (silencioso — sem output por default; use `--json`)
+
+```
+aioson scout:prep [path]
+  --question="<texto>"
+  --scope-paths="<caminho1>,<caminho2>"
+  --parent-agent=<nome>
+  --parent-session-id=<id>
+  --parent-session-excerpt="<texto>"
+  [--feature-slug=<slug>]
+  [--json]
+```
+
+### Flags
+
+| Flag | Obrigatório | Descrição |
+|---|---|---|
+| `--question="<texto>"` | sim | Pergunta que o sub-agente deve responder |
+| `--scope-paths="<paths>"` | sim (ou `--scope-globs`¹) | Arquivos e diretórios a inspecionar, separados por vírgula. Diretórios expandem 1 nível |
+| `--parent-agent=<nome>` | sim | Agente que despacha. Em V1, apenas `"deyvin"` é aceito |
+| `--parent-session-id=<id>` | sim | ID da sessão pai — usado para rastrear caps por sessão |
+| `--parent-session-excerpt="<texto>"` | sim | Por que o scout foi despachado (50-1000 chars). Bloqueado se ausente — é o campo de cold-load comprehension |
+| `--feature-slug=<slug>` | não | Feature associada (para arquivamento automático no `feature:close`) |
+| `--json` | não | Output em JSON (`{ ok, id, prompt, output_path, cap_remaining }`) |
+
+¹ `--scope-globs` está adiado para V2 (Node 18-21 não tem `fs.glob` nativo). Se passado, retorna `error.code = "globs_not_implemented_v1"`.
+
+### Comportamento
+
+1. Valida todos os campos obrigatórios.
+2. Resolve `scope_paths`: paths relativos → absolutos, verifica que ficam dentro do `rootDir`.
+3. Verifica caps: `max_scouts_per_session` e `max_files_in_scope`.
+4. Incrementa `scouts_in_session` no state file (com file-lock).
+5. Gera prompt padronizado com question, scope, output schema, e tool whitelist (`[Read, Grep]` / `[Bash, Edit, Write]` proibidos).
+6. Retorna `{ id, prompt, output_path, cap_remaining }`.
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | Scout preparado com sucesso |
+| 2 | Argumento inválido, cap excedido, escopo muito grande, path fora do root |
+
+### Exemplos
+
+```bash
+# Básico com JSON
+aioson scout:prep \
+  --question="Onde o featureSlug anterior não é limpo no workflow:next?" \
+  --scope-paths="src/commands/workflow-next.js,src/handoff-contract.js" \
+  --parent-agent=deyvin \
+  --parent-session-id=sess-abc123 \
+  --parent-session-excerpt="Usuário perguntou sobre bug de herança de state; inspeção de loadOrCreateState necessária" \
+  --json
+```
+
+```json
+{
+  "ok": true,
+  "id": "scout-2026-05-14-a3b7c1",
+  "prompt": "You are a read-only code survey sub-agent...",
+  "output_path": ".aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json",
+  "cap_remaining": 2
+}
+```
+
+Erro de cap:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "cap_exceeded",
+    "message": "max_scouts_per_session=3 reached for parent_session_id=sess-abc123",
+    "remediation": "Override .aioson/config/scout-engine.json or open a new session"
+  }
+}
+```
+
+---
+
+## `aioson scout:validate`
+
+Valida o JSON retornado pelo sub-agente contra o output schema. Rastreia retries no state file.
+
+**Tier:** 1 (silencioso)
+
+```
+aioson scout:validate [path] --input=<caminho-do-json> [--json]
+```
+
+### Flags
+
+| Flag | Obrigatório | Descrição |
+|---|---|---|
+| `--input=<path>` | sim | Caminho para o JSON que o sub-agente escreveu |
+| `--json` | não | Output em JSON |
+
+### Comportamento
+
+1. Lê o arquivo em `--input`.
+2. Valida contra `OUTPUT_SCHEMA` (strict: `additionalProperties: false`).
+3. Incrementa `retries_by_id[id]` no state file.
+4. Se `retries_by_id[id] > max_retries_on_malformed_json` → retorna `retry_exhausted` sem testar o schema.
+
+### Output schema resumido (o que o sub-agente deve gerar)
+
+```json
+{
+  "id": "scout-{slug?}-{data}-{rand6}",
+  "parent_agent": "deyvin",
+  "parent_session_id": "sess-abc123",
+  "parent_session_excerpt": "...",
+  "feature_slug": null,
+  "question": "...",
+  "scope": { "paths": [...], "files_requested": [...] },
+  "findings": [
+    {
+      "file": "src/commands/workflow-next.js",
+      "line": 42,
+      "evidence": "loadOrCreateState checks featureSlug but does not reset on feature transition",
+      "relevance": "high",
+      "explanation": "..."
+    }
+  ],
+  "confidence": "high",
+  "recommendation": "...",
+  "files_inspected": [...],
+  "status": "success",
+  "completed_at": "2026-05-14T10:00:00.000Z"
+}
+```
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | JSON válido contra o output schema |
+| 2 | Schema inválido, retry exhausted, arquivo não encontrado |
+
+### Exemplos
+
+```bash
+aioson scout:validate --input=.aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json
+
+# Com JSON detalhado em caso de falha:
+aioson scout:validate --input=... --json
+```
+
+Saída em falha:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "schema_invalid",
+    "details": [
+      { "field": "findings[0].evidence", "reason": "required field missing" },
+      { "field": "confidence", "reason": "must be one of: high, medium, low" }
+    ]
+  },
+  "retry_remaining": 1
+}
+```
+
+---
+
+## `aioson scout:commit`
+
+Persiste o relatório validado, emite telemetria, decrementa o cap counter.
+
+**Tier:** 1 (silencioso)
+
+```
+aioson scout:commit [path] --input=<caminho-do-json> [--json]
+```
+
+### Flags
+
+| Flag | Obrigatório | Descrição |
+|---|---|---|
+| `--input=<path>` | sim | Caminho para o JSON validado |
+| `--json` | não | Output em JSON |
+
+### Comportamento
+
+1. Lê o arquivo em `--input`.
+2. Verifica se o `id` já foi commitado nesta sessão (idempotente — re-commit é no-op com `committed: false, reason: 'already_committed'`).
+3. Copia o arquivo para `.aioson/runtime/scouts/{id}.json`.
+4. Emite `runtime:emit type=sub_task action=committed` em `agent_events`.
+5. Decrementa `scouts_in_session` no state file (clamped a 0).
+6. Registra `committed_ids[id] = true` no state file.
+
+> **Idempotência:** o sub-agente pode escrever o relatório em `output_path` antes do commit. O check de idempotência usa `committed_ids` no state (não presença de arquivo) — isso garante que o primeiro commit sempre processa corretamente.
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | Commitado com sucesso (ou no-op se já commitado) |
+| 1 | Arquivo não encontrado, falha de state lock, falha de telemetria |
+
+### Exemplos
+
+```bash
+aioson scout:commit --input=.aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json
+
+# Com JSON:
+aioson scout:commit --input=... --json
+```
+
+```json
+{
+  "ok": true,
+  "committed": true,
+  "id": "scout-2026-05-14-a3b7c1",
+  "path": ".aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json",
+  "cap_remaining": 1
+}
+```
+
+Re-commit (idempotente):
+
+```json
+{
+  "ok": true,
+  "committed": false,
+  "reason": "already_committed"
+}
+```
+
+---
+
+## Continue lendo
+
+- [Como usar](./como-usar.md) — fluxos concretos
+- [Diagramas](./diagramas.md) — fluxo visual
+- [Troubleshooting](./troubleshooting.md) — problemas conhecidos

package/docs/pt/deyvin-subtask-scout/como-usar.md

@@ -0,0 +1,221 @@
+# Como usar o Sub-task Scout
+
+> Exemplos concretos. O `@deyvin` usa o scout automaticamente quando a rubrica linha 111 dispara. Esta página mostra o que acontece por baixo e como intervir quando necessário.
+
+---
+
+## 1. Fluxo happy-path — scout bem-sucedido
+
+Cenário: o usuário pergunta ao `@deyvin` por que o `workflow:next` às vezes herda registros de conclusão de uma feature anterior.
+
+`@deyvin` identifica que a resposta exige inspeção de vários arquivos e despacha um scout:
+
+**Passo 1 — Preparar o scout**
+
+```bash
+aioson scout:prep \
+  --question="Por que workflow:next herda completion records de features anteriores?" \
+  --scope-paths="src/commands/workflow-next.js,src/handoff-contract.js" \
+  --parent-agent=deyvin \
+  --parent-session-id=sess-abc123 \
+  --parent-session-excerpt="Usuário perguntou sobre bug de herança de estado no workflow:next; precisa inspecionar lógica de loadOrCreateState e handoff-contract para identificar onde o featureSlug anterior não é limpo" \
+  --feature-slug=current-feature
+```
+
+Saída (`--json`):
+
+```json
+{
+  "ok": true,
+  "id": "scout-current-feature-2026-05-14-a3b7c1",
+  "prompt": "You are a read-only code survey sub-agent...\n[prompt completo]",
+  "output_path": ".aioson/runtime/scouts/scout-current-feature-2026-05-14-a3b7c1.json",
+  "cap_remaining": 2
+}
+```
+
+**Passo 2 — Chamar o sub-agente**
+
+`@deyvin` usa a capacidade de sub-agente do harness (Claude Code `Agent` tool ou Codex sub-agent) com o `prompt` retornado. O sub-agente roda em contexto isolado, usa apenas `Read` e `Grep`, e escreve o resultado em `output_path`.
+
+**Passo 3 — Validar**
+
+```bash
+aioson scout:validate --input=.aioson/runtime/scouts/scout-current-feature-2026-05-14-a3b7c1.json
+```
+
+Exit 0 = PASS. O arquivo é válido contra o output schema.
+
+**Passo 4 — Commitar**
+
+```bash
+aioson scout:commit --input=.aioson/runtime/scouts/scout-current-feature-2026-05-14-a3b7c1.json
+```
+
+Scout persistido, cap decrementado (2→1), telemetria emitida.
+
+**Passo 5 — @deyvin lê e responde**
+
+`@deyvin` lê `findings`, `confidence`, e `recommendation` do JSON e dobra a resposta na conversa com o usuário. Contexto pai cresceu ~500 tokens em vez de ~10k+.
+
+---
+
+## 2. Recuperação de JSON inválido
+
+O sub-agente retornou JSON malformado (campo obrigatório faltando):
+
+```bash
+aioson scout:validate --input=.aioson/runtime/scouts/scout-abc.json
+# exit 2
+```
+
+Saída:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "schema_invalid",
+    "details": [
+      { "field": "findings[0].evidence", "reason": "required field missing" },
+      { "field": "confidence", "reason": "must be one of: high, medium, low" }
+    ]
+  },
+  "retry_remaining": 1
+}
+```
+
+`@deyvin` re-prompta o sub-agente com as falhas de validação explícitas. Na segunda tentativa, se PASS → commit. Se FAIL novamente → `retry_exhausted`:
+
+```json
+{
+  "ok": false,
+  "error": { "code": "retry_exhausted" },
+  "retry_remaining": 0
+}
+```
+
+Scout persiste com `status: "error"`. `@deyvin` informa o usuário e oferece handoff manual para `/architect` se necessário.
+
+---
+
+## 3. Cap exceeded
+
+O agente despachará um 4º scout na mesma sessão, mas o default é 3:
+
+```bash
+aioson scout:prep --question="..." --scope-paths="..." --parent-agent=deyvin --parent-session-id=sess-abc123 --parent-session-excerpt="..."
+# exit 2
+```
+
+Saída:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "cap_exceeded",
+    "message": "max_scouts_per_session=3 reached for parent_session_id=sess-abc123",
+    "remediation": "Either fold scout findings into a single answer, or open a new session, or override .aioson/config/scout-engine.json"
+  }
+}
+```
+
+`@deyvin` superfície a mensagem e pergunta ao usuário como prosseguir: normalmente handoff para `/architect` se os surveys continuarem se multiplicando.
+
+Para aumentar o limite no projeto:
+
+```json
+// .aioson/config/scout-engine.json
+{ "max_scouts_per_session": 5 }
+```
+
+---
+
+## 4. Escopo muito grande
+
+```bash
+aioson scout:prep \
+  --question="..." \
+  --scope-paths="src/" \  # diretório com 30+ arquivos
+  --parent-agent=deyvin \
+  --parent-session-id=sess-abc123 \
+  --parent-session-excerpt="..."
+# exit 2
+```
+
+Saída:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "scope_too_large",
+    "message": "scope resolved to 34 files, max_files_in_scope=20",
+    "remediation": "Narrow scope_paths to specific files, or increase max_files_in_scope in scout-engine.json"
+  }
+}
+```
+
+Solução: especificar arquivos concretos em vez de diretório, ou ajustar `max_files_in_scope` no config.
+
+> **Nota:** diretórios em `scope_paths` expandem apenas 1 nível de profundidade (filhos diretos). `scope_globs` está adiado para V2.
+
+---
+
+## 5. Ver scouts despachados no projeto
+
+```bash
+aioson memory:summary .
+```
+
+Saída (trecho relevante):
+
+```
+Scouts dispatched: 4 (top topics: "workflow state", "handoff contract")
+```
+
+Para inspecionar diretamente:
+
+```bash
+ls .aioson/runtime/scouts/
+# scout-feature-a-2026-05-14-a1b2c3.json
+# scout-2026-05-13-x9y8z7.json
+# .state.json
+```
+
+---
+
+## 6. Usar o fallback CLI-less (sem `aioson` instalado)
+
+Em ambientes sem o binário `aioson` (ex: Claude Code puro sem CLI configurado), `@deyvin` usa o template inline do seu prompt. A seção "Sub-task scout invocation — CLI-less fallback" no `deyvin.md` descreve como construir o prompt manualmente e injetar no sub-agente via Agent tool.
+
+O fallback produz o mesmo relatório JSON, mas sem:
+- Validação de caps
+- Telemetria em SQLite
+- Archival automático no `feature:close`
+
+---
+
+## 7. Verificar arquivamento após feature:close
+
+Após `aioson feature:close --slug=my-feature --verdict=PASS`:
+
+```bash
+ls .aioson/context/features/my-feature/scouts/
+# scout-my-feature-2026-05-14-a1b2c3.json
+
+grep "Sub-task scouts" .aioson/context/features/my-feature/dossier.md
+# ## Sub-task scouts
+# - scout-my-feature-2026-05-14-a1b2c3: "Por que workflow:next herda..."
+```
+
+O runtime copy permanece em `.aioson/runtime/scouts/` e será podado pelo `doctor --fix` após 90 dias. Scouts com `feature_slug` definido **nunca** são podados — preservação de memória de cold-load.
+
+---
+
+## Continue lendo
+
+- [Referência CLI](./comandos-cli.md) — todos os flags documentados
+- [Diagramas](./diagramas.md) — fluxo visual completo
+- [Troubleshooting](./troubleshooting.md) — problemas conhecidos