@jaimevalasek/aioson 1.21.7 → 1.22.0

package/CHANGELOG.md

@@ -1,8 +1,45 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project will be documented in this file.
+
+## [1.22.0] - 2026-06-10
+
+### Added
+- **Loop guardrails for self-implementation harnesses.** `self:loop` now runs from an active contract with schema validation, active-contract discovery, scope enforcement, budget ceilings, attempt artifacts, criteria verification, failure-signature escalation, and human approval gates.
+- **Harness gate/status commands.** Added `harness:status` and human gate approval/rejection flows so paused loop work can be inspected, resumed, or explicitly blocked without losing context.
+- **Contract-aware git guard integration.** `git:guard` now merges declared `forbidden_files` from the active harness contract while preserving safe human commit behavior for lockfiles unless the contract explicitly forbids them.
+
+### Changed
+- **Dev/QA prompts now understand loop guardrails.** Workspace and template agent prompts were updated so implementation, QA, correction loops, and handoffs consume the new guarded harness model consistently.
+- **Loop-guardrails feature artifacts are now durable.** PRD, requirements, readiness, design, scope-check, Sheldon enrichment, dossier, corrections plan, and progress artifacts were recorded under `.aioson/context/` and `.aioson/plans/`.
+
+### Tests
+- Added regression coverage for contract schema validation, glob matching, scope guard behavior, budget enforcement, criteria execution, human gates, active-contract discovery, git guard contract merging, and self-loop guardrails.
+
+## [1.21.8] - 2026-06-08
+
+### Added
+- **`feature:export` — copy a feature's artefacts to a clean output directory.** Non-destructive sibling of `feature:archive`: instead of *moving* artefacts into `.aioson/context/done/{slug}/`, it *copies* the full surface (root `*-{slug}.{md,yaml,yml,json}` minus global files, the per-slug `dossier/`/`plans/`/`briefings/` directories, and `context/done/{slug}/` when archived) into an arbitrary `--out` (default `<target>/{slug}-export`), leaving the source tree untouched. Flags: `--flatten` (collapse to one level), `--no-index` (skip the generated `INDEX.md` manifest), `--dry-run`, `--json`. Reuses the archive's slug-collision guard via the new exported `collectFeatureArtifacts` helper, so a sibling slug (`checkout-v2`) never leaks into a `checkout` export. No `features.md` status guard — works on in-progress features too. Turns AIOSON's markdown output into a portable deliverable. Docs: `docs/pt/5-referencia/feature-export.md` + `docs/en/5-reference/cli-reference.md`.
 
