@jaimevalasek/aioson 1.36.0 → 1.37.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.37.0] - 2026-07-06
+
+**Full-feature autopilot + CLI-owned briefing refinement.** Two independent arcs land together. A feature built the normal way (`@product` → `@sheldon`/`@orchestrator` → `@dev`) can now run unattended through `@qa`/`@tester`/`@pentester`/`@validator` to `feature:close` — stopping only at genuine human decisions; `@product` asks the run mode once at kickoff (no hidden flag), settable inline (`--auto`/`--step`) or disarmed per feature. Separately, `@briefing-refiner`'s review surface stops being hand-written every round: the CLI now owns the schema, the render, and the apply, closing an explicit iterate-until-clean loop.
+
+### Added
+- **Full-feature autopilot.** `workflow:execute --seed` seeds the agentic scheme without advancing (idempotent, feature-scoped); `@product`/`@sheldon`/`@orchestrator` seed it and cross the pre-`@dev` gate via the `dev-state.md` cold-start packet; `@dev`/`@qa` honor it through the post-dev review cycle. `@product` asks the run mode on screen at kickoff (Autopilot / Step by step / Always autopilot) — never silent-manual by default. (`e24bfa5`, `9afc993`)
+- **Inline run-mode tokens** `--auto`/`--step` — `/product --auto <task>` / `/product --step <task>` answer the kickoff question inline (highest precedence); `/dev --auto` / `/dev --step` arm or disarm autopilot mid-chain for the current feature. Disarm is record-only (`workflow:execute --seed --step`) and beats a project-wide `auto_handoff: true` for that feature. (`70e826b`)
+- **`--help` activation token** on the 13 most-used agents — localized quick help (what/when/options/artifacts/next agents), zero kernel-byte cost beyond a 3-line trigger to the shared `agent-help.md`. (`bafaa2a`)
+- **`aioson briefing:review`** — parses `briefings.md`, strictly validates the agent's audit findings (`refinement-findings.json`: category/severity/blocking/recommendation per section), and renders the localized `review.html` + canonical `refinement-feedback.json` (schema **v1.1**: `findings[]` + `round`) + `refinement-report.md`. Refuses to clobber user-exported pending feedback (`--force` to override); the round counter survives applies via the per-round archives. (`43661a7`)
+- **`aioson briefing:apply-feedback`** — dry-run validation + summary without `--confirm` (the agent presents it and asks), real apply with it: structured-JSON-only edits, mandatory sections preserved, `approved` → `draft` revert, consumed feedback/findings archived as `*.applied-round{N}.json`. A **pending blocking finding** forces `resolve_blockers` even when `blocking_items` is empty. `--declined` records skipped changes without touching the briefing. (`43661a7`)
+- **`review.html` v2** — audit findings rendered per section with their own decision (`pending`/`accepted`/`rejected`/`deferred`) and working category filters; **localStorage autosave + draft restore** (closing the tab loses nothing); File System Access saves with a persistent handle and **degrades to download on SecurityError** (the sandboxed-preview bug); a **copy-path** affordance next to the save target and a stable save-picker id so the OS dialog reopens in the briefing folder on later rounds; en/pt localized surface. (`43661a7` + polish)
+- **`verify:artifact --kind=review`** + `briefing-refiner` in `AGENT_ARTIFACT_KIND` — the done-gate auto-fires at `agent:done --slug=...` and rejects hand-rolled surfaces (missing marker / fallbacks / external resources / invalid feedback JSON); staleness after an apply is advisory. (`43661a7`)
+
+### Fixed
+- **`@dev` phase-loop no longer self-stops.** The loop told `@dev` to `/compact` between phases — on Claude Code that ends the turn, so a feature ran one phase and waited instead of driving to the end. `@dev` never self-issues `/compact` now; `verification:plan` emits a deterministic `continuation_directive` instead. (`3a0fd34`)
+- **Autopilot chain-integrity audit** — four bugs behind the same reported symptom ("dev finished → manual /qa handoff"): a lean-lane `@sheldon` stage could re-activate backwards after `@dev` completed; tracked sessions didn't consult the seeded scheme as an autopilot signal; `--seed` hard-failed on a stale abandoned-feature guard instead of reseeding; downstream triggers didn't check the seeded scheme's feature slug against the current one. (`a0010cd`)
+- **Boolean-only argv flags** — `--seed` / `--seed-only` / `--confirm` / `--declined` / `--allow-stale` / `--step` could each swallow the path positional (e.g. `--declined .` silently defaulted to cwd). (`8a9999a`, `abc1058`, `70e826b`)
+- **`feature:close` retires per-feature runtime pointers** (`dev-state.md`, `workflow.state.json`, `workflow-execute.json`) when they reference the closed slug, so a future `@dev` cold-start can't "resume" a done feature and the next feature's `--seed` doesn't collide. (`bd34451`)
+- **Declined feedback no longer dead-ends the loop** — `briefing:apply-feedback --declined` archives the consumed feedback (`refinement-feedback.declined-round{N}.json`, findings kept since the briefing did not change) so the next `briefing:review` regenerates without `--force`, the declined round still counts toward the round counter, and declining stale feedback is allowed (decline writes nothing, so the source-hash guard does not apply). `kind=review` external-resource check hardened against false positives from briefing text quoting HTML/CSS. (`abc1058`)
+- **Windows executable resolver** never tests the extensionless candidate on `win32` — npm's extensionless shim is a shell script that `ENOENT`s on spawn despite existing (hit via `codex`/`opencode`); malformed `PATHEXT` empty segments are filtered, and a spawn failure between `spawn()` and the child-wait now fails cleanly instead of surfacing as an unhandled error (or a false exit code 0). (`25dcb60`)
+
+### Changed
+- **`@briefing-refiner`** rewritten around the CLI: explicit refinement-loop contract (generate → collect → dry-run + confirm apply → regenerate while blockers or material text changes remain → exit to `briefing:approve`/`@product` or prototype mode); handoff names the three feedback-return routes (direct save / download+replace / **paste JSON in the chat**) and instructs opening `review.html` in a real browser — editor previews are sandboxed; a non-blocking finding nudges the reference-image identity route for rich surfaces with no `identity.md`; the V1 "no dedicated refinement CLI" constraint is retired. Answers left in finding/section `note` fields are folded into `current_text` by the agent before the CLI writes — notes alone never reach the briefing. (`ad22cda`, `abc1058`)
+- **`identity.md` reaches every consumer of the `interface-design` engine** — the engine's SKILL now resolves it first (briefing scope → project brand → intent-first) so any consumer inherits the step; `@dev` reads it as a feature-mode UI input next to the prototype reference (a lean-lane feature without prototype/ux-ui no longer ships generic visuals over an existing brand); `@ux-ui`'s blank-`design_skill` stop offers the reference-image route alongside presets, mirroring `@setup`. (`35891f9`)
+- **Docs sweep** — `autopilot-handoff.md` rewritten to the current model (tokens, precedence, seeding, stop conditions) with an English counterpart; 14 PT/EN pages updated to the CLI-owned refinement loop and identity routes; agent-count headers and cycle-cap references corrected. (`95b99d5`, `90c77d1`, `16f9172`, `4c6507e`)
+
+Suite green (3587 pass / 0 fail / 1 skip).
+
 ## [1.36.0] - 2026-06-30
 
 **Reference-image-driven visual identity.** A project's UI no longer has to inherit a fixed design preset's identical look (the generic, "made-by-AI" sameness). The user provides reference images — a brand/identity set and an optional component/structure set — which are extracted **once** into a text `identity.md` that the `interface-design` engine applies. The build reads the text, never the images, so it ports to a vision-less harness, is user-editable, and is gateable. Purely **additive** — the fixed presets stay as raw material for `@design-hybrid-forge` / `@site-forge`; the new path is the recommended default alongside them.

