@jaimevalasek/aioson 1.8.0 → 1.9.1

package/template/.aioson/skills/process/aioson-spec-driven/references/ui-language.md

@@ -1,75 +1,75 @@
-# UI Language — AIOSON Visual Standards
-
-> Carregue quando um agente precisa apresentar opções, status ou checkpoints ao usuário.
-
-## Status symbols
-✓ completo / aprovado
-✗ falhou / bloqueado
-◆ em progresso
-○ pendente
-⚠ atenção necessária
-⚡ auto-aprovado
-
-## Stage banner
-Usar ao iniciar fase principal:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- AIOSON ► @{AGENT} — {FASE}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Checkpoint verify (confirmação visual)
-Usar: após implementação que o usuário precisa ver
-```
-┌─────────────────────────────────────────────┐
-│  ✓ VERIFICAR: {título}                      │
-│  {instrução específica}                      │
-│  Confirmar? [s/n]                           │
-└─────────────────────────────────────────────┘
-```
-
-## Checkpoint decision (AskUserQuestion — radio)
-Usar: quando há bifurcação com outcomes diferentes
-→ AskUserQuestion com multiSelect: false, 2-4 opções
-
-```
-┌─────────────────────────────────────────────┐
-│  ◆ DECISÃO NECESSÁRIA                      │
-│                                             │
-│  {contexto da decisão}                      │
-│                                             │
-│  1. {opção A} — {consequências}            │
-│  2. {opção B} — {consequências}            │
-│                                             │
-│  Escolha [1/2]:                            │
-└─────────────────────────────────────────────┘
-```
-
-## Checkpoint action (passo manual)
-Usar: apenas para passos que o agente literalmente não pode executar
-```
-┌─────────────────────────────────────────────┐
-│  ⚠ AÇÃO MANUAL NECESSÁRIA                  │
-│                                             │
-│  {instrução específica}                      │
-│  {onde executar}                             │
-│                                             │
-│  Avise quando estiver pronto.              │
-└─────────────────────────────────────────────┘
-```
-
-## Checkpoint multi-select (AskUserQuestion — checkbox)
-Usar: seleção múltipla (skills, requirements, itens de sprint)
-→ AskUserQuestion com multiSelect: true
-
-## Progress bar
-Usar para fases longas com steps definidos:
-```
-Progresso: ████████░░ 80% (4/5 steps)
-```
-
-## Regras
-- Header máximo 12 caracteres
-- Máximo 4 opções em radio; máximo 8 em checkbox
-- Incluir opção "Nenhuma/Pular" em checkbox quando pertinente
-- Não usar checkbox para decisões que mudam arquitetura (use radio)
+# UI Language — AIOSON Visual Standards
+
+> Carregue quando um agente precisa apresentar opções, status ou checkpoints ao usuário.
+
+## Status symbols
+✓ completo / aprovado
+✗ falhou / bloqueado
+◆ em progresso
+○ pendente
+⚠ atenção necessária
+⚡ auto-aprovado
+
+## Stage banner
+Usar ao iniciar fase principal:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ AIOSON ► @{AGENT} — {FASE}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Checkpoint verify (confirmação visual)
+Usar: após implementação que o usuário precisa ver
+```
+┌─────────────────────────────────────────────┐
+│  ✓ VERIFICAR: {título}                      │
+│  {instrução específica}                      │
+│  Confirmar? [s/n]                           │
+└─────────────────────────────────────────────┘
+```
+
+## Checkpoint decision (AskUserQuestion — radio)
+Usar: quando há bifurcação com outcomes diferentes
+→ AskUserQuestion com multiSelect: false, 2-4 opções
+
+```
+┌─────────────────────────────────────────────┐
+│  ◆ DECISÃO NECESSÁRIA                      │
+│                                             │
+│  {contexto da decisão}                      │
+│                                             │
+│  1. {opção A} — {consequências}            │
+│  2. {opção B} — {consequências}            │
+│                                             │
+│  Escolha [1/2]:                            │
+└─────────────────────────────────────────────┘
+```
+
+## Checkpoint action (passo manual)
+Usar: apenas para passos que o agente literalmente não pode executar
+```
+┌─────────────────────────────────────────────┐
+│  ⚠ AÇÃO MANUAL NECESSÁRIA                  │
+│                                             │
+│  {instrução específica}                      │
+│  {onde executar}                             │
+│                                             │
+│  Avise quando estiver pronto.              │
+└─────────────────────────────────────────────┘
+```
+
+## Checkpoint multi-select (AskUserQuestion — checkbox)
+Usar: seleção múltipla (skills, requirements, itens de sprint)
+→ AskUserQuestion com multiSelect: true
+
+## Progress bar
+Usar para fases longas com steps definidos:
+```
+Progresso: ████████░░ 80% (4/5 steps)
+```
+
+## Regras
+- Header máximo 12 caracteres
+- Máximo 4 opções em radio; máximo 8 em checkbox
+- Incluir opção "Nenhuma/Pular" em checkbox quando pertinente
+- Não usar checkbox para decisões que mudam arquitetura (use radio)

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"]