@jaimevalasek/aioson 1.23.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.23.0",
+  "version": "1.23.1",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

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',
@@ -687,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',
@@ -791,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');
@@ -810,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');
@@ -1076,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') {
@@ -1520,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' ||
@@ -1589,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 });

package/src/commands/agent-epilogue.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const path = require('node:path');
+const { runPulseUpdate } = require('./pulse-update');
+const { runDossierAddFinding } = require('./dossier');
+const { runGateApprove } = require('./gate-approve');
+const { runAgentDone } = require('./runtime');
+
+function resolveTargetDir(args) {
+  return path.resolve(process.cwd(), args[0] || '.');
+}
+
+function normalizeAgent(value) {
+  return String(value || '').trim().replace(/^@/, '');
+}
+
+function normalizeList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.map(String).map((item) => item.trim()).filter(Boolean);
+  return String(value).split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function makeSilentLogger() {
+  return { log() {}, error() {}, warn() {} };
+}
+
+function pushStep(steps, name, result) {
+  steps.push({
+    name,
+    ok: Boolean(result && result.ok),
+    skipped: Boolean(result && result.skipped),
+    reason: result && (result.reason || result.error || null)
+  });
+}
+
+function formatAutoAdvance(autoAdvance) {
+  if (!autoAdvance) return null;
+  if (autoAdvance.advanced) {
+    const nextStage = autoAdvance.result && (autoAdvance.result.next || autoAdvance.result.nextStage);
+    return `workflow auto-advanced${nextStage ? ` -> ${nextStage}` : ''}`;
+  }
+  return `workflow skip: ${autoAdvance.skipped || 'not_advanced'}`;
+}
+
+async function runAgentEpilogue({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const agent = normalizeAgent(options.agent);
+  const summary = String(options.summary || options.message || '').trim();
+  const feature = options.feature ? String(options.feature).trim() : null;
+  const action = options.action ? String(options.action).trim() : summary;
+  const next = options.next ? String(options.next).trim() : null;
+  const gate = options.gate ? String(options.gate).trim() : null;
+  const approveGate = options['approve-gate'] || options.approveGate
+    ? String(options['approve-gate'] || options.approveGate).trim().toUpperCase()
+    : null;
+  const verdict = options.verdict ? String(options.verdict).trim().toUpperCase() : null;
+  const artifacts = normalizeList(options.artifacts);
+  const strict = Boolean(options.strict);
+  const steps = [];
+  const errors = [];
+  const silentLogger = makeSilentLogger();
+
+  if (!agent) {
+    const failure = { ok: false, reason: 'missing_agent' };
+    if (options.json) return failure;
+    logger.error('--agent=<agent> is required.');
+    return failure;
+  }
+
+  if (!summary) {
+    const failure = { ok: false, reason: 'missing_summary' };
+    if (options.json) return failure;
+    logger.error('--summary="<summary>" is required.');
+    return failure;
+  }
+
+  if (approveGate) {
+    const gateResult = await runGateApprove({
+      args: [targetDir],
+      options: {
+        feature,
+        gate: approveGate,
+        agent,
+        json: true
+      },
+      logger: silentLogger
+    });
+    pushStep(steps, 'gate:approve', gateResult);
+    if (!gateResult.ok) {
+      errors.push({ step: 'gate:approve', reason: gateResult.reason || 'gate_failed', result: gateResult });
+      if (strict) {
+        const failure = { ok: false, reason: 'gate_approve_failed', steps, errors };
+        if (options.json) return failure;
+        logger.error(`agent:epilogue blocked: gate ${approveGate} approval failed.`);
+        return failure;
+      }
+    }
+  }
+
+  if (!options['no-pulse'] && !options.noPulse) {
+    const pulseResult = await runPulseUpdate({
+      args: [targetDir],
+      options: {
+        agent,
+        ...(feature ? { feature } : {}),
+        ...(gate || approveGate ? { gate: gate || `Gate ${approveGate}: approved` } : {}),
+        ...(action ? { action } : {}),
+        ...(next ? { next } : {}),
+        ...(verdict ? { verdict } : {}),
+        json: true
+      },
+      logger: silentLogger
+    });
+    pushStep(steps, 'pulse:update', pulseResult);
+    if (!pulseResult.ok) {
+      errors.push({ step: 'pulse:update', reason: pulseResult.reason || 'pulse_failed', result: pulseResult });
+    }
+  } else {
+    pushStep(steps, 'pulse:update', { ok: true, skipped: true, reason: 'disabled' });
+  }
+
+  if (feature && !options['no-dossier'] && !options.noDossier) {
+    const dossierResult = await runDossierAddFinding({
+      args: [targetDir],
+      options: {
+        slug: feature,
+        agent,
+        section: options.section ? String(options.section) : 'Agent Trail',
+        content: options.content ? String(options.content) : summary,
+        json: true
+      },
+      logger: silentLogger
+    });
+    pushStep(steps, 'dossier:add-finding', dossierResult);
+    if (!dossierResult.ok) {
+      errors.push({ step: 'dossier:add-finding', reason: dossierResult.reason || 'dossier_failed', result: dossierResult });
+    }
+  } else {
+    pushStep(steps, 'dossier:add-finding', { ok: true, skipped: true, reason: feature ? 'disabled' : 'missing_feature' });
+  }
+
+  const doneResult = await runAgentDone({
+    args: [targetDir],
+    options: {
+      agent,
+      summary,
+      ...(feature ? { feature } : {}),
+      ...(verdict ? { verdict } : {}),
+      ...(artifacts.length > 0 ? { artifacts: artifacts.join(',') } : {}),
+      json: true
+    },
+    logger: silentLogger,
+    t
+  });
+  pushStep(steps, 'agent:done', doneResult);
+  if (!doneResult.ok) {
+    errors.push({ step: 'agent:done', reason: doneResult.reason || doneResult.error || 'agent_done_failed', result: doneResult });
+  }
+
+  const ok = doneResult.ok && (strict ? errors.length === 0 : !errors.some((error) => error.step === 'agent:done'));
+  const result = {
+    ok,
+    targetDir,
+    agent: `@${agent}`,
+    feature,
+    summary,
+    steps,
+    errors,
+    agent_done: doneResult
+  };
+
+  if (options.json) return result;
+
+  logger.log(`agent:epilogue — @${agent} (${ok ? 'ok' : 'issues'})`);
+  for (const step of steps) {
+    const marker = step.skipped ? 'skip' : step.ok ? 'ok' : 'fail';
+    logger.log(`  ${marker} ${step.name}${step.reason ? ` (${step.reason})` : ''}`);
+  }
+  const autoAdvanceMessage = formatAutoAdvance(doneResult.auto_advance);
+  if (autoAdvanceMessage) logger.log(`  ${autoAdvanceMessage}`);
+  return result;
+}
+
+module.exports = {
+  runAgentEpilogue
+};

package/src/commands/context-select.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const path = require('node:path');
+const { selectContext } = require('../context-selector');
+
+async function runContextSelect({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const result = await selectContext(targetDir, {
+    agent: options.agent || options.a || 'dev',
+    mode: options.mode || 'planning',
+    task: options.task || options.goal || '',
+    paths: options.paths || options.path || '',
+    feature: options.feature || options.slug || ''
+  });
+
+  if (options.json) return result;
+
+  logger.log(`Context selection for @${result.agent} (${result.mode})`);
+  if (result.task) logger.log(`Task: ${result.task}`);
+  if (result.paths.length > 0) logger.log(`Paths: ${result.paths.join(', ')}`);
+  if (result.selected.length === 0) {
+    logger.log('No context files selected.');
+    return result;
+  }
+
+  for (const item of result.selected) {
+    logger.log(`- ${item.path} [${item.surface}; ${item.load_tier}] ${item.reason}`);
+  }
+
+  return result;
+}
+
+module.exports = { runContextSelect };