@jaimevalasek/aioson 1.30.2 → 1.36.0

package/docs/en/4-agents/README.md

@@ -6,28 +6,40 @@ Cards are being translated progressively. Until a card is available here, the PT
 
 ---
 
+## Default lanes (v1.35.0)
+
+| Classification | Default lane |
+|---|---|
+| **MICRO** | `@product → @dev → @qa` |
+| **SMALL** (lean — default) | `@product → @sheldon → @dev → @qa` |
+| **MEDIUM** (maestro) | `@product → @orchestrator → @dev → @pentester → @qa` |
+
+`@sheldon` (SMALL) and `@orchestrator` (MEDIUM) are the **single spec authorities** for their respective sizes. Agents like `@analyst`, `@architect`, `@pm`, `@ux-ui`, `@scope-check`, and `@discovery-design-doc` are **opt-in detours** or **fan-out sub-agents** — none deleted, none in the default hop sequence.
+
+---
+
 ## The 29 agents (plus @pair alias)
 
-### Workflow core (pipeline order)
+### Workflow core
 
 | Agent | Role |
 |---|---|
 | `@setup` | Project onboarding — detect stack, classify MICRO/SMALL/MEDIUM, write `project.context.md` |
 | `@briefing` | Pre-PRD framing — turn `plans/` sketches into structured briefings with gap analysis |
 | `@product` | PRD — vision, problem, users, scope, acceptance criteria |
-| `@sheldon` | PRD quality guardian — gap detection, web research, sizing, in-place enrichment or phased plan |
-| `@analyst` | Domain discovery — entities, flows, brownfield mapping |
-| `@scope-check` | Alignment gate before implementation — validates intent vs plan and catches scope drift |
-| `@architect` | Technical decisions — structure, libraries, integration boundaries |
-| `@ux-ui` | Design system and UI component specs (MEDIUM) |
-| `@pm` | Backlog and user stories (MEDIUM) |
-| `@orchestrator` | Parallel lane coordination (MEDIUM) |
-| `@dev` | Feature implementation — any stack |
-| `@qa` | Risk-first review, test generation, autonomous fix/test loop |
-| `@validator` | Binary contract verification against `harness-contract.json` |
+| `@sheldon` | **SMALL single spec authority** (RF-LEAN): one pass produces requirements + spec (Gates A/B/C) + design-doc + readiness + implementation-plan + harness-contract. Also a PRD-hardening / enrichment capability usable in any lane. |
+| `@analyst` | Domain discovery — entities, flows, brownfield mapping. **Opt-in detour / fan-out sub-agent** (invoked by `@orchestrator` in MEDIUM) |
+| `@scope-check` | Scope-drift gate — `spec:analyze` runs **automatically** at the `@dev`/`@qa` done gate; also available as an explicit detour |
+| `@architect` | Technical decisions — structure, libraries, integration boundaries. **Opt-in detour / fan-out sub-agent**; runs in **merged mode** (also produces design-doc + readiness + dev-state) when `@discovery-design-doc` is omitted |
+| `@ux-ui` | UI/UX spec — **opt-in detour** for UI-heavy specs; `@dev` applies design skills directly by default |
+| `@pm` | Backlog, user stories, implementation plan (Gate C). **Opt-in detour / fan-out sub-agent** (MEDIUM) |
+| `@orchestrator` | **MEDIUM maestro / single spec authority** — fans out `@analyst`/`@architect`/`@pm` (+ `@ux-ui` for UI-heavy) as sub-agents, consolidates the gated spec package. Secondary: coordinate parallel `@dev` lanes post-spec. |
+| `@dev` | Feature implementation — any stack. Runs the plan as a **phase loop**: auto-continues between phases, per-phase verification (light sub-agent), context compaction between phases. Full Runtime smoke runs once at end-of-feature. |
+| `@qa` | Risk-first review, test generation, autonomous fix/test loop (cap 2). Owns Gate D: **Runtime smoke gate** (build + migrations on real DB + boot + Core happy-path on REAL stack). |
+| `@validator` | Binary contract verification against `harness-contract.json` in a **fresh isolated context** (detour when a harness contract exists) |
 | [`@forge-run`](./forge-run.md) | Lane B (opt-in) — compile a MEDIUM feature's specs into an executable workflow and run it (`forge:compile`) |
-| `@tester` | Systematic test engineering — legacy and coverage gaps |
-| `@pentester` | Adversarial security review — OWASP Top 10, LLM Top 10, supply chain |
+| `@tester` | Systematic test engineering — legacy and coverage gaps. Triggered by `@qa` when conditions fire. |
+| `@pentester` | Adversarial security review — OWASP Top 10, LLM Top 10, supply chain. Inline in MEDIUM; opt-in in SMALL. |
 
 ### Continuity & delivery
 
@@ -51,10 +63,12 @@ Cards are being translated progressively. Until a card is available here, the PT
 | `@design-hybrid-forge` | Combine two design skills into a hybrid |
 | `@orache` | Domain investigation and strategic research |
 | `@copywriter` | Conversion copy — landing pages, VSL scripts |
