@jaimevalasek/aioson 1.36.0 → 1.37.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [1.37.1] - 2026-07-11
+
+### Added
+- Intelligent, bounded resolution of human-readable and approximate Codex model names.
+- Separate reasoning-effort propagation and model-resolution metadata across execution, reports, telemetry, and verification.
+
+### Changed
+- **Operator-memory promotion threshold is now per signal type.** `authorization`, `exclusion`, and `correction` are single explicit standing decisions and promote to a decision on **first** detection; `confirmation` still needs **2×** (it must repeat to distinguish a pattern from a one-off acceptance). Previously all four required 2× (`op-capture.js`), so a firmly-stated one-shot correction/authorization never persisted unless the agent emitted `op:capture` twice. Aligns the storage engine with the signal taxonomy already documented in `agents/_shared/memory-capture-directive.md`. New `promotionThresholdFor(signalType)` helper.
+
+### Fixed
+- **Re-detecting an already-promoted decision no longer duplicates its FTS row or resets `promoted_at`.** `op:capture` now reinforces in place — bumps `reinforcement_count` + refreshes `last_reinforced` (PMD-11) via the new `decision.reinforceDecision` primitive — instead of re-running promotion when a decision for the slug already exists (the stray proposal from re-detection is dropped). This latent double-insert also affected the old uniform-2× flow on the 3rd+ detection of the same signal.
+
+## [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 |
 
 ---