@jaimevalasek/aioson 1.33.1 → 1.37.0

package/docs/en/5-reference/cli-reference.md

@@ -73,6 +73,8 @@ aioson update --lang=pt-BR
 
 **What it updates:** all files in the `MANAGED_FILES` list that match your install profile (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
 
+**Output:** on completion, prints `Template version applied: <version>` (and `(<sha>, <date>)` when the install is a git checkout — e.g. an `npm link`ed dogfood setup) so you can tell exactly which template landed.
+
 ---
 
 ## info
@@ -300,22 +302,25 @@ Notes:
   — Framework not installed: agents will include installation steps.
 ```
 
-**Sequences by classification:**
-- `MICRO`: `@setup → @product (optional) → @dev`
-- `SMALL`: `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
-- `MEDIUM`: `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
+**Sequences by classification (v1.35.0):**
+- `MICRO`: `@setup → @product → @dev → @qa`
+- `SMALL` (lean default): `@setup → @product → @sheldon → @dev → @qa` — `@sheldon` is the single spec authority
+- `MEDIUM` (maestro): `@setup → @product → @orchestrator → @dev → @pentester → @qa` — `@orchestrator` fans out `@analyst`/`@architect`/`@pm` as sub-agents
+
+Spec agents (`@analyst`, `@architect`, `@pm`, `@ux-ui`, `@scope-check`, `@discovery-design-doc`) are **opt-in detours** or fan-out sub-agents — not default hops.
 
 **Feature development workflow (after initial setup):**
 
 Once the project is set up, each new feature follows a shorter sequence — no `@setup` required:
 
 ```
-/aioson:agent:product → @analyst → @scope-check → @dev → @qa
+SMALL:  /aioson:agent:product → @sheldon → @dev → @qa
+MEDIUM: /aioson:agent:product → @orchestrator → @dev → @pentester → @qa
 ```
 
-`@product` creates a feature-scoped `prd-{slug}.md` and registers the feature in `features.md`. `@analyst` produces `requirements-{slug}.md` and `spec-{slug}.md`. `@scope-check` compares intent against the planned implementation before coding. `@dev` reads the feature spec. `@qa` closes the feature by running `feature:close --verdict=PASS`, which updates `spec-{slug}.md` with a QA sign-off, marks it `done` in `features.md`, and automatically archives all feature artefacts to `.aioson/context/done/{slug}/`.
+`@product` creates a feature-scoped `prd-{slug}.md`. `@sheldon` (SMALL) produces the full spec package: requirements, design-doc, readiness, implementation-plan, and harness-contract. `@orchestrator` (MEDIUM) fans out `@analyst`/`@architect`/`@pm` and consolidates the gated spec package. `@dev` runs the implementation-plan phase by phase. `@qa` closes the feature by running `feature:close --verdict=PASS`, which updates `spec-{slug}.md` with a QA sign-off, marks it `done` in `features.md`, and automatically archives all feature artefacts to `.aioson/context/done/{slug}/`.
 
-The `SMALL` and MEDIUM outputs include a note reminding you of this sequence.
+The `SMALL` and `MEDIUM` outputs include a note reminding you of this sequence.
 
 ---
 
@@ -343,6 +348,10 @@ aioson workflow:next ./my-project --skip=dev
 - `agent:next` is an alias for compatibility
 - `workflow.config.json` and `workflow.state.json` live under `.aioson/context/`, so normal framework updates preserve them
 
+### workflow:execute --seed (full-feature autopilot)
+
+`aioson workflow:execute . --feature=<slug> --seed --tool=<tool>` seeds the agentic scheme (`.aioson/context/workflow-execute.json` with `agentic_policy.enabled: true`) without advancing a stage — this is what a spec agent (`@product`/`@sheldon`/`@orchestrator`) runs on its own once it finishes, to arm the full-feature autopilot chain described in [Autopilot handoff](./autopilot-handoff.md). Add `--step` to seed it already disarmed (equivalent to the inline `--step` token). A stale `workflow.state.json` left by a closed/abandoned feature is discarded and reseeded automatically; a genuinely different active feature returns `different_active_feature` — close/pause it, or run `aioson feature:sweep .` to discard stale state explicitly.
+
 ---
 
 ## feature:close
@@ -677,53 +686,53 @@ aioson harness:check . --slug=checkout
 # Run only a subset of criteria
 aioson harness:check . --slug=checkout --criteria=C1,C3
 
-# Custom timeout and JSON output (exit 0 = pass)
-aioson harness:check . --slug=checkout --timeout=120000 --json
-
-# Strict mode: binary criteria without verification block the result
-aioson harness:check . --slug=checkout --strict
+# Custom timeout and JSON output (exit 0 = pass)
+aioson harness:check . --slug=checkout --timeout=120000 --json
+
+# Strict mode: binary criteria without verification block the result
+aioson harness:check . --slug=checkout --strict
 ```
 
 **Options:**
 - `--slug=<feature>` — feature slug matching the harness contract. If omitted, the active contract is auto-discovered.
-- `--criteria=C1,C2` — run only the listed criteria instead of all verifiable ones.
-- `--timeout=<ms>` — per-criterion timeout override.
-- `--strict` — fail when binary criteria lack executable `verification` or no executable criterion exists.
-- `--json` — structured output; exit code propagated.
+- `--criteria=C1,C2` — run only the listed criteria instead of all verifiable ones.
+- `--timeout=<ms>` — per-criterion timeout override.
+- `--strict` — fail when binary criteria lack executable `verification` or no executable criterion exists.
+- `--json` — structured output; exit code propagated.
 
 **What it does:** the `verification` field is authored per criterion by `@sheldon` for every mechanically-checkable `binary: true` criterion (prefer the project test runner; deterministic; cross-platform; exit 0 = pass). `harness:check` is the standalone deterministic verification of those criteria — it never touches the circuit-breaker state (that stays exclusive to `harness:validate`/`apply-validation`). Legacy contracts without `verification` remain valid; `validateContract` only emits an advisory **warning** for `binary: true` criteria lacking it. `@validator` runs `harness:check` first and copies the exit-code verdicts verbatim into `results[].passed`, LLM-judging only the criteria without `verification`.
 
-See [Executable verification](./executable-verification.md) for the full theme.
-
----
-
-## ac:test-audit
-
-Map declared acceptance criteria to deterministic test evidence.
-
-```bash
-aioson ac:test-audit . --feature=checkout
-aioson ac:test-audit . --feature=checkout --json
-```
-
-**What it does:** extracts `AC-*` IDs from `requirements-{slug}.md`, `prd-{slug}.md`, and `conformance-{slug}.yaml`, then checks whether each ID appears in a test file or an executable harness criterion. Gate D treats missing evidence as blocking when ACs are declared.
-
----
-
-## sdd:benchmark
-
-Generate a deterministic SDD quality snapshot for a feature.
-
-```bash
-aioson sdd:benchmark . --feature=checkout
-aioson sdd:benchmark . --feature=checkout --strict --json
-```
-
-**What it does:** combines artifact presence, `spec:analyze`, and `ac:test-audit` into a reproducible score and writes `.aioson/context/retro/sdd-benchmark-{slug}.md`.
-
----
-
-## harness:validate
+See [Executable verification](./executable-verification.md) for the full theme.
+
+---
+
+## ac:test-audit
+
+Map declared acceptance criteria to deterministic test evidence.
+
+```bash
+aioson ac:test-audit . --feature=checkout
+aioson ac:test-audit . --feature=checkout --json
+```
+
+**What it does:** extracts `AC-*` IDs from `requirements-{slug}.md`, `prd-{slug}.md`, and `conformance-{slug}.yaml`, then checks whether each ID appears in a test file or an executable harness criterion. Gate D treats missing evidence as blocking when ACs are declared.
+
+---
+
+## sdd:benchmark
+
+Generate a deterministic SDD quality snapshot for a feature.
+
+```bash
+aioson sdd:benchmark . --feature=checkout
+aioson sdd:benchmark . --feature=checkout --strict --json
+```
+
+**What it does:** combines artifact presence, `spec:analyze`, and `ac:test-audit` into a reproducible score and writes `.aioson/context/retro/sdd-benchmark-{slug}.md`.
+
+---
+
+## harness:validate
 
 Generate the `validator-prompt.txt` for the binary success contract and append a self-contained **review payload** so the validator can judge in a fresh, isolated context. Consumes the verdict back through the circuit breaker.
 
@@ -820,7 +829,7 @@ aioson harness:retro . --feature=checkout --json
 
 **Exit codes:** 0 = success (including empty dossier); 1 = unexpected I/O error; 12 = input error (invalid slug, conflicting flags, feature not found).
 
-**Sources mined:** QA reports, implementation verification reports (non-confirming `Machine Report` findings only), correction plans, dossier FAIL→PASS cycles, execution events, attempt artifacts, failure signatures, devlogs. Raw auditor output, stderr, prompt packages, and finding evidence text are not mined.
+**Sources mined:** QA reports, implementation verification reports (non-confirming `Machine Report` findings only), correction plans, dossier FAIL→PASS cycles, execution events, attempt artifacts, failure signatures, devlogs. Raw auditor output, stderr, prompt packages, and finding evidence text are not mined.
 
 ---
 

package/docs/en/5-reference/executable-verification.md

@@ -10,7 +10,7 @@
 
 ## The idea in one paragraph
 
-AIOSON already has two strong foundations: the **`harness-contract.json`** (binary success criteria per feature) and the **SDD artifact chain** (PRD → spec → plan → conformance). The executable-verification theme builds on both to make verification **deterministic** (run a command, read an exit code) and to make specs **compilable** (turn a ready spec into an auditable workflow). Everything is **additive**: the default lane — `@scope-check` → `@dev` → `@qa` → `@validator` — is **unchanged**. The new pieces tighten the verification surface without rerouting existing flows.
+AIOSON already has two strong foundations: the **`harness-contract.json`** (binary success criteria per feature) and the **SDD artifact chain** (PRD → spec → plan → conformance). The executable-verification theme builds on both to make verification **deterministic** (run a command, read an exit code) and to make specs **compilable** (turn a ready spec into an auditable workflow). Everything is **additive**: the default SMALL lean lane (`@sheldon → @dev → @qa`) and MEDIUM maestro lane (`@orchestrator → @dev → @pentester → @qa`) are **unchanged** in structure. The new pieces tighten the verification surface — `@scope-check`'s `spec:analyze` now runs **automatically at the `@dev`/`@qa` done gate** (scope-drift gate) in addition to being available as an explicit detour. `@validator` remains a detour when a harness contract exists.
 
 The theme ships in five phases.
 
@@ -97,7 +97,7 @@ It runs five deterministic checks:
 4. **Harness-contract sanity** — schema errors = error; executable-coverage = info.
 5. **AC→contract linkage** = info.
 
-An `error` flips `ok: false` (exit 1 in `--json`). Results persist to `spec-analyze-{slug}.json`. `@scope-check` runs `spec:analyze` in preflight: **errors are blockers, warnings are pre-computed drift evidence**.
+An `error` flips `ok: false` (exit 1 in `--json`). Results persist to `spec-analyze-{slug}.json`. `spec:analyze` runs **automatically at the `@dev`/`@qa` done gate** (scope-drift gate) — errors block completion, warnings are pre-computed drift evidence. `@scope-check` also runs it in preflight when invoked as an explicit detour.
 
 See [`spec:analyze`](./cli-reference.md#specanalyze) in the CLI reference.
 
@@ -143,15 +143,18 @@ See [`forge:compile`](./cli-reference.md#forgecompile) in the CLI reference and
 ## How the phases fit together
 
 ```text
-@sheldon authors verification ──► harness:check (deterministic, exit 0 = pass)   [Phase 1]
+@sheldon (SMALL) / @orchestrator (MEDIUM) authors verification
+                          ──► harness:check (deterministic, exit 0 = pass)         [Phase 1]
                                         │
-@scope-check runs spec:analyze ◄────────┤  (errors block, warnings = drift)       [Phase 3]
+spec:analyze runs automatically ◄───────┤  at @dev/@qa done gate (scope-drift)    [Phase 3]
+  (also: @scope-check preflight)        │  (errors block, warnings = drift evidence)
 @pm fills the Wave column ──────────────┤  (parallelizable, file-disjoint)        [Phase 4]
                                         │
-default lane:  @dev ► @qa ► harness:validate (review payload)                      [Phase 2]
-                              └► @validator in a FRESH, ISOLATED context
+SMALL lane:   @sheldon ► @dev ► @qa ► harness:validate (review payload)            [Phase 2]
+MEDIUM lane:  @orchestrator ► @dev ► @pentester ► @qa ► harness:validate
+                              └► @validator in a FRESH, ISOLATED context (detour)
                                         │
-Lane B (opt-in):  @forge-run ► forge:compile ► run the compiled workflow          [Phase 5]
+Lane B (opt-in):  @forge-run ► forge:compile ► run the compiled workflow           [Phase 5]
 ```
 
 The default lane and Lane B consume the **same** contract, plan, and `spec:analyze` results — Lane B just compiles them into one executable script.

package/docs/en/5-reference/parallel.md

@@ -1,5 +1,7 @@
 # Parallel Orchestration Guide
 
+> **v1.35.0 context:** In the MEDIUM maestro lane, `@orchestrator` is the **single spec authority** — it fans out `@analyst`/`@architect`/`@pm` as sub-agents, consolidates the gated spec package, and produces the parallel lane files that the commands below manage. The lane files (`agent-N.status.md`, `shared-decisions.md`) are part of the spec package handed to `@dev`.
+
 Use `parallel:init` to bootstrap the parallel context files used by `@orchestrator`.
 
 ## Command

package/docs/en/5-reference/qa-browser.md

@@ -258,8 +258,8 @@ This means running `aioson qa:run` before `@qa` gives you a richer, more complet
 Two terminals, running in parallel:
 
 ```bash
-# Terminal 1 — aioson agents
-/aioson:agent:setup → @product → @analyst → @architect → @dev
+# Terminal 1 — aioson agents (SMALL lean example)
+/aioson:agent:setup → @product → @sheldon → @dev
 
 # Terminal 2 — browser QA (while app is running)
 aioson qa:init --url=http://localhost:3000

package/docs/en/README.md

@@ -23,7 +23,7 @@ This is the entry door to the English documentation. It is not an alphabetical i
 ### I want a recipe ready for my case
 
 **Canonical trails — how features reach the dev:**
-1. **[Full feature with @sheldon](./3-recipes/full-feature-with-sheldon.md)** — the main trail: `@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa` (with optional gates from `@tester` and `@pentester`)
+1. **[Full feature with @sheldon](./3-recipes/full-feature-with-sheldon.md)** — SMALL lean default: `@product → @sheldon → @dev → @qa`; MEDIUM maestro: `@product → @orchestrator → @dev → @pentester → @qa`
 2. [From idea to PRD via @briefing](./3-recipes/from-idea-to-prd-via-briefing.md) — when the idea is still vague
 3. [Continuity between sessions](./3-recipes/continuity-between-sessions.md) — feature dossier, dev-resume, drift detection
 
@@ -40,7 +40,7 @@ This is the entry door to the English documentation. It is not an alphabetical i
 See [3-recipes/README.md](./3-recipes/README.md) for the full list.
 
 ### I want the technical reference for an agent or command
-- **[Agent cards (in progress)](./4-agents/README.md)** — stub today; full set is in [docs/pt/4-agentes/](../pt/4-agentes/README.md) (29 cards)
+- **[Agent cards (in progress)](./4-agents/README.md)** — stub today; full set is in [docs/pt/4-agentes/](../pt/4-agentes/README.md) (29 cards)
 - **[Technical reference](./5-reference/README.md)** — 11 docs migrated from the previous flat structure (CLI, MCP, parallel, QA browser, squad dashboard, web3, i18n, JSON schemas, release flow)
 
 ### Highlights of `5-reference/`
@@ -109,7 +109,7 @@ This English portal is being **incrementally translated** from `docs/pt/`. The p
 - 4-agents (stub README; full agent cards pending)
 
 **Phase 2 (next)** — remaining 8 scenario recipes in 3-recipes/.
-**Phase 3 (next)** — 29 agent cards in 4-agents/.
+**Phase 3 (next)** — 29 agent cards in 4-agents/.
 **Phase 4 (next)** — remaining ~18 reference docs in 5-reference/ (feature-dossier, agent-chain-continuity, sdd-framework, live-sessions, secure-by-default, aioson-com-store, etc.).
 
 For anything not yet in English, the PT version is current and authoritative — the AIOSON behaviors, agent prompts, and CLI commands are language-agnostic.

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

@@ -72,9 +72,9 @@ Termos em ordem alfabética. Cada um tem **definição curta** + **exemplo concr
 **Definição:** o tamanho do projeto, calculado a partir de 3 fatores (tipos de usuário, integrações externas, regras de negócio). Define quanta cerimônia o workflow vai aplicar.
 
 **Como funciona:**
-- 0–1 ponto → **MICRO** (`@setup → @product → @dev`)
-- 2–3 pontos → **SMALL** (`@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`)
-- 4–6 pontos → **MEDIUM** (workflow completo, todos os gates, todos os artefatos)
+- 0–1 ponto → **MICRO** (`@setup → @product → @dev → @qa`)
+- 2–3 pontos → **SMALL** — lean lane: `@setup → @product → @sheldon → @dev → @qa` (`@sheldon` é a autoridade única de spec)
+- 4–6 pontos → **MEDIUM** — maestro lane: `@setup → @product → @orchestrator → @dev → @pentester → @qa` (`@orchestrator` faz fan-out de spec)
 
 **Onde aparece:** `classification:` no frontmatter do `project.context.md`.
 
@@ -129,7 +129,7 @@ Termos em ordem alfabética. Cada um tem **definição curta** + **exemplo concr
 
 **Exemplos prontos:** Clean SaaS UI, Aurora Command UI, Cognitive Core UI, Bold Editorial UI, Warm Craft UI, Glassmorphism UI, Neo Brutalist UI.
 
-**Onde escolher:** durante o `aioson init`, no wizard.
+**Onde escolher:** durante o `aioson init`, no wizard, ou depois com `@setup`/`@ux-ui`. A rota recomendada é o motor `interface-design` guiado pelas suas **imagens de referência**, extraídas uma única vez num `identity.md` que o motor aplica; os presets ficam como alternativa explícita.
 
 ---
 
@@ -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:scaffold`, `squad:agent-create`, `squad:doctor`.
+**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 29 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.
 
 ---
 
@@ -68,25 +68,27 @@
 
 ### 2. Núcleo de desenvolvimento (workflow oficial)
 
-A ordem padrão depende da classificação:
+A ordem padrão depende da classificação (v1.35.0):
 
-**MICRO:** `@setup → @product (opcional) → @dev`
-**SMALL:** `@setup → @product → @sheldon (opcional) → @analyst → @scope-check → @architect → @dev → @qa`
-**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
+**MICRO:** `@setup → @product → @dev → @qa`
+**SMALL (lean — padrão):** `@setup → @product → @sheldon → @dev → @qa`
+**MEDIUM (maestro):** `@setup → @product → @orchestrator → @dev → @pentester → @qa`
 
-> **Por que `@sheldon` aparece tão cedo?** Ele é o **PRD quality guardian** — roda *entre* `@product` e `@analyst` para detectar gaps, validar premissas técnicas com pesquisa web, e decidir entre enriquecer o PRD in-place ou criar um phased plan em `.aioson/plans/{slug}/`. Pode ser invocado N vezes no mesmo PRD. Pular essa etapa em features sérias custa caro lá na frente.
+> **Por que `@sheldon` substitui toda a cadeia de spec no SMALL?** Ele é a **autoridade única de spec**: em uma passada vertical produz requirements + decisões técnicas + design-doc + readiness + plano de implementação + harness-contract (Gates A/B/C aprovados). `@analyst`, `@architect`, `@scope-check` e outros viram **detours opt-in**, não hops padrão.
+
+> **Por que `@orchestrator` substitui a cadeia longa no MEDIUM?** Ele é o **maestro de spec**: faz fan-out para `@analyst`, `@architect`, `@pm` (+ `@ux-ui` quando UI-heavy) como sub-agentes, consolida e verifica os artefatos. Mesma qualidade, menos hops manuais.
 
 | Agente | O que faz | Saída principal |
 |---|---|---|
 | **`@product`** | Define visão, escopo, PRD da feature | `prd.md`, `spec.md` |
-| **`@sheldon`** | PRD quality guardian — gap analysis, web research, sizing, decide in-place vs phased plan | `sheldon-enrichment-{slug}.md` ou `.aioson/plans/{slug}/` |
-| **`@analyst`** | Descobre domínio, entidades, fluxos no codebase | `architecture.md`, ER diagrams |
-| **`@architect`** | Decisões técnicas: estrutura, libs, integração | `architecture.md` (decisões) |
-| **`@ux-ui`** | Design system e specs de componentes (MEDIUM) | `design-doc.md`, `discovery.md` |
-| **`@pm`** | Backlog, user stories, ACs (MEDIUM) | `tasks.md`, user stories |
-| **`@orchestrator`** | Coordena lanes paralelas (MEDIUM) | `parallel/`, plano de execução |
+| **`@sheldon`** | **SMALL:** autoridade única de spec (vertical/solo) — produz requirements + decisões técnicas + plano + harness-contract (Gates A/B/C) em uma passada. **Qualquer lane:** gap analysis, pesquisa web, endurecimento de PRD. | `sheldon-enrichment-{slug}.md`, `requirements-{slug}.md`, `implementation-plan-{slug}.md`, `harness-contract.json` |
+| **`@analyst`** | Discovery de domínio: entidades, fluxos, regras de negócio. **MEDIUM:** sub-agente do `@orchestrator`. **Qualquer tamanho:** detour opt-in. | `requirements-{slug}.md`, ER diagrams |
+| **`@architect`** | Decisões técnicas: estrutura, libs, integração. **Merged mode:** também produz design-doc + readiness quando `@discovery-design-doc` não está no fluxo. **MEDIUM:** sub-agente do `@orchestrator`. **Qualquer tamanho:** detour opt-in. | `architecture.md` |
+| **`@ux-ui`** | Spec de UI/UX e componentes. **MEDIUM com UI pesada:** sub-agente do `@orchestrator`. **Qualquer tamanho:** detour opt-in. | `design-doc.md` |
+| **`@pm`** | Backlog, user stories, plano de implementação. **MEDIUM:** sub-agente do `@orchestrator`. **Qualquer tamanho:** detour opt-in. | `tasks.md`, `implementation-plan-{slug}.md` |
+| **`@orchestrator`** | **MEDIUM:** maestro de spec (faz fan-out para @analyst/@architect/@pm/@ux-ui, consolida e verifica, entrega pacote de spec com Gates A/B/C). Também coordena lanes paralelas de implementação pós-spec. | `parallel/`, `implementation-plan-{slug}.md`, `harness-contract.json` |
 | **`@dev`** | Implementa a feature | Código + `dev-state.md` |
-| **`@qa`** | Escreve testes, valida ACs, ciclo autônomo de correção (cap 2) | `test-plan.md`, `qa-report-*.md` |
+| **`@qa`** | Escreve testes, valida ACs, ciclo autônomo de correção (cap 3), hub do autopilot pós-dev (roteia para `@tester`/`@pentester`/`@validator`) | `test-plan.md`, `qa-report-*.md` |
 | **`@validator`** | Valida tecnicamente contra `harness-contract.json` em sandbox de contexto | `.aioson/plans/{slug}/last-validator-output.json` (consumido por `harness:apply-validation`, atualiza `progress.json`) |
 | **`@tester`** | Engenharia sistemática de testes (legacy/brownfield) | `test-inventory.md`, coverage tier |
 | **`@pentester`** | Revisão adversarial de segurança (OWASP, LLM Top 10) | `security-findings-*.json` |
@@ -189,7 +191,7 @@ Você no Claude Code:
 
 ---
 
-## Diálogo real — ciclo SMALL completo
+## Diálogo real — ciclo SMALL completo (lean lane)
 
 ```
 ─── Sessão 1 ───
@@ -206,17 +208,26 @@ Você > pt-BR
 Você > @product
 @product > Vamos começar uma feature. Como ela se chama? Qual o problema?
 Você > "checkout-stripe", finalizar pedido com cartão.
-@product > [...várias perguntas...] Spec criada em context/features/checkout-stripe/spec.md.
-@product > Próximo: @analyst para mapear o domínio.
+@product > [...várias perguntas...] PRD criado em context/prd-checkout-stripe.md.
+@product > Próximo: @sheldon para produzir o pacote de spec.
 
 ─── Sessão 2 (no dia seguinte) ───
 Você > @neo
-@neo > Você parou em @product. Próximo: @analyst.
-Você > @analyst
-@analyst > [lê spec.md, examina codebase] Mapeei: Order, Customer, Payment, OrderItem.
-@analyst > Decisão registrada em architecture.md. Próximo: @architect.
-
-─── e assim por diante até @qa ───
+@neo > Você parou em @product. Próximo: @sheldon.
+Você > @sheldon
+@sheldon > [lê PRD, varre codebase, detecta 3 gaps, pesquisa fontes] Gates A/B/C aprovados.
+           Pacote de spec: requirements + architecture + implementation-plan + harness-contract.
+@sheldon > Próximo: @dev.
+
+─── Sessão 3 ───
+Você > @dev
+@dev > [lê pacote de spec, implementa por fases com auto-continue, verifica por fase]
+@dev > Todas as fases completas. dev-state.md atualizado.
+@dev > Próximo: @qa.
+
+Você > @qa
+@qa > [runtime smoke gate + 12 ACs verificados. 12/12 passando.]
+@qa > Veredicto: feature pronta.
 ```
 
 ---

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

@@ -28,12 +28,12 @@ Soma de três fatores (cada um vale 0, 1 ou 2 pontos):
 
 ### O que muda em cada uma
 
-#### MICRO — `@setup → @product (opcional) → @dev`
+#### MICRO — `@setup → @product → @dev → @qa`
 
 - Para: scripts, automações, protótipos, apps pessoais simples.
-- Não há `@analyst` nem `@architect`. Você fala direto com `@dev`.
+- Não há fase de spec formal. Você fala direto com `@dev`.
 - `@product` é opcional — você pode passar a spec direto no chat se quiser.
-- Sem `@qa` no fluxo padrão (você pode invocar manualmente).
+- `@qa` é opcional no MICRO; verificação por fase do `@dev` é suprimida para economizar tokens.
 
 **Exemplos típicos:**
 - Script Python que processa CSV
@@ -41,11 +41,11 @@ Soma de três fatores (cada um vale 0, 1 ou 2 pontos):
 - Página estática de portfólio
 - Mini-API de 3 endpoints
 
-#### SMALL — `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
+#### SMALL — lean lane (padrão) — `@setup → @product → @sheldon → @dev → @qa`
 
 - Para: a maioria dos apps reais.
-- Tem o ciclo completo de discovery+desenvolvimento+QA.
-- Sem `@ux-ui`, `@pm` ou `@orchestrator` no fluxo padrão (você pode invocar pontualmente).
+- `@sheldon` é a **autoridade única de spec**: em uma passada, produz requirements, decisões técnicas, plano de implementação e contrato de harness — com Gates A/B/C aprovados — antes de passar para `@dev`.
+- `@analyst`, `@architect`, `@scope-check` e outros agentes de spec são **detours opt-in**, não hops padrão.
 
 **Exemplos típicos:**
 - App SaaS para um único persona
@@ -53,12 +53,12 @@ Soma de três fatores (cada um vale 0, 1 ou 2 pontos):
 - Loja online simples
 - Blog com painel admin
 
-#### MEDIUM — workflow completo
+#### MEDIUM — maestro lane — `@setup → @product → @orchestrator → @dev → @pentester → @qa`
 
 - Para: produtos com múltiplos tipos de usuário, várias integrações, regras complexas.
-- Adiciona `@ux-ui`, `@pm`, `@orchestrator`.
-- Gates de qualidade aplicados em cada handoff.
-- Lanes paralelas possíveis (`@orchestrator` coordena).
+- `@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, e entrega o pacote de spec com Gates A/B/C aprovados.
+- `@pentester` é **inline** na lane (entre `@dev` e `@qa`), não apenas opt-in.
+- Lanes paralelas possíveis (`@orchestrator` também coordena a execução paralela pós-spec).
 - Threshold de contexto mais agressivo (55% — alerta cedo).
 
 **Exemplos típicos:**
@@ -99,7 +99,7 @@ Você pode marcar **mais de um** no wizard — eles convivem no mesmo projeto.
 
 ### Development (padrão)
 
-Inclui os 29 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 montar compliance
-
-# Ou via CLI
-npx @jaimevalasek/aioson squad:scaffold compliance
+# Dentro do cliente AI
+> @squad montar compliance
+
+# Ou via CLI
+npx @jaimevalasek/aioson squad:scaffold compliance
 ```
 
 **Quando ativar Squads:**
@@ -133,7 +133,9 @@ npx @jaimevalasek/aioson squad:scaffold compliance
 
 ## Escolhendo o Design System
 
-Disponíveis no wizard:
+> **Rota recomendada: `interface-design` + suas imagens de referência.** Em vez de herdar o visual idêntico de um preset fixo, você fornece imagens de referência (identidade/marca e, opcionalmente, estrutura de componentes); a skill `reference-identity-extract` as converte **uma única vez** num `identity.md` de texto que o motor `interface-design` aplica em tudo que vier depois (protótipo e build). O `@setup` oferece essa rota primeiro — sempre com confirmação explícita, nunca auto-seleção. Os presets abaixo continuam disponíveis como alternativa.
+
+Presets disponíveis no wizard:
 
 | Skill | Estilo | Casos |
 |---|---|---|
@@ -146,7 +148,7 @@ Disponíveis no wizard:
 | **Neo Brutalist UI** | Contornos pretos, cores fortes, sem sombra | Marcas marcantes |
 
 **Pular** é uma opção legítima. Você pode:
-- Escolher depois com `@ux-ui`
+- Escolher depois com `@ux-ui` — ele oferece as mesmas duas rotas (imagens de referência ou preset)
 - Clonar o design de um site real com `@site-forge`
 - Criar um híbrido com `@design-hybrid-forge` (ex: clean-saas + neo-brutalist)
 

package/docs/pt/2-comecar/primeiro-projeto.md

@@ -229,7 +229,7 @@ Você > @qa
 @qa > test-plan.md e qa-report.md gravados. Feature pronta.
 ```
 
-> **A novidade:** o ciclo *autônomo QA→Dev* (cap 2) deixa o @qa pedir correções pequenas sem você ter que reativar manualmente. Foi adicionado em Mai/2026.
+> **A novidade:** o ciclo *autônomo QA→Dev* (cap 3, `agentic_policy.review_cycle`) deixa o @qa pedir correções pequenas sem você ter que reativar manualmente. Sob autopilot, esse mesmo ciclo pode encadear até `@tester`/`@pentester`/`@validator` e a recomendação de `feature:close` sem parar — veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
 
 ---
 
@@ -276,7 +276,7 @@ Daqui a três meses, alguém (você ou outra IA) pode abrir esse projeto e enten
 
 ## E quando eu quiser uma feature nova?
 
-Volte para o passo 4. `@product` cria nova feature → `@analyst` → `@architect` → `@dev` → `@qa`. O `@setup` não precisa rodar de novo (já tem o contexto).
+Volte para o passo 4. A lane depende do tamanho da feature: **SMALL** → `@product → @sheldon → @dev → @qa`; **MEDIUM** → `@product → @orchestrator → @dev → @pentester → @qa`. O `@setup` não precisa rodar de novo (já tem o contexto).
 
 Se você se perder no meio, lembre:
 

package/docs/pt/3-receitas/README.md

@@ -8,7 +8,7 @@ Estas três trilhas mostram **como features chegam ao desenvolvimento** no AIOSO
 
 | Trilha | Quando usar | Agentes-chave |
 |---|---|---|
-| **[Feature completa com @sheldon](./feature-completa-com-sheldon.md)** | Você tem PRD em mente e quer a trilha canônica completa (a mais usada) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa |
+| **[Feature completa com @sheldon](./feature-completa-com-sheldon.md)** | Você tem PRD em mente e quer a trilha canônica (a mais usada) | SMALL: `@product → @sheldon → @dev → @qa` · MEDIUM: `@product → @orchestrator → @dev → @pentester → @qa` |
 | [Da ideia ao PRD via @briefing](./da-ideia-ao-prd-via-briefing.md) | Sua ideia ainda é vaga, várias anotações soltas | @briefing → @product |
 | [Plans externos para @product](./plans-externos-para-product.md) | Você já planejou em outro chat (ChatGPT, Claude.io Web) | @product (lê `/plans/`) |