-| [`@discovery-design-doc`](./discovery-design-doc.md) | Discovery, readiness, and design doc package |
+| [`@discovery-design-doc`](./discovery-design-doc.md) | Discovery, readiness, and design doc package — opt-in; absorbed by `@architect` merged mode, `@sheldon`, or `@orchestrator` by default |
 
 ---
 
 For the executable-verification theme that `@forge-run`, `@validator`, `@scope-check`, `@sheldon`, and `@pm` participate in, see [Executable verification](../5-reference/executable-verification.md).
 
+For the full lane walkthrough and opt-in detour guide, see [Full feature with @sheldon](../3-recipes/full-feature-with-sheldon.md).
+
 Full PT cards with dialogue examples, disk outputs, and handoff maps: [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md)

package/docs/en/4-agents/discovery-design-doc.md

@@ -14,9 +14,9 @@
 `@discovery-design-doc` has two valid uses:
 
 - **Exploratory mode:** when a request is still vague, such as a ticket, feature idea, or meeting note. It normalizes the problem, identifies ambiguities, and recommends the next agent.
-- **Pre-dev workflow mode:** when a SMALL/MEDIUM project has already passed through `@analyst` and `@architect`. In this case, it consolidates PRD, requirements, spec, and architecture into a living `design-doc` and a `readiness` note with a concrete technical plan for `@dev`.
+- **Explicit pre-dev opt-in:** when you want a standalone design doc + readiness package between the spec phase and `@dev`. In the default SMALL lean and MEDIUM maestro lanes, this role is absorbed by `@sheldon` (SMALL) or `@architect` in merged mode / `@orchestrator` (MEDIUM) — invoke `@discovery-design-doc` explicitly only when you need it as a separate step.
 
-So it can be either a shortcut before the full cycle **or** a safety stage between architecture and implementation. In the current workflow, the second use is expected for SMALL/MEDIUM.
+**Note (v1.35.0):** this agent is **not in the default hop sequence** for either SMALL or MEDIUM. It is an opt-in detour.
 
 ---
 
@@ -43,25 +43,37 @@ So it can be either a shortcut before the full cycle **or** a safety stage betwe
 
 ## Where it fits in the workflow
 
-Manual exploratory flow:
+**Manual exploratory flow** (unchanged):
 
 ```text
 @setup -> @discovery-design-doc -> recommended next agent
 ```
 
-Current SMALL flow:
+**Default SMALL lean flow** — this agent is absorbed by `@sheldon`:
 
 ```text
-@product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> @qa
+@product -> @sheldon -> @dev -> @qa
 ```
 
-Current MEDIUM flow:
+**Opt-in SMALL detour** (explicit invocation after @sheldon or between @analyst and @dev):
 
 ```text
-@product -> @analyst -> @architect -> @discovery-design-doc -> @ux-ui -> @pm -> @orchestrator -> @scope-check(pre-dev) -> @dev -> @qa
+@product -> @sheldon -> [@analyst] -> @discovery-design-doc -> @dev -> @qa
 ```
 
-Its role in the middle of a feature is not to replace `@analyst` or `@architect`. It turns those artifacts into an executable implementation package.
+**Default MEDIUM maestro flow** — this agent is absorbed by `@orchestrator` (via `@architect` sub-agent in merged mode):
+
+```text
+@product -> @orchestrator -> @dev -> @pentester -> @qa
+```
+
+**Opt-in MEDIUM detour** (explicit invocation after @orchestrator):
+
+```text
+@product -> @orchestrator -> @discovery-design-doc -> @dev -> @pentester -> @qa
+```
+
+When invoked, its role is not to replace `@analyst` or `@architect` — it turns those artifacts into an executable implementation package.
 
 ---
 

package/docs/en/4-agents/forge-run.md

@@ -57,8 +57,9 @@ Lane B only compiles when every prerequisite is present — otherwise the hard p
 Lane B is an opt-in branch off the standard MEDIUM flow, taken after the spec and plan are ready:
 
 ```text
-@product -> @analyst -> @architect -> @sheldon (authors verification) ->
-@pm (Wave column) -> @scope-check (spec:analyze clean) -> @forge-run (Lane B)
+@product -> @orchestrator (fans out @analyst/@architect/@pm; @pm fills Wave column;
+             @orchestrator or @sheldon authors harness-contract verification fields) ->
+spec:analyze clean (scope-drift gate) -> @forge-run (Lane B)
 ```
 
 It never replaces the default lane — it compiles the same artifacts into a single executable workflow. (`@pm`, `@sheldon`, and `@validator` cards are tracked in the [agents index](./README.md); PT is canonical until each is translated.)

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

@@ -300,22 +300,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.
 
 ---
 
@@ -677,53 +680,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 +823,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, correction plans, dossier FAIL→PASS cycles, execution events, attempt artifacts, failure signatures, devlogs.
+**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`.
 
@@ -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,23 +68,25 @@
 
 ### 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` |
 | **`@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`) |
@@ -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:**

package/docs/pt/2-comecar/primeiro-projeto.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/`) |