@jaimevalasek/aioson 1.9.0 → 1.9.2

package/template/.aioson/agents/product.md

@@ -254,11 +254,12 @@ The detailed product protocol is split into on-demand framework docs:
 
 Run this before asking the first product question or writing any PRD:
 
-1. After mode detection, load `.aioson/docs/product/conversation-playbook.md`
-2. Before the first synthesis or any finalize decision, load `.aioson/docs/product/research-loop.md` and derive the current keyword set
-3. Before writing or updating any PRD file, load `.aioson/docs/product/quality-lens.md`
-4. Before writing or updating any PRD file, load `.aioson/docs/product/prd-contract.md`
-5. If `project_type` is `site` or `web_app`, `design_skill` is already set, or the user mentions visual quality/preferences, use the loaded docs to preserve the design-skill decision and the `## Visual identity` contract
+1. Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
+2. After mode detection, load `.aioson/docs/product/conversation-playbook.md`
+3. Before the first synthesis or any finalize decision, load `.aioson/docs/product/research-loop.md` and derive the current keyword set
+4. Before writing or updating any PRD file, load `.aioson/docs/product/quality-lens.md`
+5. Before writing or updating any PRD file, load `.aioson/docs/product/prd-contract.md`
+6. If `project_type` is `site` or `web_app`, `design_skill` is already set, or the user mentions visual quality/preferences, use the loaded docs to preserve the design-skill decision and the `## Visual identity` contract
 
 Do not proceed to PRD writing until the research loop, quality lens, and PRD contract have all been loaded.
 
@@ -267,7 +268,7 @@ Do not proceed to PRD writing until the research loop, quality lens, and PRD con
 The essential product conversation rules are:
 
 1. First message = one open question only
-2. From the second message onward, ask up to 5 numbered questions per batch
+2. Cadence by `profile` (from `project.context.md`): `creator` (or absent/auto) → 1 question per turn via `AskUserQuestion` with `(Recomendado)` on the first option and `Pausar / quero pensar` always available; `developer` → up to 5 numbered questions per batch; `team` → up to 5 per batch + emit executive summary at `agent:done`
 3. End every batch with: `6 - Finalize — write the PRD now with what we have.`
 4. Reflect understanding before opening a new topic
 5. Surface edge cases, ownership, empty states, dependencies, and failure modes proactively
@@ -340,6 +341,7 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
 - Never produce a PRD section you haven't actually discussed — write "TBD" instead.
 - Keep PRD files focused: if a section is growing beyond 5 bullet points, summarize.
 - Always run the integrity check before starting a feature conversation — never skip it.
@@ -347,5 +349,19 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 - **Always register every new feature in `features.md` before ending the session.** No PRD is complete without a corresponding `features.md` entry. Create `features.md` if it does not exist.
 - **Always emit the structured handoff** after writing the PRD. The session is not done until the next agent and action are explicit.
 
+## Dev handoff producer
+
+When the PRD classification is **MICRO** (next agent will be `@dev` directly without intermediate stages), produce `dev-state.md` before the final `agent:done` call so the next `/dev` session auto-resumes on cold start:
+
+```bash
+aioson dev:state:write . --feature={slug} \
+  --next="Implement MVP per prd-{slug}.md must-have section" \
+  --context=prd
+```
+
+`--context` accepts canonical tokens (`prd`, `requirements`, `spec`, `architecture`, `impl-plan`, `sheldon`, `design-doc`, `dossier`), max 4 entries total. For MICRO features `--context=prd` is usually sufficient. Idempotent: re-running with the same args does not duplicate state.
+
+Skip this step when classification is SMALL or MEDIUM — `@analyst` (and downstream agents) own the handoff producer in those flows.
+
 ## Observability
 At session end, register: `aioson agent:done . --agent=product --summary="PRD <slug>: <classification>, <N> stories" 2>/dev/null || true`

package/template/.aioson/agents/setup.md

@@ -43,6 +43,7 @@ This single command installs the template, auto-detects the framework, infers th
 If the template is already installed but `project.context.md` is missing, proceed with detection and full onboarding below.
 
 ## Mandatory sequence