package/docs/en/1-understand/ecosystem-map.md

@@ -93,7 +93,7 @@ The default lane depends on the classification:
 | **`@pm`** | Backlog, user stories, implementation plan (Gate C). **Opt-in detour / fan-out sub-agent** (MEDIUM) | `tasks.md`, user stories |
 | **`@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. | `parallel/`, execution plan, consolidated spec package |
 | **`@dev`** | Implements the feature — runs phases as a **loop**: auto-continues between phases, compacts context between phases, per-phase verification (light sub-agent). Full Runtime smoke runs once at end-of-feature. | Code + `dev-state.md` |
-| **`@qa`** | Writes tests, validates ACs, autonomous fix cycle (cap 2). Owns Gate D: **Runtime smoke gate** (build + migrations on real DB + boot + Core happy-path on REAL stack). | `test-plan.md`, `qa-report-*.md` |
+| **`@qa`** | Writes tests, validates ACs, autonomous fix cycle (cap 3), hub of the post-dev autopilot review cycle. Owns Gate D: **Runtime smoke gate** (build + migrations on real DB + boot + Core happy-path on REAL stack). | `test-plan.md`, `qa-report-*.md` |
 | **`@validator`** | Technically validates against `harness-contract.json` in a **fresh isolated context** (detour when a harness contract exists) | `.aioson/plans/{slug}/last-validator-output.json` |
 | **`@tester`** | Systematic test engineering (legacy/brownfield) — triggered by `@qa` when conditions fire | `test-inventory.md`, coverage tier |
 | **`@pentester`** | Adversarial security review (OWASP, LLM Top 10). Inline in MEDIUM; opt-in in SMALL. | `security-findings-*.json` |

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

@@ -129,7 +129,7 @@ Terms in alphabetical order. Each entry has a **short definition** + **concrete
 
 **Ready-made examples:** Clean SaaS UI, Aurora Command UI, Cognitive Core UI, Bold Editorial UI, Warm Craft UI, Glassmorphism UI, Neo Brutalist UI.
 
-**Where to choose:** during `aioson init`, in the wizard.
+**Where to choose:** during `aioson init`, in the wizard, or later with `@setup`/`@ux-ui`. The recommended route is the `interface-design` engine driven by your own **reference images**, extracted once into an `identity.md` the engine applies; the presets remain an explicit alternative.
 
 ---
 

package/docs/en/2-start/first-project.md

@@ -218,7 +218,7 @@ You > @qa
 @qa > test-plan.md and qa-report.md saved. Feature ready.
 ```
 
