@jaimevalasek/aioson 1.30.2 → 1.36.0

package/docs/pt/agentes.md

@@ -1,8 +1,8 @@
 # Guia de Agentes
 
-> **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md).
-
-> `@pair` é alias de `@deyvin` e não possui ficha separada.
+> **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md).
+
+> `@pair` é alias de `@deyvin` e não possui ficha separada.
 
 > Quando usar cada agente, o que ele entrega e como ativá-lo.
 
@@ -15,11 +15,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
-@scope-check  ← valida alinhamento antes de codar ou depois de fix relevante
-@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
@@ -55,9 +55,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 -> @scope-check -> @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
@@ -81,7 +81,7 @@ Regras do fluxo:
 
 **Como ativar:**
 ```
-/aioson:agent:setup
+/aioson:agent:setup
 ```
 
 **O que ele pergunta:**
@@ -138,7 +138,7 @@ O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los
 
 **Como ativar:**
 ```
-/aioson:agent:product
+/aioson:agent:product
 ```
 
 **Entrega:** Arquivo `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md` com:
@@ -182,12 +182,12 @@ O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los
 
 **Como ativar:**
 ```
-/aioson:agent:deyvin
+/aioson:agent:deyvin
 ```
 
 Alias compativel:
 ```text
-/aioson:agent:pair
+/aioson:agent:pair
 ```
 
 **Exemplos bons de uso:**
@@ -227,7 +227,7 @@ Alias compativel:
 
 **Como ativar:**
 ```
-/aioson:agent:analyst
+/aioson:agent:analyst
 ```
 
 **Exemplo de perguntas que ele faz:**
@@ -268,7 +268,7 @@ Em **modo feature**, entrega adicionalmente:
 
 **Como ativar:**
 ```
-/aioson:agent:discovery-design-doc
+/aioson:agent:discovery-design-doc
 ```
 
 **Entrega:**
@@ -300,7 +300,7 @@ Em **modo feature**, entrega adicionalmente:
 
 **Como ativar:**
 ```
-/aioson:agent:architect
+/aioson:agent:architect
 ```
 
 **Estruturas que ele propõe (exemplo Laravel SMALL):**
@@ -341,7 +341,7 @@ tests/
 
 **Como ativar o agente UI/UX:**
 ```
-/aioson:agent:ux-ui
+/aioson:agent:ux-ui
 ```
 
 **Submodos disponíveis:**
@@ -384,7 +384,7 @@ tests/
 
 **Como ativar:**
 ```
-/aioson:agent:pm
+/aioson:agent:pm
 ```
 
 **Regra de ouro do @pm:** O documento deve ter no máximo 2 páginas. Se passar disso, corte funcionalidades do MVP.
@@ -410,7 +410,7 @@ tests/
 
 **Como ativar:**
 ```
-/aioson:agent:orchestrator
+/aioson:agent:orchestrator
 ```
 
 **Ou via CLI para preparar os arquivos:**
@@ -455,7 +455,7 @@ npx @jaimevalasek/aioson parallel:status
 
 **Como ativar:**
 ```
-/aioson:agent:squad
+/aioson:agent:squad
 ```
 
 **Entrega:**
@@ -481,7 +481,7 @@ npx @jaimevalasek/aioson parallel:status
 
 **Como ativar:**
 ```
-/aioson:agent:genome
+/aioson:agent:genome
 ```
 
 **Entrega:**
@@ -517,7 +517,7 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 
 **Como ativar:**
 ```
-/aioson:agent:dev
+/aioson:agent:dev
 ```
 
 **Princípios que ele aplica em qualquer stack:**
@@ -570,7 +570,7 @@ Se o usuário pedir para pular o teste, o `@dev` resiste, explica, e só cede ap
 
 **Como ativar:**
 ```
-/aioson:agent:qa
+/aioson:agent:qa
 ```
 
 **Entrega:**
@@ -634,7 +634,7 @@ O root de `.aioson/context/` fica limpo automaticamente. O desenvolvedor não pr
 
 **Como ativar:**
 ```
-/aioson:agent:tester
+/aioson:agent:tester
 ```
 
 **Entrega:**
@@ -669,7 +669,7 @@ O root de `.aioson/context/` fica limpo automaticamente. O desenvolvedor não pr
 
 **Como ativar:**
 ```
-/aioson:agent:sheldon
+/aioson:agent:sheldon
 ```
 
 **Entrega:**
@@ -698,7 +698,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:committer
+/aioson:agent:committer
 ```
 
 **Entrega:**
@@ -719,7 +719,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:copywriter
+/aioson:agent:copywriter
 ```
 
 **Entrega:**