+0. Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
 1. **Entry check** (above) — return summary if project.context.md exists and is valid; auto-repair first if it exists but is inconsistent; full flow if it does not exist.
 2. Detect framework in the current directory.
 3. Confirm detection with the user before proceeding.
@@ -123,7 +124,7 @@ Use the answer to infer `project_type`, `profile`, and a starter stack. Then go
 **Infer profile from context:**
 - Individual developer describing their own project → `developer`
 - "we", "our team", "our company" → `team`
-- Uncertain, non-technical description, or asking what to use → `beginner`
+- Uncertain, non-technical description, or asking what to use → `creator`
 
 ### Step 2 — Propose complete stack and confirm
 After inferring project_type, propose a full stack in one message. Show everything at once:
@@ -234,9 +235,9 @@ For `api`, `script`, and non-UI-first scopes, keep `design_skill` empty unless t
 
 ---
 
-### Beginner profile — extra guidance
+### Creator profile — extra guidance
 After collecting the description:
-1. Propose a beginner-friendly stack (prefer managed services, minimal setup).
+1. Propose a creator-friendly stack (prefer managed services, minimal setup).
 2. Explain each choice in plain language.
 3. Ask for explicit confirmation before proceeding.
 
@@ -246,6 +247,7 @@ Respect existing conventions — do not suggest replacing team standards.
 
 ## Hard constraints
 - Never silently default `project_type`, `profile`, `classification`, `interaction_language`, or `conversation_language`.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
 - If answers are partial, ask follow-up questions until required fields are complete.
 - If any assumption is made, ask explicit confirmation before writing the file.
 
@@ -284,7 +286,7 @@ Generate `.aioson/context/project.context.md` in this format:
 ---
 project_name: "<name>"
 project_type: "web_app|api|site|script|dapp"
-profile: "developer|beginner|team"
+profile: "developer|creator|team"
 framework: "Laravel|Rails|Django|Next.js|Nuxt|Node|Hardhat|Foundry|Truffle|Anchor|Solana Web3|Cardano|..."
 framework_installed: true
 classification: "MICRO|SMALL|MEDIUM"

package/template/.aioson/docs/deyvin/runtime-handoffs.md

@@ -34,3 +34,9 @@ If the user did not enter through `aioson live:start`, keep one direct session o
 ## Dashboard visibility
 
 Plain natural-language agent activation in an external client does not create runtime records by itself. If the user wants tracked dashboard visibility, they must enter through `aioson workflow:next`, `aioson agent:prompt`, or `aioson live:start` first.
+
+## Cross-session handoffs — persist before /clear
+
+The runtime helpers above cover same-session handoffs (`live:handoff`, `runtime:session:finish`). For cross-session handoffs — when the next agent will run in a fresh terminal or after `/clear` — chat memory does not survive. Before suggesting `/clear`, persist the diagnostic to `plans/{slug}.md` so the next agent works from an artifact rather than from a seed prompt.
+
+Load `.aioson/docs/handoff-persistence.md` for the full pattern (when to apply, what to write, the exit-block template). Apply it whenever the recommended next agent is one that consumes raw plans (`/briefing` foremost, sometimes `/product`) or needs the full diagnostic to operate (`/analyst`, `/architect`, `/sheldon`). Skip when the next agent continues in the same session, or when the handoff is trivial.

package/template/.aioson/docs/handoff-persistence.md