-> **What's new:** the *autonomous QA→Dev cycle* (cap 2) lets `@qa` request small fixes without you having to manually reactivate it. Added in May/2026.
+> **What's new:** the *autonomous QA→Dev cycle* (cap 3, `agentic_policy.review_cycle`) lets `@qa` request small fixes without you having to manually reactivate it. Under autopilot, this same cycle can chain all the way to `@tester`/`@pentester`/`@validator` and the `feature:close` recommendation without stopping — see [Autopilot handoff](../5-reference/autopilot-handoff.md).
 
 ---
 

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

@@ -134,7 +134,9 @@ npx @jaimevalasek/aioson squad:scaffold . --slug=compliance --name="Compliance"
 
 ## Choosing a Design System
 
-Available in the wizard:
+> **Recommended route: `interface-design` + your own reference images.** Instead of inheriting a fixed preset's identical look, you provide reference images (identity/brand and, optionally, component structure); the `reference-identity-extract` skill converts them **once** into a text `identity.md` that the `interface-design` engine applies to everything downstream (prototype and build). `@setup` offers this route first — always with explicit confirmation, never auto-selected. The presets below remain available as an alternative.
+
+Presets available in the wizard:
 
 | Skill | Style | Use cases |
 |---|---|---|
@@ -147,7 +149,7 @@ Available in the wizard:
 | **Neo Brutalist UI** | Black outlines, strong colors, no shadow | Bold brands |
 
 **Skipping** is a valid option. You can:
