@jaimevalasek/aioson 1.21.6 → 1.21.7

package/docs/en/1-understand/glossary.md

@@ -255,7 +255,7 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 
 **Example:** a "legal compliance" squad with agents `@regulator`, `@attorney`, `@auditor`, under the command of `@squad`.
 
-**Commands:** `aioson squad:assemble`, `squad:agent-create`, `squad:refresh`.
+**Commands:** `aioson squad:scaffold`, `squad:agent-create`, `squad:doctor`.
 
 ---
 

package/docs/en/2-start/initial-decisions.md

@@ -110,13 +110,13 @@ Adds the squad system — you can create custom squads for domains outside the s
 - `@attorney` — interprets clauses
 - `@auditor` — checks conformity
 
-```bash
-# Inside the AI client
-> @squad assemble compliance
-
-# Or via CLI
-npx @jaimevalasek/aioson squad:assemble compliance
-```
+```bash
+# Inside the AI client
+> @squad scaffold compliance
+
+# Or via CLI
+npx @jaimevalasek/aioson squad:scaffold . --slug=compliance --name="Compliance" --mode=mixed
+```
 
 **When to activate Squads:**
 - You know you'll need specialization outside the standard

package/docs/en/5-reference/squad-dashboard.md

@@ -9,7 +9,7 @@ No additional installation required. It ships with aioson.
 ## Prerequisites
 
 - aioson installed globally (`npm install -g @jaimevalasek/aioson`)
-- At least one squad created in the project (`aioson squad:create`)
+- At least one squad created in the project (`aioson squad:scaffold . --slug=<slug>`)
 - Node.js ≥ 18 (already required by aioson)
 - A modern browser (Chrome, Firefox, Safari, Edge)
 