@@ -0,0 +1,94 @@
+---
+description: "Persist context to plans/{slug}.md before suggesting /clear in a cross-session handoff — preserves the diagnostic so the next agent works from an artifact, not from chat memory."
+---
+
+# Handoff Persistence
+
+Load this when you are about to issue a routing recommendation that involves `/clear`, a fresh terminal, or any other context boundary that drops the current conversation. Same-session handoffs (the next agent inherits the same chat) do not need this — skip the doc.
+
+## The problem
+
+A routing agent (`@neo`, `@deyvin`) ends a session by suggesting:
+1. `/agent` — activate the next agent
+2. `/clear` — fresh context window before continuing
+
+If the recommendation depends on diagnostic work done in this session (file reads, line numbers, decisions made, options weighed), and the user runs `/clear` first, **all of that context is lost**. The next agent reads only the seed prompt the user types — which can never capture the nuance of the actual diagnostic.
+
+A seed prompt is a memory of a conversation. An artifact is a memory of work.
+
+## The rule
+
+Before suggesting `/clear` to the user, persist the actionable diagnostic to `plans/{slug}.md` at the project root. Then the recommendation becomes:
+
+```
+1. Activate /briefing (or /product / /architect / …)
+2. /clear is safe — the next agent reads plans/{slug}.md
+```
+
+`plans/` is the canonical input directory for `/briefing` (and a useful seed for `/product` too). The directory may not exist yet — create it.
+
+## When to apply
+
+| Situation | Persist? |
+|---|---|
+| Handoff routes to an agent that takes raw plans (`/briefing` first and foremost, sometimes `/product`) | Yes |
+| Handoff routes to an agent that needs a discovery pass (`/analyst`, `/architect`, `/sheldon`) | Yes — they read context from `.aioson/context/` AND from raw plans |
+| Same-session continuation (`/dev` keeps going, `/qa` reviews implementation just done) | No — context is in chat |
+| Handoff happens via tracked live session (`aioson live:handoff`) | No — telemetry already carries the trail |
+| Trivial routing ("you want `/setup` first") with no diagnostic to preserve | No |
+
+## What to write
+
+Structure of `plans/{slug}.md` (lightweight — `/briefing` will enrich it):
+
+```md
+# {Short title} — raw plan
+
+> Status: raw input for /{next-agent}. Generated {date} during a /{this-agent} session.
+
+## Why this exists
+1-2 paragraphs framing the problem in the user's terms.
+
+## Symptoms observed
+Concrete pinned facts: line numbers, file paths, command outputs. Not opinions.
+
+## What's already delivered
+If part of the work landed in this session, name the commits/files.
+
+## Proposed scope (if applicable)
+Layers / phases / options the next agent should consider. Mark recommendations.
+
+## Open decisions for the next agent to surface
+Questions that need user input but were out of scope for this session.
+
+## Pointers
+Files, commits, line numbers, related plans/. The next agent reads these directly.
+
+## Out of scope
+What you deliberately did NOT cover. Prevents the next agent from re-litigating.
+```
+
+Slug rules: kebab-case, descriptive, unique inside `plans/`. Examples: `lay-user-agent-mode.md`, `payment-integration.md`, `auth-rewrite-rfc.md`. Avoid generic names like `notes.md` or `plan.md`.
+
+## What to tell the user
+
+After persisting, end with a clear handoff block. Example:
+
+```
+## Next Up
+- Routed to: /briefing
+- Activate: /briefing
+- Context persisted: plans/lay-user-agent-mode.md
+- /clear is safe — the next agent reads from the file
+
+Session artifacts written:
+- [x] plans/lay-user-agent-mode.md
+- [x] {any other files this session produced}
+```
+
+## Anti-patterns
+
+- **Inlining 2 KB of diagnostic as a "seed prompt" in the routing message.** The user shouldn't have to copy-paste a wall of text. Persist it.
+- **Persisting trivial routings.** A user who asks "what does `/setup` do" doesn't need a `plans/` file written. Apply the table above.
+- **Persisting code archaeology.** Code lives in code; reading recommendations live in the artifact only when they would otherwise be lost across `/clear`.
+- **Forgetting to mention the file.** If you wrote `plans/{slug}.md` but the handoff message doesn't reference it, the user won't know to read it (or to let the next agent read it).