-## [Unreleased]
+### Fixed
+- **`briefing:list` no longer re-surfaces PRD-generated briefings.** The "approved" filter ignored `prd_generated`, so a briefing already converted to a PRD could be picked up again and reverted to draft. It now filters `status === 'approved' && !prd_generated`.
+- **`briefing-refiner` `returnedToDraft` is computed before mutation.** The return flag was read from the entry *after* the status was rewritten, reporting the post-mutation state instead of whether the refinement actually returned an approved/non-PRD briefing to draft.
+- **`workflow:next` no longer false-flags substantiated stages as unsubstantiated.** `detectUnsubstantiatedCompletions` queried the wrong table/columns (`agent_events.agent` instead of `execution_events.agent_name`) and destructured `openRuntimeDb` incorrectly, so the completion-evidence check silently found nothing; it now reads `execution_events` and only reports `missing` stages when at least one stage *was* substantiated (no false positives on an empty event log). `discovery-design-doc` added to the inferable-stage set.
+- **`pulse:update` is CRLF-safe.** The "## Recent Activity" parser matched LF-only (`\n`), so on Windows (CRLF) line endings it failed to capture history and clobbered the existing activity list. Regex and line-split now accept `\r?\n`.
+- **`commit:prepare` reads unicode/spaced paths correctly.** `git status --short` ran without `core.quotePath=false`, so non-ASCII paths came back octal-escaped. Also removed a dead no-op ternary in the pattern builder.
+- **`parallel:doctor --dry-run` is recognized.** The handler read only `options.dryRun`, missing the kebab `--dry-run` form; it now accepts both.
+- **`scan:project` guards malformed LLM responses.** Direct `data.choices[0].message.content` / `data.content[0].text` dereferences could throw an opaque `TypeError` on an unexpected provider payload; both now validate the shape and throw a descriptive `Unexpected … response shape` error.
+- **`agent:manifest` validation now whitelists `check_modes`.** `sanitizeManifest` filters `check_modes` against `ALLOWED_CHECK_MODES` (`pre-dev`, `post-dev`, `post-fix`, `final`), mirroring the existing autonomy-mode guard.
+- **`runtime:emit` standalone-event line is localized.** The standalone path logged a hard-coded English string; it now uses the `live.standalone_event_recorded` i18n key (added in all locales).
+
+### Changed
+- **Agent structural-contract enforcement swept across all agent prompts.** Added the mandatory `## Required input` section to 18 agents that lacked it, a `## Observability` section with the `aioson agent:done … 2>/dev/null || true` call to 9 agents, the §5 best-effort suffix to `agent:done` calls that were missing it (pentester/discover/site-forge), per-slug `dossier:*` flags where required (discovery-design-doc/validator), and the `/clear` handoff cue to `product`. The previously-missing dossier templates (`agent-templates.md`, `schema.md` — referenced by 10 agents) are now shipped under `template/.aioson/docs/dossier/`, closing a packaging gap.
+- **Transient SQLite locks now wait instead of failing.** Added `busy_timeout = 5000` to the runtime store (`runtime-store.js`) and context-search index (`context-search.js`), so a WAL checkpoint or AV file-lock retries for up to 5s rather than throwing `SQLITE_BUSY` immediately — a production-robustness improvement that also stabilizes the suite under parallel load.
+
+### Tests
+- New `tests/agent-structural-contract.test.js` pins the §1–§6 structural contract (LANGUAGE BOUNDARY, mandatory sections, `Required input`, `agent:done`, §5 best-effort suffix, dossier flag integrity).
+- New `tests/feature-export.test.js` (8 cases: mirrored/flatten/no-index/done-inclusion/dry-run/noop/validation/default-out).
+- Windows file-lock hardening: recursive `fs.rm` cleanups in 14 SQLite-touching test files now pass `maxRetries: 5, retryDelay: 50`; over-tight latency ceilings in `telemetry-foundation` and `qa-feature-close-distillation` loosened to hang-guards (full suite: 2993 pass, 0 fail, 1 skip).
 
 ## [1.21.3] - 2026-05-28
 

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

@@ -2,7 +2,7 @@
 
 > **Who this is for:** anyone who wants to see the full team at once.
 > **Reading time:** 8 min
-> **What you'll know after:** who the 28 agents are, when each one enters, and how they communicate.
+> **What you'll know after:** who the 29 agents are, when each one enters, and how they communicate.
 
 ---
 

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

@@ -99,7 +99,7 @@ You can mark **more than one** in the wizard — they coexist in the same projec
 
 ### Development (default)
 
-Includes the 28 official agents (product, analyst, dev, qa, etc.). Sufficient for 95% of projects.
+Includes the 29 official agents (product, analyst, dev, qa, etc.; `@pair` is alias of `@deyvin`). Sufficient for 95% of projects.
 
 ### Development + Squads
 

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

@@ -1,12 +1,12 @@
 # Agent cards — AIOSON (EN)
 