@@ -741,7 +741,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:briefing
+/aioson:agent:briefing
 ```
 
 **Entrega:**
@@ -762,7 +762,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:design-hybrid-forge
+/aioson:agent:design-hybrid-forge
 ```
 
 **Entrega:**
@@ -782,7 +782,7 @@ Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demand
 
 **Como ativar:**
 ```
-/aioson:agent:discover
+/aioson:agent:discover
 ```
 
 **Ou via CLI:**
@@ -809,7 +809,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:neo
+/aioson:agent:neo
 ```
 
 **Entrega:**
@@ -830,7 +830,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:orache
+/aioson:agent:orache
 ```
 
 **Entrega:**
@@ -852,7 +852,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:pentester
+/aioson:agent:pentester
 ```
 
 **Entrega:**
@@ -873,7 +873,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:profiler-researcher
+/aioson:agent:profiler-researcher
 ```
 
 **Entrega:**
@@ -892,7 +892,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:profiler-enricher
+/aioson:agent:profiler-enricher
 ```
 
 **Entrega:**
@@ -911,7 +911,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:profiler-forge
+/aioson:agent:profiler-forge
 ```
 
 **Entrega:**
@@ -930,7 +930,7 @@ npx @jaimevalasek/aioson scan:project . --folder=src
 
 **Como ativar:**
 ```
-/aioson:agent:site-forge
+/aioson:agent:site-forge
 ```
 
 **Exemplos de uso:**
@@ -956,7 +956,7 @@ Extraia o design de https://exemplo.com como uma skill
 
 **Como ativar:**
 ```
-/aioson:agent:validator
+/aioson:agent:validator
 ```
 
 **Entrega:**
@@ -972,22 +972,20 @@ Extraia o design de https://exemplo.com como uma skill
 ```
 Duração típica: minutos a horas. Sem análise, sem arquitetura formal.
 
-### SMALL
+### SMALL — lean lane (padrão v1.35.0)
 ```
-@setup → @product → [@sheldon] → @analyst → @architect → @dev → @qa → [@tester]
+@setup → @product → @sheldon → @dev → @qa → [@tester]
 ```
-Duração típica: horas a dias. Análise leve, estrutura clara.
+Duração típica: horas a dias. `@sheldon` é a autoridade única de spec: produz requirements + decisões técnicas + plano faseado + harness-contract (Gates A/B/C) em uma passada. `@analyst`, `@architect`, `@scope-check` são detours opt-in.
 
-### MEDIUM
+### MEDIUM — maestro lane (v1.35.0)
 ```
