@jaimevalasek/aioson 1.5.1 → 1.7.0

package/docs/en/cli-reference.md

@@ -6,39 +6,50 @@ Complete reference for all `aioson` commands.
 
 ## init
 
-Create a new project directory and install AIOSON inside it.
+Create a new project directory and install AIOSON inside it. In interactive terminals, an **install wizard** runs first so you choose which AI tools and modes to install.
 
 ```bash
 aioson init <project-name>
 aioson init my-app --lang=pt-BR
 aioson init my-app --tool=codex
-aioson init my-app --lang=es --tool=gemini --json
+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|gemini|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.
 
 **What it does:**
 1. Creates `<project-name>/` directory.
-2. Copies all template files into it.
-3. Applies the selected locale pack.
-4. Prints the recommended first command (`@setup`).
+2. Runs the install wizard (tools + mode selection).
+3. Copies only the files matching your profile.
+4. Shows the AIOSON reveal animation and install summary.
+5. Applies the selected locale pack.
 
 ---
 
 ## install
 
-Install AIOSON in an existing directory (or the current directory).
+Install AIOSON in an existing directory (or the current directory). Runs the same wizard as `init` when in a TTY.
 
 ```bash
 aioson install
 aioson install ./my-project
 aioson install --lang=pt-BR --tool=claude
+aioson install --reconfigure
+aioson install --no-interactive
 ```
 
-**Options:** same as `init`.
+**Options:**
+- `--lang=en|pt-BR|es|fr` — sets locale pack.
+- `--tool=codex|claude|gemini|opencode` — configures AI client.
+- `--reconfigure` — re-run the wizard even if a profile already exists (e.g. to add Gemini later).
+- `--no-interactive` — skip the wizard and install all files.
+- `--force` — overwrite existing files.
+- `--dry-run` — preview without writing.
+- `--json` — prints structured JSON result.
 
 **Use this when:**
 - The project already exists (legacy codebase, existing repo).
@@ -48,7 +59,7 @@ aioson install --lang=pt-BR --tool=claude
 
 ## update
 
-Update managed files to the latest template version. Preserves context files and anything not in the managed file list.
+Update managed files to the latest template version. Respects the saved install profile — only updates files that were originally installed.
 
 ```bash
 aioson update
@@ -60,7 +71,7 @@ aioson update --lang=pt-BR
 - `--lang=en|pt-BR|es|fr` — re-applies the locale pack after updating. If omitted, re-applies whatever locale is currently active.
 - `--json` — prints structured JSON result.
 