-This layer will hold one card per AIOSON agent (28 total), translated from [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md).
+This layer will hold one card per AIOSON agent (29 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.
 
 ---
 
-## The 28 agents
+## The 29 agents (plus @pair alias)
 
 ### Workflow core (pipeline order)
 
@@ -14,10 +14,11 @@ 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 |
-| `@product` | PRD — vision, problem, users, scope, acceptance criteria |
-| `@sheldon` | PRD quality guardian — gap detection, web research, sizing, in-place enrichment or phased plan |
-| `@analyst` | Domain discovery — entities, flows, brownfield mapping |
-| `@architect` | Technical decisions — structure, libraries, integration boundaries |
+| `@product` | PRD — vision, problem, users, scope, acceptance criteria |
+| `@sheldon` | PRD quality guardian — gap detection, web research, sizing, in-place enrichment or phased plan |
+| `@analyst` | Domain discovery — entities, flows, brownfield mapping |
+| `@scope-check` | Alignment gate before implementation — validates intent vs plan and catches scope drift |
+| `@architect` | Technical decisions — structure, libraries, integration boundaries |
 | `@ux-ui` | Design system and UI component specs (MEDIUM) |
 | `@pm` | Backlog and user stories (MEDIUM) |
 | `@orchestrator` | Parallel lane coordination (MEDIUM) |
@@ -49,7 +50,7 @@ Cards are being translated progressively. Until a card is available here, the PT
 | `@design-hybrid-forge` | Combine two design skills into a hybrid |
 | `@orache` | Domain investigation and strategic research |
 | `@copywriter` | Conversion copy — landing pages, VSL scripts |
-| `@discovery-design-doc` | Combined discovery + design doc generation |
+| [`@discovery-design-doc`](./discovery-design-doc.md) | Discovery, readiness, and design doc package |
 
 ---
 

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

@@ -0,0 +1,150 @@
+# @discovery-design-doc - Discovery, readiness, and design doc
+
+> **For whom:** people who need to turn a vague idea into initial clarity, or consolidate PRD, requirements, and architecture into a technical contract before `@dev`.
+> **Reading time:** 3 min.
+> **What you will learn:**
+> - The two correct usage modes: exploratory and pre-dev
+> - Why this agent can appear after `@analyst` and `@architect` in the workflow
+> - What the design doc and readiness note provide to downstream agents
+
+---
+
+## What it is for
+
+`@discovery-design-doc` has two valid uses:
+
+- **Exploratory mode:** when a request is still vague, such as a ticket, feature idea, or meeting note. It normalizes the problem, identifies ambiguities, and recommends the next agent.
+- **Pre-dev workflow mode:** when a SMALL/MEDIUM project has already passed through `@analyst` and `@architect`. In this case, it consolidates PRD, requirements, spec, and architecture into a living `design-doc` and a `readiness` note with a concrete technical plan for `@dev`.
+
+So it can be either a shortcut before the full cycle **or** a safety stage between architecture and implementation. In the current workflow, the second use is expected for SMALL/MEDIUM.
+
+---
+
+## When to invoke
+
+- You have a ticket, briefing, or idea and want to turn it into a structured document quickly
+- You want to know what is defined vs ambiguous before invoking `@product` or `@dev`
+- You are in exploratory mode and want a clarity checkpoint without committing to the full workflow
+- You are in the SMALL/MEDIUM workflow after `@architect` and need the pre-dev technical contract
+- `@dev` needs exact paths, modules, reuse decisions, and file-size risks before editing code
+
+---
+
+## When not to invoke
+
+- To redo broad discovery when PRD, requirements, spec, and architecture are already clear
+- You need deep domain discovery and entity mapping - use `@analyst` inside the SMALL/MEDIUM workflow
+- You want pre-PRD framing with framing frameworks - use `@briefing`
+- The task is MICRO and already has a simple plan that is enough for `@dev`
+
+> Having PRD/spec defined does **not** block this agent. In the SMALL/MEDIUM workflow, those artifacts are inputs for the pre-dev `design-doc` and `readiness` package.
+
+---
+
+## Where it fits in the workflow
+
+Manual exploratory flow:
+
+```text
+@setup -> @discovery-design-doc -> recommended next agent
+```
+
+Current SMALL flow:
+
+```text
+@product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> @qa
+```
+
+Current MEDIUM flow:
+
+```text
+@product -> @analyst -> @architect -> @discovery-design-doc -> @ux-ui -> @pm -> @orchestrator -> @scope-check(pre-dev) -> @dev -> @qa
+```
+
+Its role in the middle of a feature is not to replace `@analyst` or `@architect`. It turns those artifacts into an executable implementation package.
+
+---
+
+## Typical dialogue - exploratory mode
+
+```text
+You > @discovery-design-doc
+      I want to add offline mode to the mobile app so users can read
+      content without internet access.
+
+@discovery-design-doc > Normalizing request...
+                        Problem: users lose content access without connection
+                        Scope: offline reading mode, not offline creation
+
+                        Ambiguities:
+                        - How much content can be stored offline?
+                        - Automatic or manual sync?
+                        - What happens when offline and online versions diverge?
+
+                        Already defined:
+                        - Stack: React Native + local SQLite available
+                        - Auth: token can survive offline usage
+
+@discovery-design-doc > Design doc created at: .aioson/context/design-doc.md
+                        Readiness: MEDIUM - 3 ambiguities need decisions.
+                        Recommendation: @product to close scope before @dev.
+```
+
+---
+
+## Typical dialogue - pre-dev mode
+
+```text
+You > @discovery-design-doc
+      Consolidate the checkout feature after architecture.
+
+@discovery-design-doc > Reading PRD, requirements, spec, and architecture...
+                        Scope: checkout with one-time payment
+                        Readiness: ready_with_warnings
+
+                        Technical plan:
+                        - Reuse the existing orders module
+                        - Create payment service under src/lib/payments/
+                        - Avoid changing cart flow outside checkout
+                        - Risk: controller may exceed 500 lines; split into service + validator
+
+@discovery-design-doc > Design doc created at: .aioson/context/design-doc-checkout.md
+                        Readiness created at: .aioson/context/readiness-checkout.md
+                        Recommendation: proceed to @dev when Gate B is approved.
+```
+
+---
+
+## Disk outputs
+
+```text
+.aioson/context/design-doc.md              <- project design doc
+.aioson/context/readiness.md               <- project readiness
+.aioson/context/design-doc-{slug}.md       <- feature design doc
+.aioson/context/readiness-{slug}.md        <- feature readiness
+```
+
+---
+
+## How it reads your project
+
+- `.aioson/context/project.context.md`
+- Existing artifacts: `prd.md`, `prd-{slug}.md`, `requirements-{slug}.md`, `spec.md`, `spec-{slug}.md`, `discovery.md`, `architecture.md` when relevant
+- Existing design docs: `design-doc.md`, `design-doc-{slug}.md`, `readiness.md`, `readiness-{slug}.md`
+- `.aioson/context/project-map.md` when present, to resolve canonical paths
+- Direct input: briefing, ticket, screenshots, files you provide
+
+---
+
+## Typical handoff
+
+- **Comes from:** direct request with a vague idea or ticket
+- **Also comes from:** `@architect` in the SMALL/MEDIUM workflow, as pre-dev consolidation
+- **Goes to:** the agent recommended in `readiness.md` - usually `@product` when scope is still open, or `@dev` when readiness is high
+
+---
+
+## Next step
+
+- For pre-PRD framing with discovery frameworks: use `@briefing`
+- For the full cycle: see [First project from scratch](../2-start/first-project.md)

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

@@ -17,7 +17,7 @@ aioson init my-app --no-interactive
 
 **Options:**
 - `--lang=en|pt-BR|es|fr` — sets `conversation_language` in the generated context and applies the matching agent locale pack. Default: `en`.
-- `--tool=codex|claude|opencode` — configures the primary AI client. Affects which gateway file is used. Default: `codex`.
+- `--tool=codex|claude|opencode` — configures the primary AI client. Affects which gateway file is used. Default: `codex`.
 - `--no-interactive` — skip the wizard and install all files (CI / automation).
 - `--json` — prints structured JSON result instead of human-readable output.
 
@@ -44,8 +44,8 @@ aioson install --no-interactive
 
 **Options:**
 - `--lang=en|pt-BR|es|fr` — sets locale pack.
-- `--tool=codex|claude|opencode` — configures AI client.
-- `--reconfigure` — re-run the wizard even if a profile already exists (e.g. to add another supported tool later).
+- `--tool=codex|claude|opencode` — configures AI client.
+- `--reconfigure` — re-run the wizard even if a profile already exists (e.g. to add another supported tool later).
 - `--no-interactive` — skip the wizard and install all files.
 - `--force` — overwrite existing files.
 - `--dry-run` — preview without writing.
@@ -248,25 +248,25 @@ The locale shown reflects the active agent locale pack (from `project.context.md
 Print the activation prompt for a specific agent, ready to paste into any AI CLI that does not support slash commands.
 
 ```bash
-aioson agent:prompt setup
-aioson agent:prompt setup --tool=codex
-aioson agent:prompt ux-ui --tool=claude
-aioson agent:prompt dev --tool=opencode --json
+aioson agent:prompt setup
+aioson agent:prompt setup --tool=codex
+aioson agent:prompt ux-ui --tool=claude
+aioson agent:prompt dev --tool=opencode --json
 ```
 
 **Arguments:**
-- `<agent>` — agent id: `setup`, `product`, `analyst`, `scope-check`, `architect`, `ux-ui`, `pm`, `dev`, `qa`, `orchestrator`.
+- `<agent>` — agent id: `setup`, `product`, `analyst`, `scope-check`, `architect`, `ux-ui`, `pm`, `dev`, `qa`, `orchestrator`.
 
 **Options:**
-- `--tool=codex|claude|opencode` — formats the prompt for the target CLI. Default: `codex`.
+- `--tool=codex|claude|opencode` — formats the prompt for the target CLI. Default: `codex`.
 - `--json` — returns structured JSON with the prompt string.
 
 **When to use:** if you're using an AI CLI that doesn't support `/aioson:agent:setup` slash commands, run this to get the exact text to paste into the chat.
 
 ```bash
-# Copy the prompt for @analyst in OpenCode
-aioson agent:prompt analyst --tool=opencode
-# → paste the output into OpenCode
+# Copy the prompt for @analyst in OpenCode
+aioson agent:prompt analyst --tool=opencode
+# → paste the output into OpenCode
 ```
 
 ---
@@ -302,18 +302,18 @@ Notes:
 
 **Sequences by classification:**
 - `MICRO`: `@setup → @product (optional) → @dev`
-- `SMALL`: `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
-- `MEDIUM`: `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
+- `SMALL`: `@setup → @product → @analyst → @scope-check → @architect → @dev → @qa`
+- `MEDIUM`: `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa`
 
 **Feature development workflow (after initial setup):**
 
 Once the project is set up, each new feature follows a shorter sequence — no `@setup` required:
 
 ```
-/aioson:agent:product → @analyst → @scope-check → @dev → @qa
+/aioson:agent:product → @analyst → @scope-check → @dev → @qa
 ```
 
-`@product` creates a feature-scoped `prd-{slug}.md` and registers the feature in `features.md`. `@analyst` produces `requirements-{slug}.md` and `spec-{slug}.md`. `@scope-check` compares intent against the planned implementation before coding. `@dev` reads the feature spec. `@qa` closes the feature by running `feature:close --verdict=PASS`, which updates `spec-{slug}.md` with a QA sign-off, marks it `done` in `features.md`, and automatically archives all feature artefacts to `.aioson/context/done/{slug}/`.
+`@product` creates a feature-scoped `prd-{slug}.md` and registers the feature in `features.md`. `@analyst` produces `requirements-{slug}.md` and `spec-{slug}.md`. `@scope-check` compares intent against the planned implementation before coding. `@dev` reads the feature spec. `@qa` closes the feature by running `feature:close --verdict=PASS`, which updates `spec-{slug}.md` with a QA sign-off, marks it `done` in `features.md`, and automatically archives all feature artefacts to `.aioson/context/done/{slug}/`.
 
 The `SMALL` and MEDIUM outputs include a note reminding you of this sequence.
 
@@ -400,6 +400,32 @@ aioson feature:archive . --feature=checkout --force
 
 ---
 
+## feature:export
+
+**Copy** all artefacts of a feature into a clean output directory, leaving the source tree untouched. Sibling of `feature:archive`, but a non-destructive copy to an arbitrary `--out` — turns AIOSON's markdown output into a portable deliverable. Use it to analyse a feature's specs outside the project, hand them to a client, or use AIOSON purely as a spec generator.
+
+```bash
+aioson feature:export . --feature=checkout
+aioson feature:export . --feature=checkout --out=../checkout-specs
+aioson feature:export . --feature=checkout --flatten
+aioson feature:export . --feature=checkout --no-index
+aioson feature:export . --feature=checkout --dry-run --json
+```
+
+**Options:**
+- `--feature=<slug>` — feature identifier (required).
+- `--out=<dir>` — destination directory. Default: `<target>/{slug}-export`.
+- `--flatten` — collapse the mirrored structure into a single level; nested files become `label-...-file.ext` (collision-free). Default: mirrored (`dossier/`, `plans/`, `briefings/`, `done/`).
+- `--no-index` — skip the generated `INDEX.md`. Default: an `INDEX.md` manifest is written listing every exported file and its source.
+- `--dry-run` — preview what would be copied without writing anything.
+- `--json` — structured JSON output with `outDir`, `count`, `copied`, and `index`.
+
+**What it copies:** the same surface `feature:archive` enumerates — root `*-{slug}.{md,yaml,yml,json}` files (minus global files), the per-slug `dossier/`, `plans/`, and `briefings/` directories, plus `context/done/{slug}/` when the feature is already archived. The slug-collision guard is honoured, so a sibling slug (`checkout-v2`) never leaks into a `checkout` export.
+
+**Non-destructive:** the source artefacts are never moved or deleted. Re-running overwrites files in the out dir but does not remove stale ones. Unlike `feature:archive`, there is no `features.md` status guard — you can export an in-progress feature.
+
+---
+
 ## test:smoke
 
 End-to-end integration test that installs AIOSON in a temporary directory, runs all major commands, and verifies the output. Used for CI and release validation.

package/docs/en/README.md

@@ -40,7 +40,7 @@ This is the entry door to the English documentation. It is not an alphabetical i
 See [3-recipes/README.md](./3-recipes/README.md) for the full list.
 
 ### I want the technical reference for an agent or command
-- **[Agent cards (in progress)](./4-agents/README.md)** — stub today; full set is in [docs/pt/4-agentes/](../pt/4-agentes/README.md) (28 cards)
+- **[Agent cards (in progress)](./4-agents/README.md)** — stub today; full set is in [docs/pt/4-agentes/](../pt/4-agentes/README.md) (29 cards)
 - **[Technical reference](./5-reference/README.md)** — 11 docs migrated from the previous flat structure (CLI, MCP, parallel, QA browser, squad dashboard, web3, i18n, JSON schemas, release flow)
 
 ### Highlights of `5-reference/`
@@ -109,7 +109,7 @@ This English portal is being **incrementally translated** from `docs/pt/`. The p
 - 4-agents (stub README; full agent cards pending)
 
 **Phase 2 (next)** — remaining 8 scenario recipes in 3-recipes/.
-**Phase 3 (next)** — 28 agent cards in 4-agents/.
+**Phase 3 (next)** — 29 agent cards in 4-agents/.
 **Phase 4 (next)** — remaining ~18 reference docs in 5-reference/ (feature-dossier, agent-chain-continuity, sdd-framework, live-sessions, secure-by-default, aioson-com-store, etc.).
 
 For anything not yet in English, the PT version is current and authoritative — the AIOSON behaviors, agent prompts, and CLI commands are language-agnostic.

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

@@ -1,7 +1,8 @@
 # Guia de Agentes AIOSON
 
-> Índice completo dos 29 agentes, com situação de uso e saída esperada.
+> Índice com 29 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.
 
 ---
 
@@ -9,10 +10,10 @@
 
 | 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) |
+| [@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/` |
@@ -31,6 +32,7 @@
 | [@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` |
 | [@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 |
@@ -52,7 +54,7 @@
 | [@design-hybrid-forge](./design-hybrid-forge.md) | Combina dois design skills num híbrido | Quer visual que não existe nos padrões | novo design skill |
 | [@orache](./orache.md) | Investigação de domínio e pesquisa estratégica | Antes de entrar num mercado novo | relatório de domínio |
 | [@copywriter](./copywriter.md) | Copy de conversão: landing pages, emails | Quando precisa de texto que converte | copy entregável |
-| [@discovery-design-doc](./discovery-design-doc.md) | Discovery + design doc combinados | Projetos que precisam dos dois de uma vez | `discovery.md` + `design-doc.md` |
+| [@discovery-design-doc](./discovery-design-doc.md) | Consolida discovery, readiness e design doc | Escopo vago ou etapa pré-dev SMALL/MEDIUM | `design-doc*.md` + `readiness*.md` |
 
 ---
 

package/docs/pt/4-agentes/briefing-refiner.md

@@ -0,0 +1,122 @@
+# @briefing-refiner — Revisa e refina um briefing antes do PRD
+
+> **Para quem é:** quem já tem um briefing gerado pelo `@briefing` e quer revisá-lo, anotar e refinar antes de comprometer um PRD.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que o `@briefing-refiner` faz e onde ele entra no fluxo.
+> - Como funciona a superfície de revisão local em HTML e por que o feedback é estruturado (JSON), não o DOM.
+
+## Para que serve
+
+Entre o briefing gerado e o PRD há uma etapa que costuma ser pulada: **revisar o briefing com olhar crítico**. Ambiguidades, redundâncias, decisões faltando, riscos vagos e gaps de impacto de implementação passam direto para o `@product` e viram dívida no PRD.
+
+O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, gera uma **superfície de revisão local** (`review.html`) onde você edita cada seção, marca status e deixa notas, e depois aplica de volta ao briefing **apenas o feedback estruturado que você confirmar** — preservando o contrato do briefing (todas as seções obrigatórias).
+
+É o complemento do [`@briefing`](./briefing.md): um gera, o outro refina.
+
+## Quando invocar
+
+- Você já tem um briefing em `.aioson/briefings/{slug}/briefings.md` e quer revisá-lo antes do PRD.
+- O briefing está `draft`, ou `approved` mas ainda **sem PRD gerado** (`prd_generated: null`).
+- Quer registrar comentários, pedir mudanças por seção ou marcar bloqueios antes de seguir para `@product`.
+
+## Quando NÃO invocar
+
+- Ainda não existe briefing — vá primeiro para [`@briefing`](./briefing.md).
+- O briefing já gerou PRD (`prd_generated` preenchido) — refinar exigiria uma rota nova de PRD/enrichment, fora deste agente.
+- A ideia mudou tanto que vale regerar do zero — volte ao `@briefing`.
+
+## Dois modos de operação
+
+### 1. Gerar revisão
+
+Quando ainda não há feedback pendente. O agente audita o briefing e escreve a superfície de revisão:
+
+```
+Você > @briefing-refiner
+
+@briefing-refiner > Briefing refinável encontrado: marketplace-v1 (draft).
+
+                    Auditando seções... ambiguidades: 3, redundâncias: 1,
+                    gaps de implementação: 2, riscos vagos: 1.
+
+                    Gerei a revisão:
+                    - .aioson/briefings/marketplace-v1/review.html
+                    - .aioson/briefings/marketplace-v1/refinement-feedback.json
+                    - .aioson/briefings/marketplace-v1/refinement-report.md
+
+                    Abra o review.html, edite as seções, marque status/notas,
+                    salve/exporte o refinement-feedback.json e me reative.
+```
+
+### 2. Aplicar feedback pendente
+
+Quando existe um `refinement-feedback.json` com mudanças não aplicadas. O agente valida, resume o que vai mudar e **pede confirmação explícita** antes de tocar o briefing:
+
+```
+Você > @briefing-refiner
+
+@briefing-refiner > Feedback pendente em marketplace-v1:
+                    - 4 seções com mudança aceita
+                    - 2 comentários não resolvidos
+                    - 1 item bloqueante (modelo de comissão)
+
+                    Aplico as 4 mudanças confirmadas? (o item bloqueante
+                    impede o handoff para @product até ser resolvido)
+Você > Sim.
+
+@briefing-refiner > Aplicado. Como o briefing estava `approved` sem PRD,
+                    voltei para `draft`. Relatório: refinement-report.md.
+```
+
+Se você recusar, o `briefings.md` fica intacto e as mudanças puladas são registradas no relatório.
+
+## A superfície de revisão (review.html)
+
+O diferencial deste agente. O `review.html` é **estático, local e self-contained**:
+
+- sem servidor, sem scripts ou serviços externos;
+- seções editáveis em texto puro, com layout denso de revisão;
+- controles de status por seção: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`;
+- notas/comentários por seção e um resumo do que será feito, do que é incerto e do que bloqueia o PRD;
+- filtros por ambiguidade, redundância, gap, risco, decisão pendente e sugestão de escopo;
+- **exportar/baixar/copiar o JSON sempre disponível** (a File System Access API é só um plus opcional, após ação explícita).
+
+> **Por que JSON e não o HTML editado?** O agente nunca trata o DOM/HTML editado como feedback canônico — só o `refinement-feedback.json` estruturado. Isso evita aplicar mudanças inferidas e mantém o processo auditável.
+
+## Saídas em disco
+
+| Arquivo | O que contém |
+|---|---|
+| `.aioson/briefings/{slug}/review.html` | Superfície de revisão local e editável |
+| `.aioson/briefings/{slug}/refinement-feedback.json` | Feedback estruturado (a única fonte que o agente aplica) |
+| `.aioson/briefings/{slug}/refinement-report.md` | Relatório do que foi aplicado, pulado ou bloqueado |
+| `.aioson/briefings/{slug}/briefings.md` | Atualizado **apenas** após confirmação |
+| `.aioson/briefings/config.md` | Índice/registro de briefings atualizado |
+
+## Como ele lê seu projeto
+
+1. `.aioson/config.md`
+2. `.aioson/context/project.context.md`
+3. `.aioson/briefings/config.md` — resolve o slug refinável (se ausente, roteia para `@briefing`).
+4. `.aioson/briefings/{slug}/briefings.md` — lido antes de escrever qualquer artefato de revisão.
+
+## Limites importantes (hard constraints)
+
+- Nunca cria ou edita `prd*.md`.
+- Nunca aprova um briefing automaticamente.
+- Nunca roteia para `@product` enquanto houver itens bloqueantes.
+- Nunca trata HTML/DOM editado como feedback canônico — só o JSON estruturado.
+- Nunca descarta seções obrigatórias do briefing.
+- Em V1, não há comando CLI dedicado de refinement — tudo passa pelo agente.
+
+## Handoff típico
+
+- **Vem de:** [`@briefing`](./briefing.md) (briefing gerado) ou de você, retomando uma revisão.
+- **Vai para:** depois de aplicar as mudanças e sem bloqueios → `aioson briefing:approve . --slug={slug}` → [`@product`](./product.md). Se sobrar bloqueio, você resolve no review e reativa o `@briefing-refiner`.
+
+## Próximo passo
+
+- Gerar o briefing antes de refinar → [@briefing](./briefing.md)
+- Fluxo completo até o PRD → [Da ideia ao PRD via briefing](../3-receitas/da-ideia-ao-prd-via-briefing.md)
+- Termos como "gap" e "PRD" → [Glossário](../1-entender/glossario.md)