package/template/.aioson/skills/process/decision-presentation/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: decision-presentation
+description: Process skill for profile-aware user-facing decisions. Translates framework jargon, enforces (Recomendado) marker on AskUserQuestion, and caps cadence at 1 question/turn when profile=creator. Load before the first user-facing question regardless of profile.
+activation: |
+  You are now running the decision-presentation process. Read `profile` from `.aioson/context/project.context.md`. If `profile=creator` (or absent/auto), enforce strict mode: 1 question per turn via AskUserQuestion with explicit (Recomendado) marker on the first option, plain-language `why`, and "Pausar / quero pensar" always available. If `profile=developer`, allow standard cadence (up to 5 numbered questions per batch, jargon permitted). If `profile=team`, behave as developer + emit `summary-{slug}-executive.md` at agent:done.
+---
+
+# Skill: decision-presentation
+
+> Process skill. Profile-aware UX layer for user-facing decisions.
+> Load this file first. Then lazy-load `references/jargon-map.{en,pt-BR}.yaml` only when about to emit a framework term.
+
+## When to use
+
+Load this skill before the first user-facing decision in any agent that interacts directly with the user. Mandatory in V1 for: `@neo`, `@setup`, `@product`, `@dev`, `@deyvin`.
+
+Activation mode is decided by `profile` in `project.context.md`:
+
+| profile | cadence | jargon | recommendation marker |
+|---------|---------|--------|----------------------|
+| `creator` (default) | 1 question per turn | translated via dictionary | mandatory `(Recomendado)` |
+| `developer` | up to 5 per batch | permitted | optional |
+| `team` | up to 5 per batch | permitted | optional + executive summary at agent:done |
+
+When `profile` is absent, empty, or `auto`, treat as `creator` (safer default).
+
+## Core rules
+
+### Rule 1 — AskUserQuestion is mandatory for decisions
+
+When `profile=creator`, never emit free-form open questions to the user. Always use `AskUserQuestion` with 2-4 options. Free-form input is only allowed inside an "Other / Conte com suas palavras" option of an otherwise-structured question.
+
+### Rule 2 — Recommendation marker on first option
+
+When `profile=creator`, the first option in every `AskUserQuestion` carries `(Recomendado)` in its label AND a one-sentence `description` explaining the recommendation in plain language. Trade-offs are expressed operationally: "se escolher X, demora mais mas evita Y".
+
+### Rule 3 — One question per turn (creator mode)
+
+When `profile=creator`, each agent turn emits at most 1 `AskUserQuestion`. Multiple decisions are staged across turns. Reflection of understanding precedes each new decision.
+
+### Rule 4 — Jargon translation via dictionary
+
+Before emitting any framework term, lazy-load the jargon-map for `interaction_language` (en or pt-BR; fallback to en). Look up the canonical term and substitute the `translation`. If a term is not in the dictionary, emit it verbatim (no transformation) and consider it a candidate for V2 dictionary coverage.
+
+When `profile=developer`, jargon is permitted unaltered. When `profile=team`, jargon is permitted in the operator-facing flow but the executive summary uses translations.
+
+### Rule 5 — Pause option always available
+
+Every `AskUserQuestion` in creator mode includes an option labeled "Pausar / quero pensar" (or its `en` equivalent "Pause / let me think") with `description: "Você pode parar agora e retomar mais tarde. O agente registra o estado e continua na próxima sessão."`
+
+### Rule 6 — Five-or-more alternatives escape hatch
+
+`AskUserQuestion` accepts 2-4 options (harness limit). When a decision has 5+ valid alternatives:
+
+1. Surface the 3 strongest alternatives via `AskUserQuestion` with `(Recomendado)` on the first.
+2. Add a free-form option labeled "Other / Conte com suas palavras" as the last option.
+3. If the user picks "Other", the agent synthesizes the free-form answer into one of the known alternatives internally.
+
+## Loading order
+
+1. Agent kernel preflight loads this `SKILL.md`.
+2. Agent reads `profile` from `project.context.md`.
+3. When about to emit a framework term, agent lazy-loads `references/jargon-map.{lang}.yaml` (only the file matching `interaction_language` or `conversation_language`).
+4. Translation lookup is case-sensitive with word-boundary matching (regex `\b{term}\b`). Substring matches like "MICRO" inside "MICROserviços" do NOT match.
+
+## API surface (V1 — prompt-level only)
+
+V1 exposes no executable functions. The skill is pure prompt-level guidance — the agent reads these rules and adapts behavior. V2 may add imperative helpers (`present_decision(question, options, recommended_index, plain_language_why)`, `translate(term, target_lang, profile)`) if doctor check repeatedly catches violations.
+
+Optional API hook reserved for task-mode override: `force_profile` — an explicit profile override that bypasses the project.context.md value for a single decision. V1 reads this from a per-call argument; V2 may activate task-mode (skill activates per task, not per identity).
+
+## Output contract
+
+When this skill is active, every user-facing decision produces:
+
+- one `AskUserQuestion` (creator mode) or up to 5 batched numbered questions (developer/team mode)
+- a `(Recomendado)` marker on the first option (creator mode; optional for developer/team)
+- jargon translated via dictionary (creator mode) or verbatim (developer/team mode)
+- a "Pausar / quero pensar" option (creator mode)
+- no free-form open questions outside the escape hatch
+
+## Doctor check integration
+
+The doctor check `jargon_leak_detection` (defined in this same feature) verifies adherence in CI:
+
+- scope filter: only events from `[neo, setup, product, dev, deyvin]`
+- profile filter: only runs when active project has `profile=creator`
+- success threshold: `count=0` jargon leaks in a feature MICRO completa run with `profile=creator`
+
+Skill failure does not break `report.ok` — severity is `warning` (advisory).
+
+## Default profile semantics
+
+| project.context.md value | effective profile |
+|--------------------------|-------------------|
+| `profile: creator` | creator |
+| `profile: developer` | developer |
+| `profile: team` | team |
+| `profile: auto` | creator (safer default) |
+| `profile:` (empty) | creator |
+| missing `profile` field | creator |
+| legacy `profile: beginner` | creator (migrated by installer) |
+
+## Migration note (beginner → creator)
+
+Legacy projects with `profile: beginner` are migrated by `aioson update`:
+
+1. Installer detects `profile: beginner` in `project.context.md` frontmatter.
+2. Rewrites to `profile: creator`.
+3. Emits `runtime:emit --type=migration --level=info` with message: "Profile `beginner` renamed to `creator` to better describe the user. Behavior unchanged. Edit `.aioson/context/project.context.md` to switch to `developer` if desired."
+4. Migration is idempotent — running twice does not double-emit nor reverse.
+
+## What this skill does NOT do
+
+- Does not intercept agent output at runtime (no in-loop guard). Violations are caught after-fact by `jargon_leak_detection`.
+- Does not auto-detect profile via behavioral heuristics (V2).
+- Does not capture full agent transcripts (V2; V1 sees summaries via `agent_events`).
+- Does not activate task-mode override (V1 reserves the API; V2 implements).
+- Does not load for `@analyst`, `@architect`, `@qa`, `@discovery-design-doc`, `@briefing`, `@committer` (V2 follow-up after V1 validates).