@@ -330,10 +330,10 @@ Check that the manifest exists:
 ls .aioson/squads/*/squad.manifest.json
 ```
 
-If not, create the squad first:
-```bash
-aioson squad:create . --squad=my-squad
-```
+If not, create the squad first:
+```bash
+aioson squad:scaffold . --slug=my-squad --name="My Squad" --mode=mixed
+```
 
 ### Panels appear empty
 

package/docs/pt/1-entender/glossario.md

@@ -255,7 +255,7 @@ Termos em ordem alfabética. Cada um tem **definição curta** + **exemplo concr
 
 **Exemplo:** squad "compliance jurídico" com agentes `@regulator`, `@attorney`, `@auditor`, sob comando do `@squad`.
 
-**Comandos:** `aioson squad:assemble`, `squad:agent-create`, `squad:refresh`.
+**Comandos:** `aioson squad:scaffold`, `squad:agent-create`, `squad:doctor`.
 
 ---
 

package/docs/pt/1-entender/mapa-do-ecossistema.md

@@ -2,7 +2,7 @@
 
 > **Para quem é:** quem quer ver o time inteiro de uma vez.
 > **Tempo de leitura:** 8 min.
-> **O que você vai sair sabendo:** quem são os 28 agentes, em que momento cada um entra, e como eles se conversam.
+> **O que você vai sair sabendo:** quem são os 29 agentes, em que momento cada um entra, e como eles se conversam.
 
 ---
 

package/docs/pt/2-comecar/decisoes-iniciais.md

@@ -99,7 +99,7 @@ Você pode marcar **mais de um** no wizard — eles convivem no mesmo projeto.
 
 ### Development (padrão)
 
-Inclui os 28 agentes oficiais (product, analyst, dev, qa, etc.). Suficiente para 95% dos projetos.
+Inclui os 29 agentes oficiais (product, analyst, dev, qa, etc.). Suficiente para 95% dos projetos.
 
 ### Development + Squads
 
@@ -111,11 +111,11 @@ Adiciona o sistema de squads — você pode criar squads customizados para domí
 - `@auditor` — checa conformidade
 
 ```bash
-# Dentro do cliente AI
-> @squad assemble compliance
-
-# Ou via CLI
-npx @jaimevalasek/aioson squad:assemble compliance
+# Dentro do cliente AI
+> @squad montar compliance
+
+# Ou via CLI
+npx @jaimevalasek/aioson squad:scaffold compliance
 ```
 
 **Quando ativar Squads:**

package/docs/pt/4-agentes/README.md

@@ -1,6 +1,6 @@
 # Guia de Agentes AIOSON
 
-> Índice completo dos 28 agentes, com situação de uso e saída esperada.
+> Índice completo dos 29 agentes, com situação de uso e saída esperada.
 > Cada agente tem sua ficha — clique no nome para detalhes.
 
 ---
@@ -9,9 +9,10 @@
 
 | Agente | Para que serve | Quando invocar | Saída principal |
 |---|---|---|---|
-| [@product](./product.md) | Define visão, PRD e escopo da feature | Início de projeto ou nova feature | `prd.md`, `spec.md` |
-| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Após `@product`, antes de `@architect` | `architecture.md` (domínio) |
-| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Após `@analyst` | `architecture.md` (técnico) |
+| [@product](./product.md) | Define visão, PRD e escopo da feature | Início de projeto ou nova feature | `prd.md`, `spec.md` |
+| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Após `@product`, antes de `@architect` | `architecture.md` (domínio) |
+| [@scope-check](./scope-check.md) | Confronta intenção, plano e artefatos antes do código | Antes de `@dev` e após fixes relevantes | `scope-check.md` |
+| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Após `@analyst` | `architecture.md` (técnico) |
 | [@ux-ui](./ux-ui.md) | Design system e specs de componentes | MEDIUM, após `@architect` | `design-doc.md`, `discovery.md` |
 | [@pm](./pm.md) | Backlog, user stories, ACs detalhados | MEDIUM, após `@ux-ui` | `tasks.md` |
 | [@orchestrator](./orchestrator.md) | Coordena lanes paralelas de implementação | MEDIUM, após `@pm` | `.aioson/context/parallel/` |

package/docs/pt/4-agentes/dev.md

@@ -10,7 +10,7 @@
 
 ## Para que serve
 
-Você passou por `@product`, `@analyst`, `@architect`. A spec existe, as decisões técnicas estão em disco. Agora é hora de escrever código — mas de forma que o próximo agente (`@qa`, `@validator`) consiga verificar o que foi feito sem perguntar "o que você implementou?".
+Você passou por `@product`, `@analyst`, `@architect` e, nos fluxos SMALL/MEDIUM atuais, por `@scope-check` antes de abrir implementação. A spec existe, as decisões técnicas estão em disco. Agora é hora de escrever código — mas de forma que o próximo agente (`@qa`, `@validator`) consiga verificar o que foi feito sem perguntar "o que você implementou?".
 
 `@dev` lê os artefatos, implementa, e grava um `dev-state.md` com o resumo do que foi feito, quais arquivos foram tocados, e qual é o próximo passo. Isso é o que permite continuar de onde parou em outra sessão, sem depender do histórico de chat.
 
@@ -20,7 +20,7 @@ Você passou por `@product`, `@analyst`, `@architect`. A spec existe, as decisõ
 
 ## Quando invocar
 
-- Após `@architect` (SMALL/MEDIUM) ou `@product` (MICRO).
+- Após `@scope-check` (SMALL/MEDIUM) ou `@product` (MICRO).
 - Para retomar uma feature interrompida — `@dev` lê `dev-state.md` e sabe onde parou.
 - Para correções apontadas pelo `@qa` (ciclo autônomo, até 2 iterações).
 
@@ -43,7 +43,7 @@ Você > @dev
        Lendo project.context.md... Node.js, SMALL, checkout-stripe.
        Lendo spec-checkout-stripe.md e implementation-plan-checkout-stripe.md...
        
-       Plano aprovado. Implementando:
+       Scope-check aprovado. Implementando:
        
        1. db/migrations/add-payment-table.sql       ← Payment schema
        2. src/models/payment.js                     ← model com validação básica
@@ -124,7 +124,7 @@ aioson memory:summary . --last=5
 
 ## Handoff típico
 
-- **Vem de:** `@architect` (SMALL/MEDIUM) ou `@product` (MICRO)
+- **Vem de:** `@scope-check` (SMALL/MEDIUM) ou `@product` (MICRO)
 - **Vai para:** `@qa`
 
 ---

package/docs/pt/4-agentes/squad.md

@@ -93,16 +93,16 @@ Antes de criar, o `@squad` lê:
 
 ## Comandos CLI relacionados
 
-```bash
-# Criar squad via CLI
-aioson squad:assemble <slug>
-
-# Atualizar squad existente (breadth-aware)
-aioson squad:refresh <slug>
-
-# Publicar no aioson.com
-aioson system:publish --type=squad --slug=<slug>
-```
+```bash
+# Criar squad via CLI
+aioson squad:scaffold . --slug=<slug> --name="Meu Squad" --mode=mixed
+
+# Diagnosticar squad existente
+aioson squad:doctor . --squad=<slug>
+
+# Publicar no aioson.com
+aioson system:publish --type=squad --slug=<slug>
+```
 
 ---
 

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

@@ -11,12 +11,15 @@ 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
-               ↓
-@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
+               gera scope-check-{slug}.md quando a feature é nomeada
+               ↓
+@dev → carrega minimum context package → implementa fase por fase
 ```
 
 ---
@@ -86,7 +89,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` + `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` |
 
@@ -157,9 +160,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 |
-| `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 |
@@ -173,7 +177,7 @@ Esta é a lista completa de arquivos que @dev pode consultar em qualquer sessão
 
 ## Veja também
 
-- [Fichas dos 28 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

package/docs/pt/5-referencia/squad-dashboard.md

@@ -9,7 +9,7 @@ Não requer instalação adicional. Vem incluso quando você instala o aioson.
 ## Pré-requisitos
 
 - aioson instalado globalmente (`npm install -g @jaimevalasek/aioson`)
-- Pelo menos um squad criado no projeto (`aioson squad:create`)
+- Pelo menos um squad criado no projeto (`aioson squad:scaffold . --slug=<slug>`)
 - Node.js ≥ 18 (já exigido pelo aioson)
 - Browser moderno (Chrome, Firefox, Safari, Edge)
 
@@ -331,10 +331,10 @@ Verifique se o manifest existe:
 ls .aioson/squads/*/squad.manifest.json
 ```
 
-Se não existir, crie o squad primeiro:
-```bash
-aioson squad:create . --squad=meu-squad
-```
+Se não existir, crie o squad primeiro:
+```bash
+aioson squad:scaffold . --slug=meu-squad --name="Meu Squad" --mode=mixed
+```
 
 ### Painéis aparecem vazios
 

package/docs/pt/README.md

@@ -37,7 +37,7 @@ Esta é a porta de entrada da documentação em português. Não é um índice a
 11. [Continuidade entre sessões](./3-receitas/continuidade-entre-sessoes.md) — feature dossier, dev-resume, drift detection
 
 ### Quero a referência técnica de um agente ou comando
-- **[Fichas dos 28 agentes](./4-agentes/README.md)** — uma ficha por agente, com diálogo típico, saídas em disco e handoff
+- **[Fichas dos 29 agentes](./4-agentes/README.md)** — uma ficha por agente, com diálogo típico, saídas em disco e handoff
 - **[Referência técnica completa](./5-referencia/README.md)** — 32 docs organizados em 5 categorias (novos 2026, artefatos, CLI/config, agentes/squads, skills/design)
 - [Guia de agentes (legado)](./agentes.md) — visão tabular alternativa
 

package/docs/pt/agentes.md

@@ -13,10 +13,11 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 ```
 @setup        ← sempre o primeiro
 @product      ← gera o PRD base vivo e roteia o fluxo
