@jaimevalasek/aioson 1.23.3 → 1.28.0

package/docs/pt/5-referencia/fluxo-artefatos.md

@@ -11,15 +11,16 @@ Cada agente produz arquivos que os agentes subsequentes leem. Nenhum agente lê
 ```
 @product → prd.md / prd-{slug}.md
                ↓
-@sheldon (N rodadas) → enriquece PRD + gera sheldon-enrichment-{slug}.md
-                       pode criar .aioson/plans/{slug}/manifest.md + plan-{fase}.md
-               ↓
-@analyst → lê sheldon-enrichment → discovery.md / requirements-{slug}.md + spec-{slug}.md
-               ↓
-@scope-check → confronta intenção, plano e artefatos antes do código
-               gera scope-check-{slug}.md quando a feature é nomeada
-               ↓
-@dev → carrega minimum context package → implementa fase por fase
+@sheldon (N rodadas) → enriquece PRD + gera sheldon-enrichment-{slug}.md
+                       pode criar .aioson/plans/{slug}/manifest.md + plan-{fase}.md
+               ↓
+@analyst → lê sheldon-enrichment → discovery.md / requirements-{slug}.md + spec-{slug}.md
+               ↓
+@scope-check → confronta intenção, plano e artefatos antes do código
+               roda spec:analyze (consistência cruzada) no preflight
+               gera scope-check-{slug}.md quando a feature é nomeada
+               ↓
+@dev → carrega minimum context package → implementa fase por fase
 ```
 
 ---
@@ -89,7 +90,7 @@ O `spec-{slug}.md` é o **artefato de handoff para @dev** — ele inclui as deci
 | Modo | O que @dev carrega |
 |---|---|
 | Feature MICRO | `project.context.md` + `prd-{slug}.md` |
-| Feature SMALL/MEDIUM | `project.context.md` + `spec-{slug}.md` + `scope-check-{slug}.md` + `implementation-plan-{slug}.md` |
+| Feature SMALL/MEDIUM | `project.context.md` + `spec-{slug}.md` + `scope-check-{slug}.md` + `implementation-plan-{slug}.md` |
 | Feature com plano do Sheldon | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + arquivo da fase atual |
 | Modo projeto | `project.context.md` + `spec.md` + `skeleton-system.md` |
 
@@ -160,10 +161,10 @@ Esta é a lista completa de arquivos que @dev pode consultar em qualquer sessão
 |---|---|
 | `project.context.md` | Sempre |
 | `dev-state.md` | Sempre (se existir — define o restante) |
-| `features.md` | Cold start apenas |
-| `spec-{slug}.md` | Feature ativa |
-| `scope-check-{slug}.md` | Antes da primeira implementação e após fixes relevantes |
-| `implementation-plan-{slug}.md` | Se plano existe |
+| `features.md` | Cold start apenas |
+| `spec-{slug}.md` | Feature ativa |
+| `scope-check-{slug}.md` | Antes da primeira implementação e após fixes relevantes |
+| `implementation-plan-{slug}.md` | Se plano existe |
 | `.aioson/plans/{slug}/manifest.md` + fase atual | Se plano Sheldon existe |
 | `skeleton-system.md` | Só ao navegar estrutura do projeto |
 | `design-doc.md` | Só se listado no plano |
@@ -175,9 +176,33 @@ Esta é a lista completa de arquivos que @dev pode consultar em qualquer sessão
 
 ---
 