-**What it updates:** all files in the `MANAGED_FILES` list (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
+**What it updates:** all files in the `MANAGED_FILES` list that match your install profile (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
 
 ---
 

package/docs/integrations/sdlc-genius-boundary.md

@@ -0,0 +1,76 @@
+# SDLC Genius — Integration Boundary
+
+> Created: 2026-04-02
+> Status: pre-pilot — defines what the app is allowed and not allowed to influence
+
+---
+
+## Boundary Rule
+
+**AIOSON artifacts drive work. SDLC Genius may react to GitHub changes. SDLC Genius does not mutate AIOSON source-of-truth artifacts directly.**
+
+---
+
+## What SDLC Genius Must NOT Own
+
+These artifacts are AIOSON's exclusive responsibility:
+
+| Artifact | Owner | Reason |
+|----------|-------|--------|
+| `prd-{slug}.md` | @product | Product decisions require human + agent deliberation |
+| `requirements-{slug}.md` | @analyst | Business rules require structured discovery |
+| `spec-{slug}.md` | @analyst / @dev | Feature memory and phase gates are AIOSON's execution state |
+| `architecture.md` | @architect | Architecture decisions require full project context |
+| `design-doc*.md` | @architect / @discovery-design-doc | Scope decisions are AIOSON artifacts |
+| `implementation-plan*.md` | @dev / @orchestrator | Execution sequencing belongs to AIOSON |
+| `.aioson/constitution.md` | User | Never externally modified |
+| `.aioson/rules/` | User / @dev | Project conventions are internal |
+
+SDLC Genius must never write to these files, even indirectly.
+
+---
+
+## What SDLC Genius May Own Well
+
+These are appropriate surfaces for a GitHub execution assistant:
+
+| Surface | Notes |
+|---------|-------|
+| PR review comments | Secondary signal — complements @qa, does not replace it |
+| Test generation suggestions | Must be reviewed by developer before accepting |
+| Documentation nudges | Flags stale docs, does not rewrite them |
+| GitHub workflow insights | Metrics and visibility in GitHub context |
+| Code quality signals | Language-level feedback that AIOSON agents do not produce |
+
+---
+
+## How to Interpret SDLC Genius Output
+
+When SDLC Genius comments on a PR:
+
+1. **Check if the comment is already covered by AIOSON artifacts** — if `requirements-{slug}.md` or `spec-{slug}.md` already addresses the point, SDLC Genius is confirming what AIOSON decided
+2. **If the comment contradicts a spec decision** — do not change the code; flag the contradiction to the user for a spec update
+3. **If the comment is about language-level quality** (naming, type safety, unused imports) — act directly without spec update
+4. **If the comment suggests a new requirement** — this is a spec change; route to @product or @analyst, not directly to @dev
+
+---
+
+## Conflict Resolution
+
+When SDLC Genius output conflicts with AIOSON artifacts:
+
+**AIOSON artifact wins.** Always.
+
+The spec is the single source of truth. SDLC Genius is a secondary signal.
+
+If a conflict repeats across multiple PRs, this is a signal that the spec may need updating — not that SDLC Genius is right.
+
+---
+
+## What Happens When the Pilot Ends
+
+After the pilot evaluation (Plan 70 Phase 5):
+
+- **Outcome A (adopt):** this boundary document becomes a standing operating note, promoted to `template/.aioson/docs/sdlc-genius-operating-mode.md`
+- **Outcome B (limited use):** this document is updated to reflect the narrower scope approved
+- **Outcome C (reject):** this document is archived; SDLC Genius is uninstalled

package/docs/integrations/sdlc-genius-eval-matrix.md

@@ -0,0 +1,75 @@
+# SDLC Genius — Evaluation Rubric
+
+> Created: 2026-04-02
+> Purpose: Measure pilot PR reviews against consistent criteria
+> Use: Fill one row per tested PR in `sdlc-genius-review-samples.md`
+
+---
+
+## Evaluation Axes
+
+For each PR where SDLC Genius commented, score each axis from 0 to 3:
+
+| Axis | 0 | 1 | 2 | 3 |
+|------|---|---|---|---|
+| **Relevance** | Comments are unrelated to the change | Partially related | Mostly related | Directly addresses the actual change |
+| **Signal** | No real bugs/risks caught | Low-value noise | Caught something worth reviewing | Caught a real bug or risk not found elsewhere |
+| **Duplication** | Repeats exactly what AIOSON/QA already enforced | Significant overlap | Some overlap | Adds information not in AIOSON artifacts |
+| **Actionability** | Developer cannot act without research | Possible but unclear | Actionable with context | Developer can act immediately |
+| **Traceability** | Cannot link to spec or requirements | Vague connection | Connects to requirements | Explicitly references behavior in spec |
+| **Noise risk** | Too many low-value comments per PR | Several noise comments | Occasional noise | Clean, focused output |
+
+**Score range per PR:** 0–18
+
+---
+
+## Score Interpretation
+
+| Total | Interpretation |
+|-------|---------------|
+| 15–18 | Excellent — strong signal, low noise, high actionability |
+| 10–14 | Good — useful but with improvements needed |
+| 5–9 | Marginal — some value but noise outweighs it in current state |
+| 0–4 | Poor — does not improve on AIOSON-only workflow |
+
+---
+
+## Comparison Against AIOSON Artifacts
+
+For each scored PR, also answer:
+
+| Question | Yes / Partial / No |
+|----------|-------------------|
+| Did SDLC Genius comment on something already in `requirements-{slug}.md`? | |
+| Did SDLC Genius comment on something already in `spec-{slug}.md`? | |
+| Did SDLC Genius catch something AIOSON artifacts missed? | |
+| Did SDLC Genius suggest a change that contradicts a spec decision? | |
+
+---
+
+## Noise Threshold
+
+If more than 30% of comments per PR are scored 0–1 on Relevance or Actionability, the PR is flagged as **noise-dominated**.
+
+A pilot with more than 2 noise-dominated PRs out of 5 tested = Outcome C (reject) unless tuning options exist and reduce noise significantly.
+
+---
+
+## Pilot Conclusion Criteria
+
+| Condition | Suggested Outcome |
+|-----------|------------------|
+| Average score ≥ 12 across 5+ PRs, no spec contradictions | Outcome A — Adopt |
+| Average score 7–11, useful in narrow scope (e.g., code quality only) | Outcome B — Limited use |
+| Average score < 7, OR repeated spec contradictions, OR noise-dominated | Outcome C — Reject |
+| Permissions too broad and cannot be scoped | Outcome C — Reject regardless of score |
+
+---
+
+## How to Use This Matrix
+
+1. Run the pilot PR (see Phase 2 of Plan 70)
+2. For each PR where SDLC Genius commented, score each axis
+3. Record in `sdlc-genius-review-samples.md` with the score, evidence, and comparison against AIOSON artifacts
+4. After 5+ PRs, sum up and apply the conclusion criteria above
+5. Write outcome in `plans/70.1-RESULT-sdlc-genius-pilot.md`

package/docs/integrations/sdlc-genius-install-checklist.md

@@ -0,0 +1,93 @@
+# SDLC Genius — Pilot Install and Rollback Checklist
+
+> Created: 2026-04-02
+> Status: template — fill in before installation
+> Purpose: Ensure the pilot is safe, scoped, and reversible before any installation
+
+---
+
+## Pre-Installation Gate
+
+Do NOT proceed with installation until ALL of the following are confirmed:
+
+- [ ] Plan 69 Phase 0 is complete (process-skill reference debt fixed)
+- [ ] `docs/integrations/sdlc-genius-boundary.md` is read and understood by the pilot owner
+- [ ] Public evaluation questions in `searchings/sdlc-genius-public-evaluation.md` are answered
+- [ ] Privacy policy at https://sof.to/privacy-policy has been reviewed
+- [ ] Pilot repo is chosen and is NOT a production-critical repo
+- [ ] At least one person knows how to uninstall the app
+
+---
+
+## Pilot Scope
+
+| Field | Value |
+|-------|-------|
+| Pilot repo | _(fill in)_ |
+| Installer name | _(fill in)_ |
+| Install date | _(fill in)_ |
+| Planned end date | _(fill in)_ |
+| Organization | _(fill in)_ |
+
+---
+
+## Permissions Review
+
+Before installation, verify and record the permissions the app requests:
+
+| Permission | Requested? | Acceptable? | Notes |
+|------------|-----------|-------------|-------|
+| Repository read (code) | _(confirm)_ | _(yes/no)_ | |
+| Repository write (pull requests) | _(confirm)_ | _(yes/no)_ | |
+| Repo limited to pilot repo only | _(confirm)_ | _(yes/no)_ | |
+| Org-wide access | _(confirm)_ | _(yes/no/reject)_ | Reject if org-wide and cannot scope |
+| Other permissions | _(list any)_ | _(yes/no)_ | |
+
+**If org-wide write access cannot be scoped to a single repo: DO NOT INSTALL.**
+
+---
+
+## Rollback Path
+
+| Step | Owner | Done? |
+|------|-------|-------|
+| Identify uninstall path in GitHub App settings | _(name)_ | [ ] |
+| Confirm the pilot repo reverts to normal after uninstall | _(name)_ | [ ] |
+| Identify who has permissions to uninstall | _(name)_ | [ ] |
+| Document uninstall steps here | _(fill in)_ | [ ] |
+
+Uninstall steps:
+```
+1. _(fill in after confirming from GitHub App settings)_
+2. 
+3. 
+```
+
+---
+
+## Safety Settings to Verify Before First PR
+
+- [ ] SDLC Genius comments are visible but not blocking (no required status checks set)
+- [ ] The app cannot merge PRs automatically
+- [ ] The app cannot push commits to the repo
+- [ ] A pilot owner has verified the first comment output before telling others to use it
+
+---
+
+## Rollback Owner
+
+| Role | Name |
+|------|------|
+| Pilot owner (decision to install) | _(fill in)_ |
+| Uninstall owner (authorized to remove) | _(fill in)_ |
+| Privacy review owner | _(fill in)_ |
+
+---
+
+## Post-Pilot Disposition
+
+At the end of the pilot, one of the following applies:
+
+- [ ] **Keep** — update boundary doc, promote to template
+- [ ] **Keep with limits** — update scope in boundary doc, document narrow use
+- [ ] **Remove** — uninstall, archive this checklist, record reason in `plans/70.1-RESULT-sdlc-genius-pilot.md`

package/docs/integrations/sdlc-genius-review-samples.md

@@ -0,0 +1,86 @@
+# SDLC Genius — Pilot Evidence Log
+
+> Created: 2026-04-02
+> Status: template — fill during pilot
+> Purpose: Record concrete PR review samples for final evaluation
+
+---
+
+## How to Use This File
+
+For each PR where SDLC Genius commented during the pilot:
+
+1. Copy one sample block below
+2. Fill in the PR details and SDLC Genius output
+3. Score each axis using the rubric in `sdlc-genius-eval-matrix.md`
+4. Record the comparison against AIOSON artifacts
+5. Write a 1-line decision: keep / tune / reject
+
+---
+
+## Sample Block Template
+
+```
+### PR #N — [short description of change]
+
+**Date:** YYYY-MM-DD
+**Repo:** [repo name]
+**Feature slug (if any):** [slug or none]
+
+**Most useful SDLC Genius comment:**
+> [paste comment]
+
+**Least useful SDLC Genius comment:**
+> [paste comment]
+
+**Total SDLC Genius comments on this PR:** N
+
+**Axis scores (0–3 each):**
+- Relevance:
+- Signal:
+- Duplication:
+- Actionability:
+- Traceability:
+- Noise risk:
+- **Total:** /18
+
+**AIOSON comparison:**
+- Did requirements-{slug}.md already cover the main SDLC Genius point? Yes / No / Partial
+- Did spec-{slug}.md already cover it? Yes / No / Partial
+- Did SDLC Genius catch something AIOSON missed? Yes / No
+- Did SDLC Genius contradict a spec decision? Yes / No — if yes, describe:
+
+**Decision:** keep / tune / reject
+**Reason:** [1 line]
+```
+
+---
+
+## PR Samples
+
+_(Empty — fill during pilot)_
+
+---
+
+## Running Totals
+
+| PR | Score | Noise-dominated? | Spec contradiction? |
+|----|-------|-----------------|---------------------|
+| #1 | /18 | | |
+| #2 | /18 | | |
+| #3 | /18 | | |
+| #4 | /18 | | |
+| #5 | /18 | | |
+| **Average** | /18 | | |
+
+---
+
+## Preliminary Conclusion
+
+_(Fill after 5+ PRs — apply criteria from `sdlc-genius-eval-matrix.md`)_
+
+- Average score: /18
+- Noise-dominated PRs: / tested
+- Spec contradictions: 
+- Suggested outcome: A / B / C
+- Next step: write `plans/70.1-RESULT-sdlc-genius-pilot.md`

package/docs/pt/README.md

@@ -15,9 +15,19 @@ Bem-vindo à documentação em português do AIOSON — um framework leve de age
 | [Squad e Genome](./squad-genome.md) | Como criar squads modulares, diferenciar skill de genome, aplicar genomes e publicar entregáveis HTML |
 | [Agentes Customizados](./agentes-customizados.md) | Criar agentes personalizados com `squad:agent-create` — tipos, Voice DNA, infra operacional, maturity scoring |
 | [Skills](./skills.md) | Sistema de skills: tipos, instalação, mapeamento por framework e compatibilidade cross-tool |
+| [design-hybrid-forge](./design-hybrid-forge.md) | Fluxo canônico para criar skills híbridas de design com preset visual, locale automático e histórico |
 | [Automação de Squads](./automacao-squads.md) | Transformar processos de squad em scripts executáveis (Python/Node.js) que rodam sem LLM |
 | [Output Strategy e Delivery](./output-strategy-delivery.md) | Configurar webhooks, automatizar entrega de conteúdo, monitorar delivery e troubleshoot |
 | [Suporte Web3](./web3.md) | Guia para projetos dApp (Ethereum, Solana, Cardano) |
+| [Recuperação de Sessão](./recuperacao-de-sessao.md) | Gerar e restaurar contexto entre sessões do Claude Code após compactação |
+| [Monitor de Contexto](./monitor-de-contexto.md) | Visualizar uso de janela de contexto por agente com alertas de warning e critical |
+| [Busca de Contexto](./busca-de-contexto.md) | Indexar e buscar documentos do projeto via FTS5 com ranking por relevância e recência |
+| [Cache de Contexto](./cache-de-contexto.md) | Salvar snapshots de contexto e restaurar entre sessões |
+| [Sandbox de Execução](./sandbox.md) | Executar comandos com timeout, redação de secrets e summarização de output |
+| [Agent Sharding](./agent-sharding.md) | Carregar apenas as seções relevantes de instruções de agente para uma tarefa específica |
+| [Spec & Learnings Pipeline](./spec-learnings-pipeline.md) | Sincronizar specs Markdown com o SQLite, exportar learnings para brains e acompanhar progresso de features |
+| [Devlog Pipeline](./devlog-pipeline.md) | Processar devlogs manuais dos agentes, sincronizar artifacts/learnings/verdict com o SQLite e exportar para brains |
+| [Hooks & Session Guard](./hooks-session-guard.md) | Visibilidade automática no dashboard para Claude Code, Antigravity e Codex — instalar hooks, session:guard e diagnóstico |
 
 ## Documentação em inglês
 

package/docs/pt/agent-sharding.md

@@ -0,0 +1,132 @@
+# Agent Sharding
+
+> Carrega apenas as seções relevantes de um arquivo de instruções de agente para uma tarefa específica, reduzindo consumo de tokens.
+
+Arquivos de instrução de agente podem conter muitas seções — role, guidelines, error handling, output format, checklist de revisão — mas para uma tarefa específica, apenas algumas são necessárias. O `agent:load` divide o arquivo em shards semânticos por heading, indexa via FTS5 e carrega apenas os shards mais relevantes para o objetivo informado.
+
+---
+
+## Comandos
+
+### `agent:shard:index`
+
+Indexa os arquivos de instruções de agentes para permitir carregamento inteligente.
+
+```bash
+aioson agent:shard:index [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--agents-dir=<path>` | Diretório dos agentes (padrão: `.aioson/agents`) |
+| `--force` | Reindexar mesmo se já indexado |
+| `--json` | Retorna resultado em JSON |
+
+**Exemplos:**
+
+```bash
+# Indexar todos os agentes do projeto
+aioson agent:shard:index .
+
+# Forçar reindexação após atualizar arquivos de agente
+aioson agent:shard:index . --force
+
+# Diretório customizado de agentes
+aioson agent:shard:index . --agents-dir=.aioson/my-agents
+```
+
+---
+
+### `agent:load`
+
+Carrega os shards mais relevantes de um agente para um objetivo dado.
+
+```bash
+aioson agent:load <agent-id> [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--goal="..."` | Objetivo da tarefa (direciona a seleção de shards) |
+| `--agents-dir=<path>` | Diretório dos agentes (padrão: `.aioson/agents`) |
+| `--max-shards=<n>` | Máximo de shards a carregar (padrão: 3) |
+| `--max-tokens=<n>` | Orçamento de tokens (padrão: 2000) |
+| `--print` | Exibe o conteúdo completo dos shards selecionados |
+| `--json` | Retorna shards e tokens em JSON |
+
+**Exemplos:**
+
+```bash
+# Ver quais seções do agente dev são relevantes para a tarefa
+aioson agent:load dev --goal="implementar endpoint de pagamento com TDD"
+
+# Exibir o conteúdo para usar diretamente no prompt
+aioson agent:load dev --goal="refatorar autenticação" --print
+
+# Carregar mais shards se necessário
+aioson agent:load dev --goal="..." --max-shards=5 --max-tokens=3000
+
+# JSON para integração em scripts
+aioson agent:load dev --goal="..." --json
+```
+
+**Saída:**
+
+```
+  Agent: dev  (3/8 shards, 420 tokens)
+
+  ## Role  (85 tokens)
+  ## Implementation Guidelines  (180 tokens)
+  ## Error Handling  (155 tokens)
+```
+
+---
+
+## Como funciona
+
+**Divisão em shards:**
+O arquivo de instruções é dividido por headings H2 (`##`) e H3 (`###`). Cada shard é uma seção com seu conteúdo. O bloco antes do primeiro heading vira o shard `(preamble)`.
+
+**Indexação:**
+Os shards são salvos como arquivos individuais em `~/.aioson/shards/` e indexados via FTS5 (o mesmo motor do `context:search`).
+
+**Seleção:**
+1. O shard `(preamble)` e os shards de `Role` são sempre incluídos
+2. O FTS5 busca os shards mais relevantes para o `--goal`
+3. Shards são adicionados até preencher o orçamento de tokens
+4. Se ainda há espaço, shards restantes são adicionados em ordem
+
+**Orçamento:**
+O total de tokens dos shards selecionados fica dentro de `--max-tokens` (padrão 2000, estimado como chars/4).
+
+---
+
+## Exemplo de redução de contexto
+
+Para um agente com 9 seções e 228 tokens totais:
+
+```
+Carregando para "implementar com TDD e error handling":
+  Shards selecionados: 3 de 9
+  Tokens usados: 73 de 228
+
+  → Redução de 68% no consumo de tokens
+```
+
+---
+
+## Onde ficam os índices
+
+Os shards são indexados em `~/.aioson/shards/` — fora do repositório, não commitado. Use `--force` para atualizar após editar os arquivos de agente.
+
+---
+
+## Quando usar
+
+- Quando um arquivo de instrução de agente tem muitas seções e você quer enviar ao LLM apenas o que é necessário para a tarefa atual
+- Para reduzir tokens consumidos por instruções fixas do agente
+- Para agentes que têm seções muito diferentes (implementação, revisão, documentação, deploy) e você quer carregar apenas o contexto certo para cada tarefa

package/docs/pt/agentes.md

@@ -125,6 +125,7 @@ O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los
 - métricas de sucesso
 - perguntas em aberto
 - identidade visual inicial, quando houver sinal suficiente
+- `## Specify depth` (projetos SMALL e MEDIUM) — classificação aplicada, profundidade de spec escolhida e lista de ambiguidades que devem ser resolvidas antes que `@analyst` avance
 
 > Se o pedido mencionar explicitamente um command center premium, control tower, tri-rail shell ou estilo AIOS Dashboard, o `@product` deve registrar a skill `premium-command-center-ui` na seção de identidade visual do PRD.
 
@@ -223,6 +224,10 @@ Alias compativel:
 - Riscos identificados
 - Referências visuais (wireframes, links)
 
+Em **modo feature**, entrega adicionalmente:
+- `requirements-{slug}.md` — regras de negócio com IDs rastreáveis (`REQ-{slug}-N`) e acceptance criteria verificáveis por QA (`AC-{slug}-N`)
+- `spec-{slug}.md` — esqueleto de memória da feature, com `phase_gates` no frontmatter para que `@dev` e `@deyvin` saibam quais fases já foram aprovadas
+
 ---
 
 ## @discovery-design-doc
@@ -290,8 +295,9 @@ tests/
 **Entrega:** Arquivo `.aioson/context/architecture.md` com:
 - Estrutura de pastas (proporcional ao tamanho)
 - Stack definitiva
-- Decisões técnicas documentadas
+- Decisões técnicas documentadas com **rationale** — não só o que foi decidido, mas por que aquela escolha reduz risco de debug e manutenção futura
 - Padrões de código
+- **Gate B** — sinal explícito de aprovação ao final do arquivo (`@dev` só pode iniciar implementação após este gate)
 
 ---
 
@@ -627,7 +633,7 @@ Se o usuário pedir para pular o teste, o `@dev` resiste, explica, e só cede ap
 ```
 
 **Entrega:**
-- PRD enriquecido in-place (Modo A)
+- PRD enriquecido in-place com sinal de **spec-hardened** ao final — o campo `readiness` em `sheldon-enrichment-{slug}.md` indica se o PRD está pronto para downstream (`ready_for_downstream`) ou ainda tem itens bloqueantes (`needs_work`) (Modo A)
 - Relatório de status de todos os PRDs (Modo B)
 - Checklist de validação + decisão go/no-go para implementação (Modo C)
 
@@ -660,6 +666,7 @@ Duração típica: dias a semanas. Análise completa, paralelismo, backlog forma
 
 ## Veja também
 
+- [Fluxo de artefatos entre agentes](./fluxo-artefatos.md) — o que cada agente produz, o que @dev lê de fato e como o plano do Sheldon chega à implementação
 - [Cenários completos com exemplos práticos](./cenarios.md)
 - [Início rápido](./inicio-rapido.md)
 - [Guia do engenheiro: pair programming com IA](./guia-engineer.md)