-- Choose later with `@ux-ui`
+- Choose later with `@ux-ui` — it offers the same two routes (reference images or preset)
 - Clone a real site's design with `@site-forge`
 - Create a hybrid with `@design-hybrid-forge` (e.g., clean-saas + neo-brutalist)
 

package/docs/en/3-recipes/from-idea-to-prd-via-briefing.md

@@ -23,6 +23,8 @@ vague idea / notes
        ↓
    @briefing   →  .aioson/briefings/{slug}/briefings.md
        ↓
+ (optional) @briefing-refiner  →  refinement loop: audit + review.html + apply-feedback
+       ↓
 aioson briefing:approve
        ↓
    @product   →  prd.md (or prd-{slug}.md)
@@ -90,7 +92,11 @@ You > All.
 
 ### Step 3 — Review and approve
 
-Read `.aioson/briefings/push-notifications/briefings.md`. If it looks good:
+Read `.aioson/briefings/push-notifications/briefings.md`.
+
+> **Want a structured review before approving?** Activate [`@briefing-refiner`](../4-agents/briefing-refiner.md): it audits the briefing into structured findings (category, severity, blocking), the CLI renders the `review.html` surface (`aioson briefing:review . --slug=push-notifications`) where you decide each finding and edit each section **in a real browser**, and confirmed feedback is applied with `aioson briefing:apply-feedback . --slug=push-notifications --confirm` — in rounds, until nothing blocks the PRD.
+
+If it looks good:
 
 ```bash
 aioson briefing:approve
@@ -235,4 +241,5 @@ plans/                              ← your drafts (untouched)
 - [External plans for @product](./external-plans-for-product.md) — how to use ChatGPT/Claude.ai output as source for `plans/`
 - [Full feature with @sheldon](./full-feature-with-sheldon.md) — when the PRD is ready and the trail is SMALL/MEDIUM
 - [@briefing — agent sheet](../4-agents/briefing.md) — technical reference for the agent
+- [@briefing-refiner — agent sheet](../4-agents/briefing-refiner.md) — briefing review/refinement loop before the PRD
 - [@product — agent sheet](../4-agents/product.md) — technical reference for the agent

package/docs/en/3-recipes/full-feature-with-sheldon.md

@@ -19,6 +19,8 @@
 
 **Why order matters:** each agent reads the artifacts left by the previous one. Skipping the spec authority means `@dev` improvises — improvisation on big decisions becomes rework.
 
+> **Step by step or autopilot?** This recipe walks the **manual** path — you invoke each agent yourself. But building the feature the normal way (`@product` → `@sheldon`/`@orchestrator` → `@dev` → `@qa`) can also run **on its own** up to the `feature:close` recommendation: `@product` asks the run mode once at the PRD handoff (or you decide up front with `/product --auto`/`/product --step`), and each agent auto-invokes the next. See [Autopilot handoff](../5-reference/autopilot-handoff.md) for the full chain, the inline tokens, and the stop conditions. The steps below still describe what each agent does under the hood, autopilot on or off.
+
 ---
 
 ## Scenario
@@ -305,7 +307,7 @@ Six months from now, anyone (or any AI) reads these files and understands **ever
 |---|---|
 | `@sheldon` complains the PRD is vague | Go back to `@product` and refine. `@sheldon` does not invent what is not clear. |
 | `@dev` phase loop stalls mid-phase | `@deyvin` picks up via `dev-state.md`. See [Continuity between sessions](./continuity-between-sessions.md). |
-| `@qa ↔ @dev` loop hit cap 2 | There is a design defect. Return to `@sheldon` or `@product` before writing more code. |
+| `@qa ↔ @dev` loop hit cap 3 | There is a design defect. Return to `@sheldon` or `@product` before writing more code. |
 | `@pentester` HIGH finding won't clear | Don't force it. Document as accepted risk or defer the feature. |
 | `@orchestrator` creates only 1 lane | Your feature is probably SMALL in disguise. Use the `@sheldon` trail instead. |
 | Session dropped mid-`@dev` | `@deyvin` picks up. See [Continuity between sessions](./continuity-between-sessions.md). |

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

@@ -1,6 +1,6 @@
 # Agent cards — AIOSON (EN)
 
-This layer will hold one card per AIOSON agent (29 total), translated from [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md).
+This layer will hold one card per AIOSON agent (31 total), translated from [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md).
 
 Cards are being translated progressively. Until a card is available here, the PT version is the canonical reference — it follows the same format and covers the same agents.
 
@@ -16,9 +16,11 @@ Cards are being translated progressively. Until a card is available here, the PT
 
 `@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.
 
