@jaimevalasek/aioson 1.36.0 → 1.37.1

package/docs/en/5-reference/autopilot-handoff.md

@@ -0,0 +1,286 @@
+# Autopilot handoff — AIOSON (EN)
+
+> **What this is:** the reference for AIOSON's full-feature autopilot — the opt-in protocol that removes the **mechanical** handoff confirmations across the whole feature workflow, from `@product` to the `feature:close` recommendation.
+> **Reading time:** 8 min.
+> **What you will learn:**
+> - How the run mode (autopilot vs. step-by-step) is decided, and the precedence between the inline tokens, per-feature scheme, and project flag
+> - How the chain crosses from the spec authority into `@dev`, and how the post-dev review cycle routes through `@qa`
+> - The stop conditions that always hand back to a human, and the reliability fixes that keep the chain from stalling
+
+Genuine human decisions (product scope, sizing/enrichment) still happen interactively inside their agents; autopilot only removes the mechanical "run the next thing" step once an agent's own work is settled. `feature:close`/publish is **always** a human gate — it is never auto-run.
+
+---
+
+## Two segments
+
+```
+Segment 1: @product → @sheldon (SMALL) / @orchestrator (MEDIUM) → @dev
+Segment 2: @dev → @qa (hub) → @tester / @pentester (only when their trigger fires) → @validator → STOP
+```
+
+1. **Spec → dev chain** — each spec agent, once its own decisions are resolved (no open `AskUserQuestion`, the gates it owns approved), seeds the agentic scheme and auto-invokes the next stage instead of stopping. It crosses the pre-dev boundary via the `dev-state.md` cold-start packet, not by carrying raw upstream chat forward.
+2. **Post-dev review cycle** — the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
+
+Historically segment 1 always stopped at the human (upstream agents ended on human decisions); autopilot now crosses it too, but only mechanically — a real product/sizing decision still pauses for the human before any auto-invoke.
+
+---
+
+## Activation
+
+Autopilot is active when the first two hold, gated by the third:
+
+1. **Armed signal** — `auto_handoff: true` in `project.context.md` (the project default), OR `.aioson/context/workflow-execute.json` exists with `agentic_policy.enabled: true` **and `feature` matching the current slug** (the seeded scheme — a scheme left by a different/closed feature does NOT count, for any agent in the chain). **Per-feature disarm wins over the flag:** a scheme for the current slug with `agentic_policy.enabled: false` (written by `aioson workflow:execute . --feature={slug} --seed --step`) turns autopilot OFF for that feature even when `auto_handoff: true` is set project-wide.
+2. A feature workflow is active (feature slug known).
+3. The current agent's own gate/verdict passed AND no genuine human decision is open (see stop conditions).
+
+### Inline run-mode tokens (highest precedence)
+
+A standalone `--auto` or `--step` in the activation arguments of `@product` (kickoff) or `@dev` (late entry/override) **is** the run-mode decision — the agent strips it from the task text and never asks:
+
+| Token | Where | Effect |
+|---|---|---|
+| `/product --auto <task>` | Feature kickoff | Skips the on-screen question; seeds the scheme and arms the whole chain from that point |
+| `/product --step <task>` | Feature kickoff | Skips the question; writes the disarmed scheme (`agentic_policy.enabled: false`) — manual handoffs |
+| `/dev --auto` | Entering `@dev` | Arms autopilot from here even with no prior flag/scheme — implementation + the post-dev review cycle run autonomously |
+| `/dev --step` | Entering `@dev` | Disarms autopilot for **this feature only** — stops at the `@dev → @qa` handoff even in an always-autopilot project (a per-feature disarm always wins over the project-wide flag) |
+
+Downstream agents (`@qa`/`@tester`/`@pentester`/`@validator`) do not parse tokens — they only read the flag/scheme that is already decided. Only `@product` asks; the rest never re-prompt.
+
+### No token: the question happens once, at `@product`'s handoff
+
+Absent an inline token and a standing choice, `@product` asks on screen at the PRD handoff (`AskUserQuestion`, localized, with a recommendation marker):
+
+- **Autopilot — run everything to `feature:close`** → runs the autopilot actions for this feature only (does not persist a default).
+- **Step by step — I'll drive each stage** → presents the manual handoff block and stops.
+- **Always autopilot in this project** → writes `auto_handoff: true` to `project.context.md` (adds the line if absent) and runs the autopilot actions.
+
+Full precedence, strongest to weakest:
+
+```
+1. Inline token (--auto / --step)
+2. Per-feature scheme (.aioson/context/workflow-execute.json with feature={slug}) — armed or disarmed
+3. Project-wide flag (auto_handoff: true/false in project.context.md)
+4. @product's on-screen question (only when none of the above is set)
+```
+
+---
+
+## Seeding the agentic scheme
+
+The first spec agent to finish under autopilot seeds the run's contract — the "scheme" the whole chain follows, and what makes a feature built the normal way (`@product → @sheldon`/`@orchestrator` → …) run to `feature:close` without the user launching anything:
+
+```bash
+aioson workflow:execute . --feature={slug} --seed --tool=<tool>
+```
+
+`--seed` writes `.aioson/context/workflow-execute.json` (with `agentic_policy.enabled: true` — review-loop caps, `feature_close: human_gate`, and the stop conditions) plus `.aioson/context/workflow.state.json`. It is **seed-only**: it records the policy the interactive agents follow but does NOT drive stage transitions itself — the agents do, via `Skill(aioson:agent:<next>)` + `aioson workflow:next . --complete=<agent>`. Re-seeding the same slug is idempotent.
+
+**Seed failure is a stop condition.** The seeding agent checks the command result: a `different_active_feature` failure means another feature is genuinely active in `workflow.state.json` — surface it to the user (close/pause it, or `aioson feature:sweep .`) and stop with the manual handoff. The chain is never treated as armed when the seed failed.
+
+---
+
+## Routing — deterministic, never LLM-chosen
+
+The next agent comes from the workflow state machine and on-disk evidence, not from model judgment:
+
+- CLI available: run `aioson workflow:next .` (inspect mode) and use the stage it reports, or the `next` field of `.aioson/context/workflow.state.json`.
+- CLI absent: follow the classification sequence in `.aioson/config.md` and the routing tables below, exactly.
+
+Never skip a stage, reorder, or pick an agent the state machine/routing table did not name.
+
+---
+
+## Segment 1 — spec → dev chain
+
+**SMALL (lean lane, default):** `@product` → `@sheldon` → `@dev`. Under autopilot: `@product`, once the PRD is settled, seeds the scheme and invokes `@sheldon`; `@sheldon`, once sizing/enrichment is confirmed and its lean-lane artifacts + `dev-state.md` are written, completes its own stage (`aioson workflow:next . --complete=sheldon`) and invokes `@dev`. The opt-in full-merged SMALL detour auto-chains `@analyst` → `@architect` → `@dev` when opted in (with `@scope-check`/`@discovery-design-doc` only if the sequence adds them).
+
+**MEDIUM (maestro lane, default):** `@product` → `@orchestrator` → `@dev`. Under autopilot: `@product` seeds and invokes `@orchestrator`; `@orchestrator`, once its gated spec package (Gates A/B/C approved, readiness ready) + `dev-state.md` are written, invokes `@dev`. The maestro fans out to `@analyst`/`@architect`/`@pm` as sub-agents, not as workflow stages — those chain as stages only under an opt-in full-chain detour.
+
+Crossing into `@dev` goes through the `dev-state.md` cold-start packet the spec agent writes — `@dev`'s session-start protocol loads only that minimal package, so it does not inherit the heavy upstream chat; transparent auto-compact trims the rest. That is why the crossing is safe without a manual `/compact`. The spec agent still stops with the normal manual `/dev` recommendation if it has an open product/scope/sizing decision, or a gate it owns is not approved. Recommend `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+
+---
+
+## Segment 2 — post-dev review cycle (hub = `@qa`)
+
+Once a human starts `@dev` and it finishes, the chain resumes automatically. `@qa` is the hub; every specialized agent returns to it.
+
+| Current | Condition | Auto-invoke |
+|---|---|---|
+| `@dev` (first pass) | tests green, gates clear, no open corrections cycle | `@qa` |
+| `@dev` (corrections) | corrections applied, tests green | `@qa` (re-verify) |
+| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 3, security gate) |
+| `@qa` | verdict **PASS** + `@tester` trigger fires and not yet run clean | `@tester` |
+| `@qa` | verdict **PASS** + `@pentester` trigger fires and not yet run clean | `@pentester` |
+| `@qa` | verdict **PASS** + harness contract present and `@validator` not yet PASS | `@validator` |
+| `@qa` | verdict **PASS** + no pending trigger/contract | **STOP** — recommend `aioson feature:close . --feature={slug}` |
+| `@tester` | surfaced dev-owned blocking gaps | `@dev` |
+| `@tester` | no dev-owned blocking gaps | `@qa` (re-evaluate/sign-off) |
+| `@pentester` | open `recommended_owner = dev` findings | `@dev` |
+| `@pentester` | no open dev-owned findings | `@qa` (re-evaluate/sign-off) |
+| `@validator` | PASS | **STOP** — recommend `aioson feature:close` |
+| `@validator` | FAIL | `@dev` |
+
+**Trigger source for `@tester`/`@pentester`:** the existing `@qa` trigger logic (coverage gaps → `@tester`; sensitive surface auth/secrets/data/upload/external-URL/supply-chain → `@pentester`). All four agents are ALWAYS wired into the chain, but `@tester`/`@pentester` only EXECUTE when their trigger fires — otherwise `@qa` skips straight to the next routing row.
+
+**Re-entry guard (no infinite loops):** before auto-invoking a specialized agent, `@qa` checks on-disk evidence that it already ran clean this cycle (`security-findings-{slug}.json` clean → `@pentester` done; a tester coverage artifact present with no new gap → `@tester` done; validator PASS recorded → `@validator` done). An agent that already returned clean is not re-invoked.
+
+**`@validator` runs fresh-context:** when routing to `@validator` with a harness contract present, it never runs inline in the current session — the implementation history biases the verdict. Sequence: `aioson harness:check` (deterministic checks) → `aioson harness:validate` (generates the self-contained `validator-prompt.txt`: criteria + check results + diff vs. base) → execution in an **isolated subagent** (Task tool, no conversation context) that writes its verdict to `last-validator-output.json` → `aioson harness:validate` again, to consume the verdict through the circuit breaker. Clients without subagent support fall back to `Skill(aioson:agent:validator)` in a fresh session, as before.
+
+---
+
+## Stop conditions — break the chain and emit the normal manual handoff
+
+1. **`feature:close`/publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
+2. **Genuine human decision open** — a spec agent with an unresolved product/scope/sizing question (an open `AskUserQuestion`, or a gate it owns not yet approved) resolves that decision with the human before any auto-invoke, and stops with the normal manual handoff. Autopilot removes mechanical stops, never real decisions.
+3. **Corrections cap reached** — review cycles are bounded by `agentic_policy.review_cycle` (default **3**); when `review-cycle:advance` returns `stop_cycle_limit`, stop and escalate to the human.
+4. **Critical security finding** — the `@qa` corrections security gate (auth/secret/credential/session/password/token/PII/encryption keywords) blocks the auto-loop; stop and require human intervention.
+5. **Verdict not clean / gate or readiness blocked** — the `@orchestrator` maestro spec package not gate-approved (Gates A/B/C) or its readiness `blocked`, `@validator` FAIL with no safe corrections path (and, when present as detours, `@architect` Gate B/merged-mode readiness `blocked`, `@pm` Gate C blocked, `@scope-check` not `approved`/`patched`, or `@discovery-design-doc` readiness `blocked`): stop and route to the owner manually.
+6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/compact` for same-feature continuation. The workflow resumes from `.aioson/context/workflow.state.json` — the next session re-enters autopilot automatically. Recommend `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+7. **Ambiguity** — workflow state unavailable and routing ambiguous, or any real decision requires user input: stop and ask, manually.
+
+The user can interrupt at any time (Ctrl+C); autopilot never retries an interrupted invocation.
+
+---
+
+## `--help` on the 13 most-used agents
+
+A standalone `--help` in the activation arguments (`/<agent> --help`) makes the agent print a localized quick-help block — what it does / when to use / options / typical calls / artifacts produced / next agents — and stop, doing no work. This applies to the 13 most-used agents, sourced from a single file, `.aioson/docs/agent-help.md`:
+
+```
+@product · @briefing · @briefing-refiner · @dev · @deyvin · @discover ·
+@neo · @orache · @orchestrator · @tester · @pentester · @qa · @sheldon
+```
+
+Each agent prints only its own section, never the whole file. Individual agent cards (PT: [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md)) link here when relevant.
+
+---
+
+## Reliability
+
+Three reliability fixes that directly affect anyone running autopilot:
+
+- **A stale workflow state no longer blocks the next feature's autopilot.** A `workflow.state.json` left by a closed/abandoned feature is discarded and reseeded automatically — only a genuinely active *different* feature (still `in_progress` in `features.md`) triggers the `different_active_feature` refusal. When that happens, close/pause the active feature or run:
+
+  ```bash
+  aioson feature:sweep .
+  ```
+
+- **`aioson update` now prints exactly which template landed**, including the exact build for an `npm link`ed (dogfooding) install:
+
+  ```
+  Template version applied: 1.36.0 (a1b2c3d, 2026-07-01)
+  ```
+
+  (the `(sha, date)` suffix only appears for a git-checkout install; a normal npm install prints just the semantic version.)
+
+- **The lean lane's state machine no longer regresses to `@sheldon` after implementation.** Previously, nothing resolved the `sheldon` stage, so `aioson workflow:next --complete=dev` re-activated `@sheldon` (a backwards activation). The `sheldon` stage is now recognized as completed along with the rest of the chain — completing a later stage can never leave `next` pointing at an earlier, already-resolved stage.
+
+---
+
+## How agents chain
+
+When autopilot is active and no stop condition applies:
+
+1. The agent finishes its own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `agent:epilogue`/`agent:done`).
+2. If the runtime checkpoint contains `agentic_policy.enabled=true`, it lets the gateway continue from `.aioson/context/workflow-execute.json` — it does not ask the user to confirm the next deterministic stage.
+3. If no runtime gateway is available, it emits a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
+4. It invokes `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
+
+---
+
+## CLI tracking
+
+```bash
+# See the current workflow state (which agent is active)
+aioson workflow:status .
+
+# Seed the agentic scheme without advancing (spec agents do this when they finish)
+aioson workflow:execute . --feature=checkout --seed --tool=claude
+
+# Seed already disarmed (equivalent to the --step token)
+aioson workflow:execute . --feature=checkout --seed --step --tool=claude
+
+# Advance manually (when autopilot is off)
+aioson workflow:next .
+
+# Discard a stale workflow.state.json left by a closed/abandoned feature
+aioson feature:sweep .
+
+# See the handoff prepared by the previous agent
+cat .aioson/context/last-handoff.json
+```
+
+---
+
+## Example: SMALL feature, autopilot armed end-to-end
+
+```
+You > /product --auto build email notifications
+
+@product > PRD closed. Autopilot mode (inline token) — no question asked.
+           Seeding the scheme... invoking @sheldon.
+
+@sheldon > Gates A/B/C approved. dev-state.md written.
+           Autopilot: @sheldon done → invoking @dev.
+
+@dev     > Phase loop: 3 phases implemented back to back, no stopping.
+           Tests green. Autopilot: @dev done → invoking @qa.
+
+@qa      > PASS. Neither @tester nor @pentester trigger fired. No pending harness contract.
+           STOP — "Recommend: aioson feature:close . --feature=email-notifications"
+
+You > aioson feature:close . --feature=email-notifications
+```
+
+## Example: MEDIUM feature, run mode chosen on screen at `@product`'s handoff
+
+```
+You > /product
+
+@product > [drives the PRD...] PRD closed. Classification: MEDIUM.
+           How do you want to run this feature?
+           1. Autopilot — run everything to feature:close (recommended)
+           2. Step by step — I'll drive each stage
+           3. Always autopilot in this project
+
+You > 3
+
+@product > Wrote auto_handoff: true to project.context.md.
+           Seeding the scheme... invoking @orchestrator.
+
+@orchestrator > Fan-out @analyst + @architect + @pm (+ @ux-ui). Gates A/B/C approved.
+                Autopilot: @orchestrator done → invoking @dev.
+
+@dev          > Implemented. Autopilot: @dev done → invoking @pentester (inline in MEDIUM).
+
+@pentester    > No HIGH/CRITICAL findings. Autopilot: @pentester done → invoking @qa.
+
+@qa           > PASS. Harness contract present, @validator not yet PASS → invoking @validator.
+
+@validator    > Fresh, isolated context. harness:check + LLM judgment of criteria with no verification.
+                PASS. STOP — "Recommend: aioson feature:close . --feature=..."
+```
+
+---
+
+## Lane B — compiled execution (opt-in alternative)
+
+For **MEDIUM** features, there is an execution lane alternative to real-time autopilot: **Lane B**, triggered by the `@forge-run` agent (`/forge-run`). Instead of chaining live agents, `@forge-run` **compiles** the feature's artifacts into a `.aioson/plans/{slug}/forge-run.workflow.js` (via `aioson forge:compile`) and runs it through the workflow runtime.
+
+The compiled workflow embeds the same review cycle: a `parallel()` per Wave → convergence at `harness:check` → 3-lens adversarial review for binary criteria without `verification` → the fresh-context validator closing via `harness:validate` → `apply-validation`. Like the normal lane, it **never** runs `feature:close`/publish: PASS recommends the human run `feature:close`; FAIL routes back to `@dev` through the normal lane. One feature per run.
+
+When to prefer each:
+- **Autopilot (normal lane)** — deterministic handoffs between live agents; default for SMALL and MEDIUM.
+- **Lane B (`@forge-run`)** — compiled, reproducible, versionable execution of one MEDIUM feature; opt-in, with a cost warning before running.
+
+See [Executable verification](./executable-verification.md#phase-5-v1280--lane-b-forgecompile--forge-run) for the Lane B mechanics.
+
+---
+
+## Next steps
+
+- [Executable verification](./executable-verification.md) — the five-phase theme Lane B belongs to
+- [CLI reference — workflow:next](./cli-reference.md#workflownext) and the classification-based sequences
+- PT: [SDD Framework](../../pt/5-referencia/sdd-framework.md) — full MICRO/SMALL/MEDIUM sequence and the lean/maestro lanes
+- PT: [`@product` card](../../pt/4-agentes/product.md) — where the run mode is decided
+- PT: [`@dev` card](../../pt/4-agentes/dev.md) — `--auto`/`--step` at implementation entry

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
@@ -346,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

package/docs/pt/1-entender/glossario.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.
 
 ---
 

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

@@ -88,7 +88,7 @@ A ordem padrão depende da classificação (v1.35.0):
 | **`@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` |

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

@@ -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).
 
 ---
 

package/docs/pt/3-receitas/da-ideia-ao-prd-via-briefing.md

@@ -23,6 +23,8 @@ ideia vaga / anotações
        ↓
    @briefing   →  .aioson/briefings/{slug}/briefings.md
        ↓
+ (opcional) @briefing-refiner  →  loop de refino: auditoria + review.html + apply-feedback
+       ↓
 aioson briefing:approve
        ↓
    @product   →  prd.md (ou prd-{slug}.md)
@@ -87,7 +89,11 @@ Você > Todos.
 
 ### Passo 3 — Revise e aprove
 
-Leia `.aioson/briefings/notificacoes-push/briefings.md`. Se estiver bom:
+Leia `.aioson/briefings/notificacoes-push/briefings.md`.
+
+> **Quer uma revisão estruturada antes de aprovar?** Ative o [`@briefing-refiner`](../4-agentes/briefing-refiner.md): ele audita o briefing em achados estruturados (categoria, severidade, bloqueio), o CLI renderiza a superfície `review.html` (`aioson briefing:review . --slug=notificacoes-push`) para você decidir cada achado e editar cada seção **num navegador de verdade**, e o feedback confirmado é aplicado com `aioson briefing:apply-feedback . --slug=notificacoes-push --confirm` — em rodadas, até nada bloquear o PRD.
+
+Se estiver bom:
 
 ```bash
 aioson briefing:approve