package/template/.aioson/skills/process/decision-presentation/references/jargon-map.en.yaml

@@ -0,0 +1,108 @@
+version: 1
+language: en
+# Jargon dictionary — English translations for the decision-presentation skill.
+# Lookup: case-sensitive, word-boundary (\b{term}\b). Substring matches blocked.
+# Lazy-loaded by the skill only when about to emit a framework term to a creator-profile user.
+# Adding a term: keep `translation` short (≤6 words), `context` plain language (≤120 chars),
+# `examples` covering typical phrasings the term appears in.
+
+terms:
+  MICRO:
+    translation: "quick"
+    context: "A small feature type — usually finishes in 1-2 hours of work."
+    examples: ["feature MICRO", "classification: MICRO", "MICRO project"]
+
+  SMALL:
+    translation: "standard"
+    context: "A medium-sized feature type — usually takes 1-3 days end to end."
+    examples: ["classification: SMALL", "SMALL feature"]
+
+  MEDIUM:
+    translation: "full"
+    context: "A complex feature type — takes a week or more, with several review checkpoints."
+    examples: ["classification: MEDIUM", "MEDIUM project"]
+
+  "Gate A":
+    translation: "first checkpoint — requirements ready"
+    context: "Confirms the requirements are written down before anyone starts building."
+    examples: ["Gate A pending", "Gate A approved"]
+
+  "Gate B":
+    translation: "design checkpoint — architecture decided"
+    context: "Confirms how the system will be built before code starts."
+    examples: ["Gate B pending", "Gate B approved"]
+
+  "Gate C":
+    translation: "plan checkpoint — execution plan signed off"
+    context: "Confirms the step-by-step plan is in place before implementation."
+    examples: ["Gate C pending", "Gate C approved"]
+
+  "Gate D":
+    translation: "final review before closing"
+    context: "Last quality check the QA does before marking the feature as done."
+    examples: ["Gate D pending", "Gate D approved"]
+
+  tier1:
+    translation: "silent automated action"
+    context: "An action the agent takes by itself, no notification — usually reading or telemetry."
+    examples: ["tier1 command", "tier1 silent"]
+
+  tier2:
+    translation: "notified automated action"
+    context: "An action the agent takes and tells you about — usually a write to memory."
+    examples: ["tier2 command", "tier2 notified"]
+
+  tier3:
+    translation: "action that needs your approval"
+    context: "An irreversible action the agent never does alone — like publishing or pushing."
+    examples: ["tier3 command", "tier3 blocking"]
+
+  circuit_open:
+    translation: "safety brake engaged"
+    context: "A built-in stop that prevents the agent from retrying after repeated failures."
+    examples: ["circuit_open", "circuit state: CLOSED"]
+
+  harness-contract:
+    translation: "agent runtime agreement"
+    context: "The set of rules a feature commits to follow so the agent runtime can track it."
+    examples: ["harness-contract.json", "harness contract"]
+
+  waiting_validation:
+    translation: "waiting for QA approval"
+    context: "Feature is implemented but QA hasn't signed off yet."
+    examples: ["status: waiting_validation"]
+
+  ready_for_done_gate:
+    translation: "ready for final review"
+    context: "Feature passed all earlier checks and is queued for the final QA pass."
+    examples: ["ready_for_done_gate: true"]
+
+  dossier:
+    translation: "feature folder"
+    context: "A living document that consolidates everything about one feature in one place."
+    examples: ["feature dossier", "dossier.md"]
+
+  brain:
+    translation: "agent memory pattern file"
+    context: "Procedural memory the agent reuses — like reminders learned from past projects."
+    examples: ["brain node", "brain pattern"]
+
+  scout:
+    translation: "side investigation"
+    context: "A quick read-only side task that gathers information without interrupting main work."
+    examples: ["scout subtask", "scout dispatch"]
+
+  in_progress:
+    translation: "in progress"
+    context: "Work is happening right now on this item."
+    examples: ["status: in_progress"]
+
+  done:
+    translation: "finished"
+    context: "Item is closed and shipped."
+    examples: ["status: done"]
+
+  classification:
+    translation: "feature type"
+    context: "How big the feature is — `quick`, `standard`, or `full`."
+    examples: ["classification: SMALL"]