+Building a feature the normal way through this lane can now run the whole chain automatically, up to the `feature:close` recommendation — `feature:close`/publish is always a human gate. See [Autopilot handoff](../5-reference/autopilot-handoff.md) for the run-mode decision (`--auto`/`--step` tokens, the `@product` kickoff question), the post-dev review cycle hub (`@qa` → `@tester`/`@pentester`/`@validator`), and the `--help` quick-help token available on the 13 most-used agents.
+
 ---
 
-## The 29 agents (plus @pair alias)
+## The 31 agents (plus @pair alias)
 
 ### Workflow core
 
@@ -26,6 +28,7 @@ Cards are being translated progressively. Until a card is available here, the PT
 |---|---|
 | `@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 |
+| [`@briefing-refiner`](./briefing-refiner.md) | Briefing refinement loop — audits the briefing into structured findings, the CLI renders the localized `review.html` surface (`briefing:review`), confirmed feedback is applied via `briefing:apply-feedback`, rounds repeat until nothing blocks the PRD |
 | `@product` | PRD — vision, problem, users, scope, acceptance criteria |
 | `@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) |
@@ -35,7 +38,7 @@ Cards are being translated progressively. Until a card is available here, the PT
 | `@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). |
+| `@qa` | Risk-first review, test generation, autonomous fix/test loop (cap 3), hub of the post-dev autopilot review cycle (routes to `@tester`/`@pentester`/`@validator`). 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. Triggered by `@qa` when conditions fire. |

package/docs/en/4-agents/briefing-refiner.md

@@ -0,0 +1,146 @@
+# @briefing-refiner — Review and refine a briefing before the PRD
+
+> **Who this is for:** anyone who already has a briefing generated by `@briefing` and wants to review, annotate, and refine it before committing to a PRD.
+> **Reading time:** 5 min.
+> **What you'll know after:**
+> - What `@briefing-refiner` does and where it fits in the flow.
+> - How the round-based refinement loop works (audit → browser review → apply).
+> - How the `review.html` surface actually saves (local autosave + 3 routes to return the JSON).
+
+## What it is for
+
+Between the generated briefing and the PRD there is a step that usually gets skipped: **reviewing the briefing with a critical eye**. Ambiguities, redundancies, missing decisions, vague risks, and implementation-impact gaps go straight to `@product` and become debt in the PRD.
+
+`@briefing-refiner` fills that step as a **loop of rounds**: it audits the briefing and records **structured findings** (category, severity, and whether they block the PRD); the CLI renders the deterministic review surface (`aioson briefing:review`); you decide each finding and edit each section in the browser; the structured feedback comes back and is applied (`aioson briefing:apply-feedback`) — and the cycle repeats until nothing blocks the PRD.
+
+It is the complement of [`@briefing`](../../pt/4-agentes/briefing.md): one generates, the other refines.
+
+## When to invoke
+
+- You already have a briefing in `.aioson/briefings/{slug}/briefings.md` and want to review it before the PRD.
+- The briefing is `draft`, or `approved` but still **without a generated PRD** (`prd_generated: null`).
+- You want to record comments, decide findings, request per-section changes, or flag blockers before moving on to `@product`.
+- You want to **see the solution** before the PRD (prototype mode) and, optionally, define the visual identity from your reference images.
+
+## When NOT to invoke
+
+- No briefing exists yet — go to [`@briefing`](../../pt/4-agentes/briefing.md) first.
+- The briefing already produced a PRD (`prd_generated` filled) — refining would require a new PRD/enrichment route, outside this agent.
+- The idea changed so much that regenerating from scratch is better — go back to `@briefing`.
+
+## The refinement loop
+
+```
+audit (agent) → review.html (CLI) → you decide in the browser
+      ↑                                        ↓
+regenerate the review  ←  apply confirmed feedback (CLI)
+(while blockers or text changes remain)
+```
+
+Each round is numbered (`round`) and archives the consumed feedback (`refinement-feedback.applied-round{N}.json`), so "`refinement-feedback.json` exists" = "there is pending feedback" — a deterministic signal.
+
+### 1. Generate the review
+
+The agent audits the briefing and writes the findings to `refinement-findings.json`; the CLI validates and renders:
+
+```
+You > @briefing-refiner
+
+@briefing-refiner > Refinable briefing found: marketplace-v1 (draft).
+
+                    Auditing... 10 findings (3 ambiguities, 2 gaps,
+                    1 blocking: commission model undefined).
+
+                    aioson briefing:review . --slug=marketplace-v1  ✓ (round 1)
+
+                    Open .aioson/briefings/marketplace-v1/review.html
+                    in a REAL BROWSER (double-click) — editor previews
+                    are sandboxed and block saving/downloading.
+```
+
+### 2. Apply pending feedback
+
+The CLI validates (schema, slug, source hash) and does a **dry-run** with the summary; the agent asks for explicit confirmation before touching the briefing:
+
+```
+@briefing-refiner > Pending feedback on marketplace-v1 (round 1):
+                    - 4 sections changed, 1 blocked
+                    - findings: 6 accepted, 2 rejected, 1 deferred, 1 pending (blocking)
+
+                    Apply the confirmed changes? The pending blocking
+                    finding keeps the PRD blocked.
+You > Yes.
+
+@briefing-refiner > aioson briefing:apply-feedback --confirm  ✓
+                    Applied; briefing reverted from approved to draft.
+                    Blocker remains → regenerating the review (round 2)...
+```
+
+If you decline, `briefings.md` stays intact and the skipped changes are recorded in the report. When no blocker remains: `aioson briefing:approve . --slug={slug}` → `@product`.
+
+## The review surface (review.html)
+
+Rendered by the CLI (`aioson briefing:review`) — static, local, self-contained, and in your language:
+
+- plain-text editable sections + per-section status (`unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`) and notes;
+- **audit findings rendered per section**, each with its own decision (`pending`/`accepted`/`rejected`/`deferred`) and note — with working category filters;
+- a panel showing what changed, what blocks the PRD, and how many findings are still pending;
+- **local autosave**: every edit is saved in the browser (localStorage) and restored on reopen — closing the tab loses nothing;
+- **3 routes to return the JSON**: *Save to file* (File System Access, with an automatic fallback to download when the context is sandboxed), *Download JSON* (and move it over `refinement-feedback.json`), or *Copy JSON and paste it in the chat* — the lowest-friction route.
+
+> **Why JSON and not the edited HTML?** The agent never treats the edited DOM/HTML as canonical feedback — only the structured `refinement-feedback.json` (schema v1.1, validated by source hash). That prevents applying inferred changes and keeps the process auditable.
+
+> **Important:** open `review.html` in a real browser (double-click). Embedded editor previews run in a sandbox and block the file picker and downloads.
+
+## Prototype mode and visual identity (optional)
+
+For rich-surface briefings (workspaces, boards, CRM/Kanban, dashboards, repeated-use CRUD), the agent recommends — without blocking — generating a clickable prototype before the PRD. This is the moment (or already during the review, via a non-blocking finding) where the **visual identity** comes in:
+
+- you drop reference images into `references/identity/` (brand: color, typography, mood) and `references/structure/` (a board, a table, a screen);
+- the `reference-identity-extract` skill reads the images **once** and writes `identity.md` (tokens + per-component structure notes);
+- the `interface-design` engine **applies** `identity.md` to everything downstream (prototype and build) — with no images, it runs intent-first.
+
+The prototype is mock-only and never becomes canonical feedback.
+
+## Outputs on disk
+
+| File | What it contains |
+|---|---|
+| `.aioson/briefings/{slug}/refinement-findings.json` | The agent's audit findings (CLI input) |
+| `.aioson/briefings/{slug}/review.html` | Review surface rendered by the CLI |
+| `.aioson/briefings/{slug}/refinement-feedback.json` | Structured v1.1 feedback (the only source that gets applied) |
+| `.aioson/briefings/{slug}/refinement-report.md` | Round report: applied, skipped, blocked, findings |
+| `.aioson/briefings/{slug}/refinement-*.applied-round{N}.json` | Per-round archive (consumed feedback and findings) |
+| `.aioson/briefings/{slug}/briefings.md` | Updated **only** after confirmation |
+| `.aioson/briefings/config.md` | Updated briefing index/registry |
+
+## How it reads your project
+
+1. `.aioson/config.md`
+2. `.aioson/context/project.context.md`
+3. `.aioson/briefings/config.md` — resolves the refinable slug (if absent, routes to `@briefing`).
+4. `.aioson/briefings/{slug}/briefings.md` — read before writing any review artifact.
+
+## Hard constraints
+
+- Never creates or edits `prd*.md`.
+- Never approves a briefing automatically.
+- Never routes to `@product` while blocking items remain (including a pending blocking finding).
+- Never treats edited HTML/DOM as canonical feedback — only the structured JSON.
+- Never hand-writes `review.html` or applies feedback manually while the CLI commands exist — the done-gate (`verify:artifact --kind=review`) rejects hand-rolled surfaces.
+- Never discards mandatory briefing sections.
+
+## `--help` option
+
+An activation with `--help` (`/briefing-refiner --help`) prints a quick summary — what it does, when to use it, typical call, what it produces, next agent — localized in your language, and stops without executing anything. Source: `.aioson/docs/agent-help.md`.
+
+## Typical handoff
+
+- **Comes from:** [`@briefing`](../../pt/4-agentes/briefing.md) (briefing generated) or you, resuming a review.
+- **Goes to:** after applying the changes with no blockers → `aioson briefing:approve . --slug={slug}` → [`@product`](../../pt/4-agentes/product.md); for rich surfaces, prototype mode first. If a blocker remains, the next round of the loop resolves it — never manual editing.
+
+## Next step
+
+- Generate the briefing before refining → [@briefing (PT card)](../../pt/4-agentes/briefing.md)
+- Full flow up to the PRD → [From idea to PRD via briefing](../3-recipes/from-idea-to-prd-via-briefing.md)
+- Terms like "gap" and "PRD" → [Glossary](../1-understand/glossary.md)

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

@@ -15,6 +15,7 @@ This layer currently holds the original EN feature guides. Additional reference
 | [cli-reference.md](./cli-reference.md) | Full reference for every CLI command |
 | [json-schemas.md](./json-schemas.md) | `--json` output contracts for all commands |
 | [executable-verification.md](./executable-verification.md) | The executable-verification theme: `verification` + `harness:check`, fresh-context validator, `spec:analyze`, Wave markers, Lane B (`forge:compile` + `@forge-run`) |
+| [autopilot-handoff.md](./autopilot-handoff.md) | Full-feature autopilot: `@product` → `@sheldon`/`@orchestrator` → `@dev` → `@qa` (hub) → `@tester`/`@pentester`/`@validator` up to the `feature:close` recommendation; inline `--auto`/`--step` tokens, `--help` on the 13 most-used agents |
 
 ---
 

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