@@ -231,4 +237,5 @@ plans/                              ← seus rascunhos (intocados)
 - [Plans externos para @product](./plans-externos-para-product.md) — como usar ChatGPT/Claude.ai como fonte para `plans/`
 - [Feature completa com @sheldon](./feature-completa-com-sheldon.md) — quando o PRD está pronto e a trilha é SMALL/MEDIUM
 - [@briefing — ficha](../4-agentes/briefing.md) — referência técnica do agente
+- [@briefing-refiner — ficha](../4-agentes/briefing-refiner.md) — loop de revisão/refino do briefing antes do PRD
 - [@product — ficha](../4-agentes/product.md) — referência técnica do agente

package/docs/pt/3-receitas/feature-completa-com-sheldon.md

@@ -24,6 +24,8 @@
 
 `@orchestrator` é o maestro de spec: faz fan-out para `@analyst` + `@architect` + `@pm` (+ `@ux-ui` quando UI-heavy) como sub-agentes, consolida os artefatos, e entrega o pacote de spec aprovado para `@dev`. `@pentester` é inline (entre `@dev` e `@qa`).
 
+> **Passo a passo ou autopilot?** Esta receita mostra o fluxo **manual** — você invoca cada agente. Mas construir a feature do jeito normal (`@product` → `@sheldon`/`@orchestrator` → `@dev` → `@qa`) também pode rodar **sozinho** até a recomendação de `feature:close`: `@product` pergunta o modo de execução uma vez no handoff do PRD (ou você já decide na hora com `/product --auto`/`/product --step`), e cada agente invoca o próximo automaticamente. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md) para a cadeia completa, os tokens inline e as condições de parada. Os passos abaixo continuam valendo — é o que cada agente faz por trás, autopilot ligado ou não.
+
 ---
 
 ## SMALL lean — passo a passo