package/template/.aioson/skills/process/decision-presentation/references/jargon-map.pt-BR.yaml

@@ -0,0 +1,108 @@
+version: 1
+language: pt-BR
+# Dicionário de jargão — traduções pt-BR para a skill decision-presentation.
+# Lookup: case-sensitive, word-boundary (\b{term}\b). Match por substring bloqueado.
+# Carga lazy pela skill só quando vai emitir um termo de framework pra usuário com profile=creator.
+# Adicionar termo: `translation` curto (≤6 palavras), `context` em linguagem corrente (≤120 chars),
+# `examples` cobrindo frases típicas onde o termo aparece.
+
+terms:
+  MICRO:
+    translation: "rápida"
+    context: "Tipo de feature pequena — costuma fechar em 1-2 horas de trabalho."
+    examples: ["feature MICRO", "classification: MICRO", "projeto MICRO"]
+
+  SMALL:
+    translation: "padrão"
+    context: "Tipo de feature de médio porte — costuma levar 1-3 dias do início ao fim."
+    examples: ["classification: SMALL", "feature SMALL"]
+
+  MEDIUM:
+    translation: "completa"
+    context: "Tipo de feature complexa — leva uma semana ou mais, com vários checkpoints de revisão."
+    examples: ["classification: MEDIUM", "projeto MEDIUM"]
+
+  "Gate A":
+    translation: "primeiro checkpoint — requisitos prontos"
+    context: "Confirma que os requisitos estão escritos antes de alguém começar a construir."
+    examples: ["Gate A pending", "Gate A aprovado"]
+
+  "Gate B":
+    translation: "checkpoint de desenho — arquitetura decidida"
+    context: "Confirma como o sistema vai ser construído antes do código começar."
+    examples: ["Gate B pending", "Gate B aprovado"]
+
+  "Gate C":
+    translation: "checkpoint de plano — execução assinada"
+    context: "Confirma que o passo a passo está pronto antes da implementação."
+    examples: ["Gate C pending", "Gate C aprovado"]
+
+  "Gate D":
+    translation: "revisão final antes de fechar"
+    context: "Última verificação que o QA faz antes de marcar a feature como pronta."
+    examples: ["Gate D pending", "Gate D aprovado"]
+
+  tier1:
+    translation: "ação automática silenciosa"
+    context: "Uma ação que o agente faz sozinho, sem avisar — normalmente leitura ou telemetria."
+    examples: ["comando tier1", "tier1 silent"]
+
+  tier2:
+    translation: "ação automática com aviso"
+    context: "Uma ação que o agente faz e te avisa — normalmente escrita na memória."
+    examples: ["comando tier2", "tier2 notified"]
+
+  tier3:
+    translation: "ação que precisa da sua aprovação"
+    context: "Ação irreversível que o agente nunca faz sozinho — tipo publicar ou dar push."
+    examples: ["comando tier3", "tier3 blocking"]
+
+  circuit_open:
+    translation: "freio de segurança acionado"
+    context: "Parada interna que impede o agente de tentar de novo depois de falhas em sequência."
+    examples: ["circuit_open", "circuit state: CLOSED"]
+
+  harness-contract:
+    translation: "contrato do runtime do agente"
+    context: "Conjunto de regras que a feature se compromete a seguir pra o runtime do agente conseguir rastrear."
+    examples: ["harness-contract.json", "harness contract"]
+
+  waiting_validation:
+    translation: "esperando aprovação do QA"
+    context: "Feature está implementada mas o QA ainda não deu o OK."
+    examples: ["status: waiting_validation"]
+
+  ready_for_done_gate:
+    translation: "pronto pra revisão final"
+    context: "Feature passou em todas as verificações anteriores e está na fila do QA final."
+    examples: ["ready_for_done_gate: true"]
+
+  dossier:
+    translation: "pasta da feature"
+    context: "Documento vivo que consolida tudo sobre uma feature num lugar só."
+    examples: ["dossier da feature", "dossier.md"]
+
+  brain:
+    translation: "memória de padrões do agente"
+    context: "Memória procedural que o agente reusa — tipo lembretes aprendidos de projetos antigos."
+    examples: ["nó de brain", "padrão de brain"]
+
+  scout:
+    translation: "investigação paralela"
+    context: "Tarefa rápida e somente-leitura que coleta informação sem atrapalhar o trabalho principal."
+    examples: ["subtarefa scout", "scout dispatch"]
+
+  in_progress:
+    translation: "em andamento"
+    context: "Trabalho está acontecendo neste item agora."
+    examples: ["status: in_progress"]
+
+  done:
+    translation: "concluído"
+    context: "Item está fechado e entregue."
+    examples: ["status: done"]
+
+  classification:
+    translation: "tipo de feature"
+    context: "Quão grande é a feature — `rápida`, `padrão` ou `completa`."
+    examples: ["classification: SMALL"]