+## Verificação executável: campos e artefatos adicionais
+
+Além da cadeia acima, a camada de **verificação executável** adiciona campos e artefatos opcionais que tornam o gate de execução determinístico. Tudo é aditivo — features que não os usam seguem a lane normal sem mudança.
+
+### Campo `verification` no harness-contract.json
+
+Quando o `@sheldon` autora o `harness-contract.json`, ele escreve um comando `verification` para todo critério `binary:true` mecanicamente verificável (preferindo o test runner do projeto; determinístico; cross-platform; exit 0 = pass). Esse campo é o que o `aioson harness:check` roda deterministicamente fora do loop, e o que o `@validator` copia verbatim antes de julgar por LLM os critérios restantes. Contratos legados sem o campo continuam válidos.
+
+### Coluna `Wave` no plano de implementação
+
+A tabela **Execution Sequence** gerada pelo `@pm` ganha a coluna `Wave`. Fases na mesma Wave são disjuntas em arquivos e sem dependência entre si — paralelizáveis via subagentes/worktrees isolados; waves executam em ordem crescente. A marcação é conservadora: mesma Wave só quando os Primary files não se sobrepõem **e** nenhuma fase consome a saída da outra; na dúvida, sequencial. É essa coluna que a Lane B usa para montar os `parallel()` do workflow compilado.
+
+### spec:analyze como passe de consistência pré-execução
+
+Antes do gate de execução, o `@scope-check` roda `aioson spec:analyze --feature={slug}` — o irmão de **conteúdo** do `artifact:validate`. Enquanto `artifact:validate` checa a presença da cadeia, `spec:analyze` checa a consistência cruzada entre os artefatos: rastreabilidade REQ/AC, staleness (upstream modificado após downstream gerado), readiness, sanidade do contrato, vínculo AC→contrato e `wave_file_overlap`. Persiste `spec-analyze-{slug}.json` em `.aioson/context/`: errors são blockers roteados ao agente dono; warnings viram evidência de drift pré-computada.
+
+### forge-run.workflow.js como artefato de saída compilado
+
+Para features MEDIUM, a **Lane B** (`@forge-run` → `aioson forge:compile`) compila os artefatos da feature num `.aioson/plans/{slug}/forge-run.workflow.js` — um script de dynamic workflow auditável e versionável, **commitado junto da spec**. Ele embute parallel-por-Wave, convergência no `harness:check`, revisão adversarial e validador fresh-context. É a forma compilada e reproduzível dos mesmos artefatos descritos acima; nunca roda `feature:close`/publish.
+
+---
+
 ## Veja também
 
-- [Fichas dos 29 agentes](../4-agentes/README.md) — quando usar cada agente e o que ele entrega
+- [Fichas dos 29 agentes](../4-agentes/README.md) — quando usar cada agente e o que ele entrega
 - [Receitas práticas](../3-receitas/README.md) — exemplos end-to-end por cenário
 - [Continuidade entre sessões](../3-receitas/continuidade-entre-sessoes.md) — feature dossier, dev-resume, drift detection
 - [Feature Archive](./feature-archive.md) — o que acontece com os artefatos quando a feature fecha
+- [Loop Guardrails](./loop-guardrails.md) — `harness:check` e o campo `verification` do harness-contract
+- [SDD Automation Scripts](./sdd-automation-scripts.md) — `spec:analyze` e a Lane B (`forge:compile`)

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

@@ -164,6 +164,25 @@ Cada critério pode declarar um comando de verificaçã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).
 