-@deyvin       ← companheiro tecnico para continuidade e pequenas implementacoes
-@discovery-design-doc ← quando precisa clarear escopo e gerar design doc vivo
-@analyst      ← projetos SMALL e MEDIUM
-@architect    ← projetos SMALL e MEDIUM
+@deyvin       ← companheiro tecnico para continuidade e pequenas implementacoes
+@discovery-design-doc ← quando precisa clarear escopo e gerar design doc vivo
+@analyst      ← projetos SMALL e MEDIUM
+@scope-check  ← valida alinhamento antes de codar ou depois de fix relevante
+@architect    ← projetos SMALL e MEDIUM
 @ux-ui        ← UI/UX quando há interfaces (SMALL e MEDIUM)
 @pm           ← apenas MEDIUM
 @orchestrator ← apenas MEDIUM
@@ -52,9 +53,9 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 
 Quando o projeto ja existe e voce roda `scan:project`, o handoff correto agora e:
 
-```text
-scan:project -> @analyst -> @architect -> @dev
-```
+```text
+scan:project -> @analyst -> @scope-check -> @architect -> @dev
+```
 
 Regras do fluxo:
 - os artefatos locais do scan (`scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`) servem como mapas brutos do codigo

package/docs/pt/living-memory/troubleshooting.md