@@ -267,7 +269,7 @@ Você > @pentester
 | **MEDIUM, você quer gerenciar a spec manualmente** | `@product → @analyst → @architect → @ux-ui → @pm → @orchestrator (lanes only) → @dev → @pentester → @qa` — o "escape hatch" full-merged. |
 | **Sessão caiu no meio do `@dev`** | `@deyvin` retoma. Ver [Continuidade entre sessões](./continuidade-entre-sessoes.md). |
 | **`@sheldon` reclama que PRD está vago** | Volte ao `@product` e refine. `@sheldon` não inventa o que não está claro. |
-| **Ciclo `@qa ↔ @dev` estourou cap 2** | Há defeito de design. Volte ao `@sheldon` (SMALL) ou `@orchestrator` (MEDIUM) antes de mais código. |
+| **Ciclo `@qa ↔ @dev` estourou cap 3** | Há defeito de design. Volte ao `@sheldon` (SMALL) ou `@orchestrator` (MEDIUM) antes de mais código. |
 | **`@pentester` HIGH não baixa** | Não force. Documente como risco aceito ou adie a feature. |
 
 ---

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

@@ -1,9 +1,11 @@
 # Guia de Agentes AIOSON
 
-> Índice com 30 agentes e 1 alias, com situação de uso e saída esperada.
+> Índice com 31 agentes e 1 alias, com situação de uso e saída esperada.
 > Cada agente tem sua ficha — clique no nome para detalhes.
 > `@pair` é alias de `@deyvin` e não possui ficha separada.
 