-@setup → @product → [@sheldon] → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @pentester → @qa → [@tester]
+@setup → @product → [@sheldon] → @orchestrator → @dev → @pentester → @qa → [@tester]
 ```
-Duração típica: dias a semanas. Análise completa, paralelismo, backlog formal, revisao adversarial obrigatoria.
-
-> O `@pentester` entra obrigatoriamente em projetos MEDIUM entre `@dev` e `@qa`. Em projetos sensiveis ou com requisitos de seguranca, ative-o tambem em SMALL.
+Duração típica: dias a semanas. `@orchestrator` é o maestro de spec: faz fan-out para `@analyst` + `@architect` + `@pm` (+ `@ux-ui` quando UI-heavy) como sub-agentes, consolida e verifica os artefatos. `@pentester` é inline (entre `@dev` e `@qa`).
 
-`[@sheldon]` — opcional, recomendado antes de iniciar a cadeia de execução para validar o PRD.
-`[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`.
+> `[@sheldon]` — opcional no MEDIUM como pré-etapa antes do `@orchestrator` para endurecer o PRD.
+> `[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.30.2",
+  "version": "1.36.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",
@@ -42,7 +42,7 @@
     "test:genome-2.0:block-a": "node scripts/smoke/genome-2.0-smoke.js && npm run test:genome && npm test && npm run lint",
     "test:genome-2.0:rollout": "node scripts/testing/genome-2.0-rollout.js",
     "lint": "node scripts/check-js.js",
-    "sync:agents": "node src/commands/sync-agents-preflight.js && rsync -av --progress --exclude='config.md' --exclude='runtime/' --exclude='backups/' --exclude='mcp/servers.local.json' template/ ./",
+    "sync:agents": "node src/commands/sync-agents-preflight.js && node src/commands/sync-agents-copy.js",
     "ci": "npm run lint && npm test"
   },
   "dependencies": {

package/src/artifact-kinds.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * Canonical map: which agents produce a `verify:artifact`-checkable artifact at
+ * session end, the kind, and how that artifact's path is resolved.
+ *
+ *   needs: 'none'  — self-resolving (fixed path); the engine can prove it at
+ *                    `agent:done` with no extra input.
+ *   needs: 'slug'  — path keyed by --slug; the agent threads it into agent:done.
+ *   needs: 'file'  — date-stamped / caller-known path, threaded via --file.
+ *   needs: 'dir'   — a generated-site root, via --dir (advisory static floor only
+ *                    at agent:done; the full `npm run build` stays in the agent's
+ *                    explicit Done gate).
+ *
+ * This is the bridge that makes the periphery's done-gates AUTO-FIRE: instead of
+ * relying on each agent to remember its `## Done gate` line, `agent:done` runs the
+ * check itself (advisory, best-effort). Keep in sync with the RULESETS/ADAPTERS
+ * registry in commands/verify-artifact.js and the per-agent Done gates — it is one
+ * of the workflow agent-enumeration sites.
+ */
+const AGENT_ARTIFACT_KIND = {
+  setup: { kind: 'project-context', needs: 'none' },
+  discover: { kind: 'bootstrap', needs: 'none' },
+  committer: { kind: 'commit-message', needs: 'none' },
+  genome: { kind: 'genome', needs: 'slug' },
+  'profiler-forge': { kind: 'genome', needs: 'slug' },
+  'profiler-researcher': { kind: 'research-report', needs: 'slug' },
+  'profiler-enricher': { kind: 'enriched-profile', needs: 'slug' },
+  'design-hybrid-forge': { kind: 'hybrid-skill', needs: 'slug' },
+  copywriter: { kind: 'copy', needs: 'slug' },
+  orache: { kind: 'orache-report', needs: 'file' },
+  'site-forge': { kind: 'site', needs: 'dir', opts: { noBuild: true } }
+};
+
+const NEEDS_FLAG = { slug: '--slug=<slug>', file: '--file=<path>', dir: '--dir=<dir>' };
+
+/** Resolve an agent name (with or without a leading @) to its artifact mapping, or null. */
+function resolveAgentArtifact(agent) {
+  const name = String(agent || '').trim().replace(/^@/, '');
+  return AGENT_ARTIFACT_KIND[name] || null;
+}
+
+/**
+ * Best-effort advisory `verify:artifact` for the calling agent at `agent:done`.
+ *
+ * Returns `null` when the agent produces no checkable artifact (the common case —
+ * product, dev, qa, …). Otherwise a uniform advisory descriptor:
+ *   { kind, ok, skipped, issues?, reason }
+ * - self-resolving kinds, or locator-keyed kinds whose locator was threaded into
+ *   agent:done, run the real check (advisory — never blocks).
+ * - a locator-keyed kind with no locator yields `skipped:true` plus a one-line
+ *   hint naming the exact command, so it is surfaced instead of silently missing.
+ *
+ * Never throws — a failure here must never break the session-end registration.
+ */
+async function verifyAgentArtifact({ targetDir, agent, options = {} }) {
+  const mapping = resolveAgentArtifact(agent);
+  if (!mapping) return null;
+  const { kind, needs } = mapping;
+  const slug = options.slug ? String(options.slug).trim() : null;
+  const file = options.file ? String(options.file).trim() : null;
+  const dir = options.dir ? String(options.dir).trim() : null;
+
+  const missingLocator =
+    (needs === 'slug' && !slug) || (needs === 'file' && !file) || (needs === 'dir' && !dir);
+  if (missingLocator) {
+    const flag = NEEDS_FLAG[needs];
+    return {
+      kind,
+      ok: true,
+      skipped: true,
+      reason: `needs ${flag} — run: aioson verify:artifact . --kind=${kind} ${flag} --advisory`
+    };
+  }
+
+  try {
+    const { runVerifyArtifact } = require('./commands/verify-artifact');
+    const report = await runVerifyArtifact({
+      args: [targetDir],
+      options: {
+        kind,
+        slug,
+        file,
+        dir,
+        advisory: true,
+        suppressExitCode: true,
+        json: true,
+        ...(mapping.opts && mapping.opts.noBuild ? { 'no-build': true } : {})
+      },
+      logger: { log() {}, error() {}, warn() {} }
+    });
+    if (!report) return null;
+    const issues = report.issues || [];
+    const head = issues.slice(0, 3).join('; ');
+    const more = issues.length > 3 ? ` (+${issues.length - 3} more)` : '';
+    return {
+      kind,
+      ok: Boolean(report.ok),
+      skipped: false,
+      issues,
+      reason: report.ok
+        ? null
+        : `${head}${more} — advisory; see .aioson/context/verify-artifact-${kind}.json`
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { AGENT_ARTIFACT_KIND, resolveAgentArtifact, verifyAgentArtifact };