@@ -44,7 +44,7 @@ aioson memory:status .
 
 ```
 [FAIL] Bootstrap coverage: 4/4
-  Hint: Run /discover to refresh the bootstrap files (or `aioson memory:refresh` if implemented).
+  Hint: Run /discover to refresh the bootstrap files (or `aioson memory:reflect-prepare . --agent=dev` for manual reflection).
 ```
 
 (Repare: cobertura 4/4 mas advisório por estar antigo — a hint detecta via `generated_at`.)

package/package.json

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

package/src/commands/live.js

@@ -1569,30 +1569,58 @@ async function runLiveStart({ args, options = {}, logger, t }) {
   }
 }
 
-async function runRuntimeEmit({ args, options = {}, logger, t }) {
-  const targetDir = resolveTargetDir(args);
-  const agentName = normalizeAgentHandle(requireOption(options, 'agent', t));
-  const eventType = String(options.type || 'note').trim() || 'note';
-
-  const { db, dbPath, runtimeDir, context } = await requireActiveLiveContext(targetDir, agentName, t, {
-    limit: options.limit
-  });
-
-  try {
-    const now = new Date().toISOString();
-    const refs = parseRefs(options.refs);
-    const planStep = options['plan-step'] ? String(options['plan-step']).trim() : null;
-    const summary = truncateMessage(
-      options.summary || options.message || options.title || `${eventType} emitted by ${agentName}`
-    );
-    const meta = parseJsonOption(options.meta);
-    const payload = meta && typeof meta === 'object' ? { ...meta } : {};
-    if (refs.length > 0) payload.refs = refs;
-    if (planStep) payload.plan_step = planStep;
-
-    const state = context.state || createLiveState(targetDir, context.run, context.task, {
-      sessionKey: context.sessionKey,
-      activeAgent: context.agentName,
+async function runRuntimeEmit({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const agentName = normalizeAgentHandle(requireOption(options, 'agent', t));
+  const eventType = String(options.type || 'note').trim() || 'note';
+  const now = new Date().toISOString();
+  const refs = parseRefs(options.refs);
+  const planStep = options['plan-step'] ? String(options['plan-step']).trim() : null;
+  const summary = truncateMessage(
+    options.summary || options.message || options.title || `${eventType} emitted by ${agentName}`
+  );
+  const meta = parseJsonOption(options.meta);
+  const payload = meta && typeof meta === 'object' ? { ...meta } : {};
+  if (refs.length > 0) payload.refs = refs;
+  if (planStep) payload.plan_step = planStep;
+
+  let liveHandle;
+  if (await runtimeStoreExists(targetDir)) {
+    try {
+      liveHandle = await requireActiveLiveContext(targetDir, agentName, t, {
+        limit: options.limit
+      });
+    } catch (err) {
+      const noActive = t('live.no_active_session', { agent: agentName });
+      const notActive = t('live.session_not_active', { agent: agentName });
+      if (err && !(err.message === noActive || err.message === notActive)) {
+        throw err;
+      }
+    }
+  }
+
+  if (!liveHandle) {
+    const standalone = await emitStandaloneRuntimeEvent({
+      targetDir,
+      agentName,
+      eventType,
+      summary,
+      payload,
+      options,
+      now
+    });
+    if (!options.json) {
+      logger.log(`runtime:emit — ${agentName} | standalone event logged | run: ${standalone.runKey} (${standalone.dbPath})`);
+    }
+    return standalone;
+  }
+
+  const { db, dbPath, runtimeDir, context } = liveHandle;
+
+  try {
+    const state = context.state || createLiveState(targetDir, context.run, context.task, {
+      sessionKey: context.sessionKey,
+      activeAgent: context.agentName,
       projectPath: targetDir
     });
 
@@ -1730,8 +1758,69 @@ async function runRuntimeEmit({ args, options = {}, logger, t }) {
     };
   } finally {
     db.close();
-  }
-}
+  }
+}
+
+async function emitStandaloneRuntimeEvent({
+  targetDir,
+  agentName,
+  eventType,
+  summary,
+  payload,
+  options = {},
+  now
+}) {
+  const { db, dbPath } = await openRuntimeDb(targetDir);
+  try {
+    const taskKey = startTask(db, {
+      title: options.title ? String(options.title).trim() : `runtime:emit ${agentName}`,
+      goal: summary,
+      status: 'completed',
+      createdBy: agentName,
+      taskKind: 'runtime_event',
+      metaJson: {
+        mode: 'standalone',
+        reason: 'no_active_live_session'
+      }
+    });
+    const runKey = startRun(db, {
+      taskKey,
+      agentName,
+      agentKind: 'official',
+      source: 'direct',
+      title: options.title ? String(options.title).trim() : `runtime:emit ${agentName}`,
+      status: 'completed',
+      summary,
+      eventType,
+      phase: 'direct',
+      message: summary,
+      payload: Object.keys(payload).length > 0 ? {
+        ...payload,
+        standalone: true,
+        reason: 'no_active_live_session'
+      } : {
+        standalone: true,
+        reason: 'no_active_live_session'
+      }
+    });
+
+    return {
+      ok: true,
+      targetDir,
+      dbPath,
+      agent: agentName,
+      eventType,
+      sessionKey: null,
+      runKey,
+      taskKey,
+      currentTask: null,
+      open: false,
+      standalone: true
+    };
+  } finally {
+    db.close();
+  }
+}
 
 
 async function runLiveHandoff({ args, options = {}, logger, t }) {

package/src/commands/workflow-next.js

@@ -465,22 +465,58 @@ function buildQaSecurityAuditBriefing(result, targetDir) {
   ].join('\n');
 }
 
-async function inferCompletedStages(targetDir, draftState) {
-  const completed = [];
-  for (const stage of draftState.sequence) {
-    if (!isInferableStage(stage)) break;
-    const valid = await validateStageArtifacts(targetDir, draftState, stage);
-    if (!valid) break;
-    completed.push(normalizeAgentName(stage));
-  }
-  return completed;
-}
-
-// SF-project-18: cross-check workflow.state.json#completed against runtime
-// telemetry. Stages claimed as completed without a corresponding agent_done
-// event in .aioson/runtime/aios.sqlite are surfaced as a warning. Detection
-// is best-effort — if the runtime DB is unavailable, the check is silently
-// skipped (the framework still works in environments without telemetry).
+async function inferCompletedStages(targetDir, draftState) {
+  const completed = [];
+  for (const stage of draftState.sequence) {
+    if (!isInferableStage(stage)) break;
+    const valid = await validateStageArtifacts(targetDir, draftState, stage);
+    if (!valid) break;
+    const contractCheck = await validateHandoffContract(targetDir, draftState, normalizeAgentName(stage));
+    if (!contractCheck.ok) break;
+    completed.push(normalizeAgentName(stage));
+  }
+  return completed;
+}
+
+function mergeInferredCompletedStages(state, inferredCompleted) {
+  if (!state || !Array.isArray(state.sequence) || !Array.isArray(inferredCompleted)) {
+    return { state, changed: false };
+  }
+
+  const sequence = state.sequence.map(normalizeAgentName);
+  const completedSet = new Set((state.completed || []).map(normalizeAgentName).filter(Boolean));
+  const skippedSet = new Set((state.skipped || []).map(normalizeAgentName).filter(Boolean));
+  let changed = false;
+
+  for (const stage of inferredCompleted.map(normalizeAgentName).filter(Boolean)) {
+    if (!sequence.includes(stage)) continue;
+    if (!completedSet.has(stage)) {
+      completedSet.add(stage);
+      changed = true;
+    }
+    if (skippedSet.delete(stage)) {
+      changed = true;
+    }
+  }
+
+  if (!changed) return { state, changed: false };
+
+  return {
+    changed: true,
+    state: buildStatePayload({
+      ...state,
+      sequence,
+      completed: sequence.filter((stage) => completedSet.has(stage)),
+      skipped: sequence.filter((stage) => skippedSet.has(stage))
+    })
+  };
+}
+
+// SF-project-18: cross-check workflow.state.json#completed against runtime
+// telemetry. Stages claimed as completed without a corresponding agent_done
+// event in .aioson/runtime/aios.sqlite are surfaced as a warning. Detection
+// is best-effort — if the runtime DB is unavailable, the check is silently
+// skipped (the framework still works in environments without telemetry).
 async function detectUnsubstantiatedCompletions(targetDir, completedStages, logger = null) {
   if (!Array.isArray(completedStages) || completedStages.length === 0) return [];
   let runtimeStore;
@@ -553,18 +589,24 @@ async function loadOrCreateState(targetDir, options = {}) {
     }
   }
 
-  if (existing && typeof existing === 'object' && Array.isArray(existing.sequence)) {
-    // SF-project-18: warn-on-mismatch only, never refuse — preserves
-    // backwards-compat with environments that lack runtime telemetry.
-    if (Array.isArray(existing.completed) && existing.completed.length > 0 && options.logger) {
-      await detectUnsubstantiatedCompletions(targetDir, existing.completed, options.logger);
-    }
-    const reconciled = reconcileWorkflowState(existing);
-    if (reconciled.changed) {
-      await writeJson(statePath, reconciled.state);
-    }
-    return { statePath, state: reconciled.state, created: false };
-  }
+  if (existing && typeof existing === 'object' && Array.isArray(existing.sequence)) {
+    // SF-project-18: warn-on-mismatch only, never refuse — preserves
+    // backwards-compat with environments that lack runtime telemetry.
+    if (Array.isArray(existing.completed) && existing.completed.length > 0 && options.logger) {
+      await detectUnsubstantiatedCompletions(targetDir, existing.completed, options.logger);
+    }
+    const reconciled = reconcileWorkflowState(existing);
+    const inferredCompleted = (reconciled.state.current || (reconciled.state.detour && reconciled.state.detour.active))
+      ? []
+      : await inferCompletedStages(targetDir, reconciled.state);
+    const merged = mergeInferredCompletedStages(reconciled.state, inferredCompleted);
+    const finalReconciled = merged.changed ? reconcileWorkflowState(merged.state) : reconciled;
+    const changed = reconciled.changed || merged.changed || finalReconciled.changed;
+    if (changed) {
+      await writeJson(statePath, finalReconciled.state);
+    }
+    return { statePath, state: finalReconciled.state, created: false };
+  }
 
   const context = await validateProjectContextFile(targetDir);
   const modeInfo = await detectWorkflowMode(targetDir);

package/src/handoff-contract.js

@@ -287,41 +287,49 @@ async function checkGateApproval(targetDir, gateLetter, slug, classification, pr
     return { ok: false, reason: 'spec_missing' };
   }
 
-  const gateNames = { A: 'requirements', B: 'design', C: 'plan', D: 'execution' };
-  const gateName = gateNames[gateLetter];
-
-  // Parse frontmatter
-  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!fmMatch) return { ok: false, reason: 'no_frontmatter' };
-
-  const fm = {};
-  for (const line of fmMatch[1].split(/\r?\n/)) {
-    const idx = line.indexOf(':');
-    if (idx === -1) continue;
-    const key = line.slice(0, idx).trim();
-    const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
-    if (key) fm[key] = val;
-  }
-
-  // Check explicit gate field
-  const gateVal = fm[`gate_${gateName}`] || fm[`gate${gateLetter}`] || fm[`gate_${gateLetter}`];
-  if (gateVal && gateVal.toLowerCase() === 'approved') {
-    return { ok: true };
-  }
-
-  // Check phase_gates JSON
-  if (fm.phase_gates) {
-    try {
-      const parsed = JSON.parse(fm.phase_gates.replace(/'/g, '"'));
-      if (parsed[gateName] === 'approved') return { ok: true };
-    } catch {
-      // ignore
-    }
-  }
-
-  // Check content for gate approval lines
-  const gateLineRe = new RegExp(`gate\\s+${gateLetter}[^:]*:\\s*approved`, 'i');
-  if (gateLineRe.test(content)) {
+  const gateNames = { A: 'requirements', B: 'design', C: 'plan', D: 'execution' };
+  const gateName = gateNames[gateLetter];
+
+  // Parse frontmatter when present. Explicit gate fields take precedence over
+  // free-text gate lines so `gate_requirements: pending` cannot be overridden
+  // accidentally by stale prose elsewhere in the spec.
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fmMatch) {
+    const fm = {};
+    for (const line of fmMatch[1].split(/\r?\n/)) {
+      const idx = line.indexOf(':');
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+      if (key) fm[key] = val;
+    }
+
+    // Check explicit gate field
+    const gateVal = fm[`gate_${gateName}`] || fm[`gate${gateLetter}`] || fm[`gate_${gateLetter}`];
+    if (gateVal) {
+      return gateVal.toLowerCase() === 'approved'
+        ? { ok: true }
+        : { ok: false, reason: `gate_${gateName}_not_approved` };
+    }
+
+    // Check phase_gates JSON
+    if (fm.phase_gates) {
+      try {
+        const parsed = JSON.parse(fm.phase_gates.replace(/'/g, '"'));
+        if (parsed[gateName]) {
+          return parsed[gateName] === 'approved'
+            ? { ok: true }
+            : { ok: false, reason: `gate_${gateName}_not_approved` };
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  // Check content for gate approval lines
+  const gateLineRe = new RegExp(`gate\\s+${gateLetter}[^:]*:\\s*approved`, 'i');
+  if (gateLineRe.test(content)) {
     return { ok: true };
   }
 
@@ -331,12 +339,12 @@ async function checkGateApproval(targetDir, gateLetter, slug, classification, pr
       const passMatch = content.match(/\*\*Verdict:\*\*\s*(PASS)/i);
       if (passMatch) {
         return { ok: true };
-      }
-    }
-  }
-
-  return { ok: false, reason: `gate_${gateName}_not_approved` };
-}
+      }
+    }
+  }
+
+  return { ok: false, reason: fmMatch ? `gate_${gateName}_not_approved` : 'no_frontmatter' };
+}
 
 async function validateHandoffContract(targetDir, state, stageName) {
   const contract = CONTRACTS[stageName];

package/template/.aioson/agents/genome.md

@@ -1878,15 +1878,15 @@ The CLI auto-detects format from response (`format` field, OR presence of `files
 - **DB schema** — should track `format: "folder" | "single-file"` per genome to route response correctly
 - **Migration** — backend may store folder format internally and convert to single-file on legacy installs (out of scope here)
 
-### Future CLI commands (not yet implemented — placeholders)
-
-| Command | Status | Function |
-|---------|--------|----------|
-| `aioson genome:enrich --slug=<slug> --source=<file>` | not implemented | Enrichment Round (currently runs via `@genome` agent conversation only) |
-| `aioson genome:export --slug=<slug> --as=system-prompt` | not implemented | Export Track 4.3 system-prompt.md (currently runs via `@genome` agent only) |
-| `aioson genome:viability --slug=<slug>` | not implemented | Standalone Viability Gate scoring (currently part of `@genome` Step 0.5) |
-
-These are documented for future implementation. For now, the agent (`@genome`) handles them in-conversation.
+### Future CLI subcommands (not implemented — do not run)
+
+| Future subcommand | Status | Function |
+|-------------------|--------|----------|
+| `genome:enrich` | not implemented | Enrichment Round (currently runs via `@genome` agent conversation only) |
+| `genome:export` | not implemented | Export Track 4.3 system-prompt.md (currently runs via `@genome` agent only) |
+| `genome:viability` | not implemented | Standalone Viability Gate scoring (currently part of `@genome` Step 0.5) |
+
+These are documented for future implementation only. Do not run them as CLI commands until they are registered in `src/cli.js`. For now, the agent (`@genome`) handles them in-conversation.
 
 ## Continuation Protocol
 

package/template/.aioson/rules/agent-structural-contract.md

@@ -84,13 +84,32 @@ Rules:
 
 ## 5. CLI error handling
 
-Every `aioson` CLI command in an agent file MUST end with `2>/dev/null || true` to prevent silent failures from breaking the session.
+Best-effort `aioson` CLI commands in agent files MUST end with `2>/dev/null || true` to prevent optional telemetry or context helpers from breaking the session when the CLI is unavailable.
 
 ```
 aioson <command> . --flag=value 2>/dev/null || true
 ```
 
-The ONLY exception is commands inside "Quick start" or "Prerequisites" sections where the user runs them manually (not the agent).
+Do not silence blocking commands whose result controls safety, routing, or user action. These commands must run normally, and the agent must inspect their result before continuing.
+
+Blocking examples:
+- `aioson git:guard`
+- `aioson commit:prepare`
+- `aioson gate:check`
+- `aioson preflight`
+- `aioson workflow:status`
+- `aioson context:validate`
+
+Best-effort examples:
+- `aioson runtime:emit`
+- `aioson pulse:update`
+- `aioson agent:done`
+- `aioson dossier:*`
+- `aioson memory:search`
+- `aioson context:search`
+- `aioson context:pack`
+
+Commands inside "Quick start" or "Prerequisites" sections are user-run examples and do not need the best-effort suffix.
 
 ## 6. CLI flag integrity