+> **As colunas "Quando invocar" abaixo descrevem a capacidade de cada agente, não a ordem obrigatória do fluxo padrão.** Desde a lane lean/maestro (v1.35.0), o fluxo padrão é `@product → @sheldon → @dev → @qa` (SMALL) ou `@product → @orchestrator → @dev → @pentester → @qa` (MEDIUM) — `@analyst`, `@architect`, `@ux-ui` e `@pm` são detours opt-in ou sub-agentes do fan-out do `@orchestrator`, não hops obrigatórios. Construir a feature assim também pode rodar sozinho até a recomendação de `feature:close` — veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
 ---
 
 ## Núcleo de desenvolvimento (neste diretório)
@@ -11,14 +13,15 @@
 | 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) |
-| [@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/` |
-| [@dev](./dev.md) | Implementa a feature | Após planning completo | código + `dev-state.md` |
-| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
+| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Detour opt-in / sub-agente do `@orchestrator` (MEDIUM) | `architecture.md` (domínio) |
+| [@scope-check](./scope-check.md) | Confronta intenção, plano e artefatos antes do código | `spec:analyze` roda automático no gate `@dev`/`@qa`; detour explícito também disponível | `scope-check.md` |
+| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Detour opt-in / sub-agente do `@orchestrator` (MEDIUM) | `architecture.md` (técnico) |
+| [@ux-ui](./ux-ui.md) | Design system e specs de componentes | Detour opt-in para specs UI-heavy | `design-doc.md`, `discovery.md` |
+| [@pm](./pm.md) | Backlog, user stories, ACs detalhados | Sub-agente do `@orchestrator` (MEDIUM) ou detour opt-in | `tasks.md` |
+| [@sheldon](./sheldon.md) | **Autoridade única de spec (SMALL)** — requirements + decisões técnicas + plano faseado + harness-contract numa passada | Após `@product`, padrão do SMALL | `requirements-*.md`, `implementation-plan-*.md`, `harness-contract.json` |
+| [@orchestrator](./orchestrator.md) | **Maestro de spec (MEDIUM)** — fan-out para `@analyst`/`@architect`/`@pm` (+`@ux-ui`), consolida o pacote de spec com Gates A/B/C; secundário: coordena lanes paralelas pós-spec | Após `@product`, padrão do MEDIUM | `.aioson/context/parallel/`, pacote de spec consolidado |
+| [@dev](./dev.md) | Implementa a feature | Após o pacote de spec (`@sheldon`/`@orchestrator`) ou direto após `@product` (MICRO) | código + `dev-state.md` |
+| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` (cap 3), hub do autopilot pós-dev | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
 | [@validator](./validator.md) | Gate final: valida contrato binário de sucesso | Após `@qa`, antes de fechar feature | veredicto em `last-handoff.json` |
 | [@forge-run](./forge-run.md) | Lane B opt-in: compila e roda o workflow de verificação executável de uma feature MEDIUM | MEDIUM com contrato `verification` + plano com Wave | `forge-run.workflow.js` |
 | [@tester](./tester.md) | Engenharia de testes para apps já existentes | Legacy/brownfield ou lacunas graves | `test-inventory.md` |
@@ -33,10 +36,9 @@
 | [@setup](./setup.md) | Onboarding: detecta stack, classifica projeto | Sempre primeiro num projeto novo | `project.context.md` |
 | [@neo](./neo.md) | Roteador: diz qual agente é o próximo | Quando você está perdido | Orientação verbal |
 | [@briefing](./briefing.md) | Transforma anotações soltas em briefing pré-PRD | Antes de `@product`, quando ideia ainda vaga | `briefing.md` |
-| [@briefing-refiner](./briefing-refiner.md) | Revisa e refina um briefing existente via superfície HTML local | Após `@briefing`, antes de `@product` | `review.html`, `refinement-report.md` |
+| [@briefing-refiner](./briefing-refiner.md) | Loop de refino de briefing: audita em achados estruturados, o CLI renderiza a revisão (`briefing:review`) e aplica o feedback confirmado (`briefing:apply-feedback`) | Após `@briefing`, antes de `@product` | `refinement-findings.json`, `review.html` (CLI), `refinement-feedback.json`, `refinement-report.md` |
 | [@deyvin](./deyvin.md) | Pair-programming e continuidade de sessão | Retomar feature interrompida | continuação do trabalho |
 | [@pair](./deyvin.md) | Alias de `@deyvin` | — | — |
-| [@sheldon](./sheldon.md) | Análise técnica profunda, revisão de arquitetura | Decisões grandes, código legado | relatório de revisão |
 | [@committer](./committer.md) | Gera mensagem de commit profissional | Após implementar, antes de commitar | mensagem de commit |
 | [@discover](./discover.md) | Constrói cache semântico do projeto | Onboarding em codebase grande | `.aioson/context/bootstrap/` |