+O campo `verification` é **autorado por critério**. O `@sheldon` o escreve para todo critério `binary:true` mecanicamente verificável — preferindo o test runner do projeto, determinístico, cross-platform, com exit 0 = pass. Contratos legados sem o campo continuam válidos; `validateContract` apenas emite um WARNING advisory (nunca erro) para critério `binary:true` sem `verification`.
+
+---
+
+## harness:check — verificação determinística avulsa
+
+O mesmo motor de verificação que o `self:loop` usa internamente também é exposto como comando autônomo:
+
+```bash
+aioson harness:check . --slug=<feature>
+aioson harness:check . --slug=<feature> --criteria=C1,C3 --timeout=120000 --json
+```
+
+`harness:check` roda os comandos `criteria[].verification` do contrato deterministicamente, **fora do self:loop**. Exit 0 = pass. Reusa exatamente o mesmo `runCriteria`/`executeInSandbox` da avaliação de critérios acima — timeouts, kill de process-tree, redaction de credenciais e failure signatures idênticos.
+
+Diferença chave de governança: é **read-only sobre `progress.json`**. O estado do circuit breaker continua exclusivo de `harness:validate`/`apply-validation` — `harness:check` nunca abre nem fecha o circuito, só reporta o veredito. Persiste `last-check-output.json` e emite telemetria `criteria_check_failed`. Auto-descobre o contrato ativo se `--slug` for omitido; `--criteria` roda um subconjunto.
+
+É a base do gate de execução: o `@validator` roda `harness:check` **primeiro** e copia o veredito do exit code verbatim em `results[].passed`, julgando por LLM apenas os critérios sem `verification`. Veja [Comandos CLI — harness:check](./comandos-cli.md#58-verificar-critérios-deterministicamente-com-harnesscheck).
+
 ---
 
 ## Artefatos por tentativa

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

@@ -1,6 +1,6 @@
 # SDD Automation Scripts — Regra dos 80%
 
-> Referência completa dos 12 comandos determinísticos do AIOSON que movem trabalho de arquivo/estado/validação para fora do contexto LLM.
+> Referência completa dos comandos determinísticos do AIOSON que movem trabalho de arquivo/estado/validação para fora do contexto LLM.
 >
 > **Veja também:** [SDD Framework](./sdd-framework.md) — os princípios e a metodologia por trás desses scripts.
 
@@ -346,10 +346,47 @@ project.context.md
 
 ---
 
+## spec:analyze
+
+```
+aioson spec:analyze [path] --feature=<slug> [--json]
+```
+
+Irmão de **conteúdo** do `artifact:validate`. Enquanto `artifact:validate` checa a **presença** da cadeia, `spec:analyze` checa a **consistência cruzada** entre os artefatos da feature antes do gate de execução — tudo deterministicamente, sem LLM.
+
+**Checagens:**
+
+| Checagem | O que detecta | Severidade |
+|---|---|---|
+| **Rastreabilidade REQ/AC** | ids declarados em `requirements-{slug}.md` nunca referenciados downstream = gap de cobertura; ids referenciados downstream sem declaração = órfão/drift | warning |
+| **Staleness** | artefato upstream modificado depois de um downstream já gerado (tolerância 60s, `architecture.md` global excluído) | warning |
+| **Readiness** | `blocked` = error; `ready_with_warnings` = info | error / info |
+| **Sanidade do contrato** | erros de schema do `harness-contract.json` = error; warnings de cobertura executável = info | error / info |
+| **Vínculo AC→contrato** | nenhum AC declarado mencionado no contrato | info |
+| **wave_file_overlap** | fases da mesma Wave com Primary files sobrepostos no plano de implementação | warning |
+
+A rastreabilidade tem **guarda anti-ruído**: plano em prosa que não cita ids não gera gap. O `wave_file_overlap` pula o check quando o plano não tem a coluna `Wave`; placeholders e waves não-inteiras são ignorados, paths são normalizados.
+
+**Severidades e exit code:** `error` vira `ok:false` (exit 1 em `--json`) para scripting de gate; `warning` = drift provável; `info` = dívida. Persiste `spec-analyze-{slug}.json` em `.aioson/context/`.
+
+**Quem roda:** o `@scope-check` chama no preflight — errors são blockers roteados ao agente dono; warnings viram evidência de drift pré-computada para confirmar ou descartar.
+
+```bash
+# Consistência cruzada antes do gate de execução
+aioson spec:analyze . --feature=checkout
+
+# Em pipeline de gate (errors → exit 1)
+aioson spec:analyze . --feature=checkout --json
+```
+
+Veja [Comandos CLI — spec:analyze](./comandos-cli.md#59-validar-consistência-cruzada-com-specanalyze).
+
+---
+
 ## workflow:execute
 
 ```
-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]
+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,39 +404,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 |
-| `--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 |
+| `--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 \
-  --agentic \
-  --dry-run \
-  --json
-```
+aioson workflow:execute . \
+  --feature=checkout \
+  --classification=SMALL \
+  --agentic \
+  --dry-run \
+  --json
+```
 
 ```json
 {
   "ok": true,
   "dry_run": true,
-  "feature": "checkout",
-  "classification": "SMALL",
-  "agentic_policy": {
-    "enabled": true,
-    "review_cycle": {
-      "max_dev_qa_cycles": 3,
-      "feature_close": "human_gate"
-    }
-  },
-  "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 },
@@ -517,6 +554,73 @@ aioson learning:auto-promote . --threshold=5
 
 ---
 
+## harness:check
+
+```
+aioson harness:check [path] --slug=<slug> [--criteria=C1,C2] [--timeout=<ms>] [--json]
+```
+
+Roda os comandos `criteria[].verification` do `harness-contract.json` deterministicamente, **fora do self:loop**. Exit 0 = pass. É o surface avulso do mesmo motor de verificação que o loop usa internamente — reusa `runCriteria`/`executeInSandbox` (timeouts, kill de process-tree, redaction de credenciais, failure signatures).
+
+- **Read-only** sobre `progress.json` — o estado do circuit breaker continua exclusivo de `harness:validate`/`apply-validation`.
+- Persiste `last-check-output.json` e emite telemetria `criteria_check_failed`.
+- Auto-descobre o contrato ativo se `--slug` for omitido; `--criteria` roda um subconjunto.
+
+O `verification` é campo autorado por critério: o `@sheldon` o escreve para todo critério `binary:true` mecanicamente verificável (preferindo o test runner do projeto; determinístico; cross-platform; exit 0 = pass). Contratos legados sem o campo continuam válidos — `validateContract` emite apenas um WARNING advisory (nunca erro).
+
+No gate de execução, o `@validator` roda `harness:check` **primeiro** e copia o veredito do exit code verbatim em `results[].passed`; só julga por LLM os critérios sem `verification`.
+
+```bash
+# Verificação determinística avulsa antes do @validator
+aioson harness:check . --slug=checkout
+
+# Subconjunto de critérios + JSON (exit 0 = pass)
+aioson harness:check . --slug=checkout --criteria=C1,C3 --json
+```
+
+Veja [Loop Guardrails](./loop-guardrails.md) para o motor compartilhado e [Comandos CLI — harness:check](./comandos-cli.md#58-verificar-critérios-deterministicamente-com-harnesscheck).
+
+---
+
+## forge:compile (Lane B)
+
+```
+aioson forge:compile [path] --feature=<slug> [--json]
+```
+
+A **Lane B** é uma lane de execução compilada, opt-in, para features MEDIUM. Em vez de orquestrar agentes em tempo real (como `workflow:execute`), o `forge:compile` compila os artefatos da feature num `.aioson/plans/{slug}/forge-run.workflow.js` — um script de dynamic workflow auditável e versionável (Workflow tool do Claude Code), commitado junto da spec.
+
+**Estrutura compilada:**
+
+1. Um `parallel()` por **Wave** (devs em arquivos disjuntos; parada antecipada se uma wave bloqueia).
+2. Loop de convergência determinístico no `harness:check`, limitado pelo `error_streak_limit` do governor (fixes **sequenciais** — só waves provam disjunção) + guarda de orçamento de tokens.
+3. Revisão adversarial de 3 lentes (correção / completude / risco-de-regressão; maioria sobrevive, refuta-por-default) para critérios binários **sem** `verification`.
+4. Estágio de validador fresh-context fechando pelo ciclo normal `harness:validate` → `last-validator-output.json` → `apply-validation`.
+
+**Preflights duros** recusam compilar e nomeiam o agente dono:
+
+| Recusa | Agente dono |
+|---|---|
+| Contrato inválido/ausente, zero critério executável | `@sheldon` |
+| Plano sem coluna Wave, `wave_file_overlap` (warning na análise, **erro aqui**) | `@pm` |
+| Errors do `spec:analyze`, readiness | `@discovery-design-doc` |
+
+O código gerado respeita o contrato do runtime: meta literal puro, JS plano, sem `Date.now`/`Math.random`/`new Date`, texto de artefatos via `JSON.stringify` (seguro contra injeção). O script **nunca** roda `feature:close`/publish.
+
+A entrada da Lane B é o agente `@forge-run` (`/forge-run`): compila → revisa com o usuário (aviso de custo) → executa via runtime de workflows (nunca emulado na mão) → reporta. PASS recomenda o humano rodar `feature:close`; FAIL volta ao `@dev` pela lane normal. Uma feature por run.
+
+```bash
+# Compilar a feature MEDIUM num workflow auditável
+aioson forge:compile . --feature=checkout
+
+# JSON (preflights duros podem recusar)
+aioson forge:compile . --feature=checkout --json
+```
+
+Veja [Comandos CLI — forge:compile](./comandos-cli.md#60-compilar-a-lane-b-com-forgecompile).
+
+---
+
 ## Fluxo completo de uma feature SMALL
 
 ```bash

package/package.json

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

package/src/cli.js

@@ -11,10 +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 { runContextSelect } = require('./commands/context-select');
-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');
@@ -183,9 +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 { runAgentEpilogue } = require('./commands/agent-epilogue');
-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');
@@ -205,8 +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 { runReviewCycle } = require('./commands/review-cycle');
+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');
@@ -241,10 +241,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'agent-prompt',
   'agent:help',
   'agent-help',
-  'agent:invoke',
-  'agent-invoke',
-  'agent:epilogue',
-  'agent-epilogue',
+  'agent:invoke',
+  'agent-invoke',
+  'agent:epilogue',
+  'agent-epilogue',
   'setup:context',
   'setup-context',
   'locale:apply',
@@ -253,11 +253,11 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'doctor',
   'context:validate',
   'context-validate',
-  'context:pack',
-  'context-pack',
-  'context:select',
-  'context-select',
-  'context:load',
+  'context:pack',
+  'context-pack',
+  'context:select',
+  'context-select',
+  'context:load',
   'context-load',
   'chain:audit',
   'chain-audit',
@@ -416,6 +416,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'harness-reject',
   'harness:status',
   'harness-status',
+  'harness:check',
+  'harness-check',
   'harness:retro',
   'harness-retro',
   'harness:preview',
@@ -694,16 +696,20 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'gate-approve',
   'artifact:validate',
   'artifact-validate',
-  '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',
+  'spec:analyze',
+  'spec-analyze',
+  'forge:compile',
+  'forge-compile',
+  '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',
@@ -806,13 +812,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_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_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');
@@ -827,9 +833,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_review_cycle');
+  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');
@@ -843,6 +849,7 @@ 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_check');
   logHelpLine(t, logger, 'cli.help_harness_retro');
   logHelpLine(t, logger, 'cli.help_harness_preview');
   logHelpLine(t, logger, 'cli.help_web_map');
@@ -1094,12 +1101,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: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 === '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') {
@@ -1301,6 +1308,9 @@ 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:check' || command === 'harness-check') {
+      const { runHarnessCheck } = require('./commands/harness-check');
+      result = await runHarnessCheck({ 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 });
@@ -1540,10 +1550,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 === 'agent:epilogue' || command === 'agent-epilogue') {
-      result = await runAgentEpilogue({ args, options, logger: commandLogger, t });
+    } 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' ||
@@ -1611,12 +1621,18 @@ 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.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') {
+    } else if (command === 'spec:analyze' || command === 'spec-analyze') {
+      const { runSpecAnalyze } = require('./commands/spec-analyze');
+      result = await runSpecAnalyze({ args, options, logger: commandLogger });
+    } else if (command === 'forge:compile' || command === 'forge-compile') {
+      const { runForgeCompile } = require('./commands/forge-compile');
+      result = await runForgeCompile({ args, options, logger: commandLogger });
+    } 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 });