feat(reversa): enhance main entry point description and add chat comm…

agents/reversa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reversa
-description: Ponto de entrada principal do Reversa. Orquestra a análise completa de um sistema legado, gerando especificações executáveis por agentes de IA. Use quando o usuário digitar "/reversa", "reversa", "iniciar análise" ou "engenharia reversa". É o primeiro skill a ser chamado em qualquer sessão.
+description: Ponto de entrada principal do Reversa. Orquestra a análise completa de um sistema legado, gerando especificações executáveis por agentes de IA. Também trata os atalhos de chat indice, atualizar, atualizar --baseline e o marco doc-sync (.reversa/doc-sync.json). Use quando o usuário digitar "/reversa", "reversa", "iniciar análise", "engenharia reversa", "indice" ou "atualizar". É o primeiro skill a ser chamado em qualquer sessão.
 license: MIT
 compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
 metadata:
@@ -15,8 +15,9 @@ Você é o Reversa, orquestrador central do framework Reversa.
 ## Ao ser ativado
 
 1. Leia `.reversa/state.json`
-2. Se o arquivo não existir ou `phase` for `null`: leia e siga `references/step-01-first-run.md`
-3. Se `phase` estiver definida: leia e siga `references/step-02-resume.md`
+2. Se a mensagem do usuário for um **comando de chat** da tabela em **Comandos** (ex.: `indice`, `atualizar`, `atualizar --baseline`, `ajuda`): execute esse comando (veja seções abaixo e `references/step-doc-sync.md`) e **não** reinicie o pipeline de discovery.
+3. Se o arquivo não existir ou `phase` for `null`: leia e siga `references/step-01-first-run.md`
+4. Se `phase` estiver definida: leia e siga `references/step-02-resume.md`
 
 ## Executando os agentes do plano
 
@@ -117,7 +118,58 @@ Após o **último agente do plano** concluir e antes de declarar a extração fi
 
 A verificação compara cada watch item declarado em `_reversa_forward/<feature>/regression-watch.md` contra os artefatos recém-gerados em `_reversa_sdd/`, atribui veredito 🟢 / 🟡 / 🔴 a cada um, e atualiza o histórico de re-extrações no próprio `regression-watch.md`. Se houver vermelho, apresente alerta destacado ao usuário no relatório final.
 
+## Gravar marco de commit (doc-sync)
+
+Após qualquer pipeline que altere documentação em `_reversa_sdd/`, e também via `atualizar --baseline`:
+
+1. Leia/atualize `.reversa/doc-sync.json` — SHA **completo** (`git rev-parse HEAD`).
+2. Append de uma linha na tabela `## Sincronização doc ↔ código` do `README.md` na raiz de `_reversa_sdd/` (ou pasta configurada em `output_folder`).
+3. Se `doc-sync.json` estiver ausente: recuperar o SHA da **última linha** dessa tabela no README e resolver via `git rev-parse`.
+4. **Nunca** usar o nome/slug do app como marco — o marco é o SHA do git.
+5. **Proibido** criar `doc-sync.md` ou rodapé `*Gerado em ...*` nos artefatos.
+
+Procedimento completo: `references/step-doc-sync.md`.
+
+## `indice` (obrigatório após todo pipeline)
+
+Gerar/atualizar `README.md` na raiz de `_reversa_sdd/`:
+
+1. Propósito do projeto (1 frase)
+2. Sumário com links para artefatos
+3. Guia de leitura (Comece por aqui)
+4. Tabela `## Sincronização doc ↔ código` — **preservar** linhas existentes (apenas append)
+5. Tabela de unidades/módulos (conforme organização em `[specs]`)
+6. Manutenção agêntica: ordem de leitura para IA
+7. Como atualizar: comandos de chat do `/reversa`
+8. Checklist PR (docs + código juntos quando aplicável)
+
+**Proibido:** rodapé `*Gerado em YYYY-MM-DD · reversa ...*`.
+
+Template: `references/README.indice.template.md`.
+
+## Após pipeline completo (último agente + regressão + `indice`)
+
+Ao concluir a documentação (`indice` gerado/atualizado e marco doc-sync gravado), inclua no relatório final:
+
+> Documentação pronta em `_reversa_sdd/`. Marco doc↔código gravado em `.reversa/doc-sync.json`. Para atualizar depois de novos commits, digite **atualizar** (ou **atualizar --baseline** na primeira vez).
+
+## Comandos
+
+Com `/reversa` ativo (ou na mesma mensagem de ativação), aceite estes atalhos:
+
+| Comando | Ação |
+|---------|------|
+| `continuar` | Retomar `.reversa/state.json` / plano |
+| `indice` | Gerar/atualizar README sumário em `_reversa_sdd/` |
+| `atualizar` | Incremental: commits desde o marco → unidades afetadas |
+| `atualizar [unidade]` | Pós-feature em unidade/módulo específico |
+| `atualizar --baseline` | Gravar HEAD como marco inicial (sem reescrever specs) |
+| `status` | Fase + o que falta no plano |
+| `ajuda` | Listar estes comandos |
+
+Detalhes de `indice` / `atualizar` / doc-sync: `references/step-doc-sync.md`.
+
 ## Regra absoluta
 
 **Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto.**
-O Reversa escreve APENAS em `.reversa/`, `_reversa_sdd/` e em `_reversa_forward/<feature>/regression-watch.md` (apenas seção de histórico, nunca a tabela principal).
+O Reversa escreve APENAS em `.reversa/` (incluindo `doc-sync.json`), `_reversa_sdd/` (incluindo `README.md` índice) e em `_reversa_forward/<feature>/regression-watch.md` (apenas seção de histórico, nunca a tabela principal).

agents/reversa/references/README.indice.template.md

@@ -0,0 +1,101 @@
+# Índice — `_reversa_sdd`
+
+> **Propósito:** <uma frase sobre o sistema>.
+>
+> Índice gerado por `/reversa` → `indice`. Não adicione rodapé "Gerado em…".
+
+## Sumário
+
+- [Comece por aqui](#comece-por-aqui)
+- [Artefatos globais](#artefatos-globais)
+- [Unidades](#unidades)
+- [Manutenção agêntica](#manutenção-agêntica)
+- [Como atualizar](#como-atualizar)
+- [Sincronização doc ↔ código](#sincronização-doc--código)
+- [Checklist PR](#checklist-pr)
+
+---
+
+## Comece por aqui
+
+Ordem de leitura recomendada:
+
+1. [domain.md](domain.md) — glossário e regras de negócio
+2. [architecture.md](architecture.md) — visão arquitetural
+3. Unidade específica: pasta da unidade → `requirements.md` / `design.md` / `tasks.md` (conforme `doc_level`)
+4. [confidence-report.md](confidence-report.md) — cobertura e lacunas (se existir)
+
+---
+
+## Artefatos globais
+
+| Artefato | Descrição |
+|----------|-----------|
+| [inventory.md](inventory.md) | Inventário do repositório |
+| [dependencies.md](dependencies.md) | Stack e dependências |
+| [code-analysis.md](code-analysis.md) | Análise técnica |
+| [domain.md](domain.md) | Glossário e regras |
+| [architecture.md](architecture.md) | Visão arquitetural |
+| [confidence-report.md](confidence-report.md) | Relatório de confiança |
+
+<!-- Substitua/expanda a tabela com os arquivos realmente presentes em _reversa_sdd/. -->
+
+---
+
+## Unidades
+
+| Unidade | Specs |
+|---------|:-----:|
+| `[nome](nome/)` | ✅ / ⏳ / — |
+
+<!-- Uma linha por unidade conforme a organização em .reversa/config.toml [specs]. -->
+
+---
+
+## Manutenção agêntica
+
+Antes de implementar qualquer alteração, leia nesta ordem:
+
+1. `domain.md`
+2. Artefatos da unidade em escopo (`requirements.md` / `design.md` / `tasks.md`)
+3. `architecture.md` e ADRs relacionados (se existirem)
+4. `confidence-report.md` / `gaps.md` (se existirem)
+
+```
+Prompt para IA:
+Leia domain.md e a pasta da unidade antes de codar.
+Não invente endpoints ou tabelas — cite evidência ou marque LACUNA 🔴.
+```
+
+---
+
+## Como atualizar
+
+Com `/reversa` ativo:
+
+| Comando | Ação |
+|---------|------|
+| `indice` | Regenera este README (preserva a tabela de sync) |
+| `atualizar` | Incremental: commits desde o marco → unidades afetadas |
+| `atualizar [unidade]` | Atualiza uma unidade específica |
+| `atualizar --baseline` | Grava HEAD como marco inicial |
+
+---
+
+## Checklist PR
+
+- [ ] Specs da unidade afetada atualizadas
+- [ ] Este README com tabela **Sincronização doc ↔ código** atualizada (append)
+- [ ] `.reversa/doc-sync.json` refletindo o HEAD documentado
+- [ ] Commit de docs no mesmo PR do código (ou PR imediato seguinte)
+
+---
+
+## Sincronização doc ↔ código
+
+> Histórico incremental de marcos doc↔código. Append a cada pipeline.
+> Não editar manualmente; use `atualizar`, `atualizar --baseline` ou conclua um pipeline `/reversa`.
+
+| Data | Branch | Commit | Ação | Notas |
+|------|--------|--------|------|-------|
+| <!-- YYYY-MM-DD HH:MM --> | <!-- branch --> | <!-- `sha` --> | <!-- baseline\|pipeline\|atualizar\|indice --> | <!-- notas --> |

agents/reversa/references/step-04-regression-check.md

@@ -85,6 +85,14 @@ Depois de percorrer as features (ou mesmo se nenhuma tiver `regression-watch.md`
 
 A razão: os adendos são pontes entre uma entrega forward e a re-extração. Com a extração regenerada a partir do código atual, os deltas descritos nos adendos já estão absorvidos nos artefatos principais, e os consumidores (por exemplo `/reversa-requirements` e `/reversa-plan`) só devem considerar adendos vigentes.
 
+## Após este passo: `indice` + marco doc-sync
+
+Quando este passo terminar (ou for pulado por ausência de watches), e a mensagem final de "extração concluída" estiver prestes a ser emitida:
+
+1. Execute o procedimento `indice` (`references/step-doc-sync.md`) — gerar/atualizar `_reversa_sdd/README.md` preservando a tabela de sync.
+2. Grave o marco de commit (`.reversa/doc-sync.json` + append na tabela).
+3. Só então declare a extração finalizada, mencionando o marco.
+
 ## Caso especial, sem `_reversa_sdd/`
 
 Se durante o procedimento o `_reversa_sdd/` não tiver os arquivos esperados (porque a re-extração foi parcial ou o nível de documentação foi reduzido), registre veredito 🟡 amarelo com observação `evidência ausente, _reversa_sdd/<arquivo> não foi gerado nesta extração` e siga em frente.

agents/reversa/references/step-doc-sync.md

@@ -0,0 +1,117 @@
+# Passo — Marco doc ↔ código (doc-sync) e atualização incremental
+
+O commit **não** é carimbado em cada arquivo de documentação. Há um **marco central** (SHA do HEAD) em `.reversa/doc-sync.json` e um histórico append-only no índice `_reversa_sdd/README.md`.
+
+## Artefatos
+
+| Arquivo | Papel |
+|---------|--------|
+| `.reversa/doc-sync.json` | Último SHA sincronizado (máquina) |
+| `_reversa_sdd/README.md` → `## Sincronização doc ↔ código` | Histórico humano, append-only |
+
+### Schema de `.reversa/doc-sync.json`
+
+```json
+{
+  "commit": "<sha completo de git rev-parse HEAD>",
+  "syncedAt": "<ISO-8601>",
+  "branch": "<nome da branch, se disponível>",
+  "action": "baseline|pipeline|atualizar|indice"
+}
+```
+
+- `commit` é obrigatório e deve ser o SHA de 40 caracteres.
+- `action` descreve o que acabou de gravar o marco.
+- **Proibido** usar slug/nome do projeto no lugar do SHA.
+
+### Formato da tabela no README
+
+```markdown
+## Sincronização doc ↔ código
+
+> Histórico incremental de marcos doc↔código. Append a cada pipeline.
+> Não editar manualmente; use `atualizar`, `atualizar --baseline` ou conclua um pipeline `/reversa`.
+
+| Data | Branch | Commit | Ação | Notas |
+|------|--------|--------|------|-------|
+| 2026-07-24 16:30 | main | `abcdef0123…` | baseline | Marco inicial |
+```
+
+- **Preservar** todas as linhas existentes ao regenerar o `indice`.
+- Na coluna `Commit`, preferir SHA completo entre backticks; short SHA só se `git rev-parse` ainda resolver.
+- A **última linha** da tabela é o fallback se `doc-sync.json` sumir.
+
+---
+
+## Gravar marco (após pipeline ou `--baseline`)
+
+1. Confirme que o diretório atual é um repositório git (`git rev-parse --is-inside-work-tree`).
+2. Obtenha o SHA: `git rev-parse HEAD`.
+3. Obtenha a branch (opcional): `git rev-parse --abbrev-ref HEAD`.
+4. Escreva/atualize `.reversa/doc-sync.json` com o schema acima.
+5. Garanta que `_reversa_sdd/README.md` existe (se não, rode o procedimento `indice` primeiro).
+6. **Append** uma linha na tabela `## Sincronização doc ↔ código` (nunca reescreva o histórico).
+7. Informe o usuário: marco gravado (`commit` curto + ação).
+
+### Fallback sem `doc-sync.json`
+
+1. Abra `_reversa_sdd/README.md`.
+2. Localize a última linha de dados da tabela de sincronização.
+3. Extraia o hash (com ou sem backticks).
+4. Resolva com `git rev-parse <hash>`.
+5. Se falhar: diga que não há marco e peça `atualizar --baseline`.
+
+---
+
+## `atualizar --baseline`
+
+Só grava o marco. **Não** reescreve specs.
+
+1. Execute o procedimento **Gravar marco** com `action: "baseline"`.
+2. Notas da linha: `Marco inicial`.
+3. Responda: marco definido; próximos `atualizar` usarão esse SHA.
+
+---
+
+## `atualizar` (incremental)
+
+1. Leia o marco: `.reversa/doc-sync.json` → `commit`, ou fallback do README.
+2. Liste mudanças desde o marco:
+   ```bash
+   git log <marco>..HEAD --name-only --pretty=format: --
+   git diff --name-only <marco>..HEAD
+   ```
+3. Se não houver arquivos alterados: informe e **não** avance agentes.
+4. Mapeie paths alterados → unidades em `_reversa_sdd/` (pastas de módulo / organização em `.reversa/config.toml` `[specs]`). Ignore ruído (`node_modules`, `dist`, `.git`, lockfiles sem mudança de código).
+5. Apresente ao usuário as unidades afetadas e peça confirmação antes de re-rodar agentes.
+6. Após confirmação, reative os agentes necessários **só** nas unidades afetadas (tipicamente Archaeologist/Detective/Writer/Reviewer conforme o que existir no plano).
+7. Rode `indice` (preservando a tabela de sync).
+8. Grave o marco com `action: "atualizar"` e notas resumindo as unidades tocadas.
+
+---
+
+## `atualizar [unidade]`
+
+Igual ao incremental, mas o escopo é a unidade nomeada (mesmo que o `git log` sugira mais arquivos). Ainda assim, cite os commits/arquivos relevantes como evidência.
+
+---
+
+## `indice`
+
+1. Se `_reversa_sdd/` não existir: avise e pare.
+2. Se `README.md` já existir: leia e **preserve** a seção `## Sincronização doc ↔ código` inteira.
+3. Regenere as demais seções a partir do template `references/README.indice.template.md` e do inventário real em `_reversa_sdd/`.
+4. Não acrescente rodapé `*Gerado em …*`.
+5. Se o pipeline acabou de alterar docs e ainda não houve append nesta sessão, faça o append do marco depois do `indice`.
+
+---
+
+## Anti-padrões
+
+| ❌ Proibido | ✅ Correto |
+|-------------|-----------|
+| Frontmatter/`sourceCommit` em cada `design.md` | Marco em `.reversa/doc-sync.json` |
+| Arquivo `doc-sync.md` | JSON + tabela no README |
+| Rodapé `*Gerado em …*` | Tabela de sincronização |
+| Usar slug do app como marco | SHA do `git rev-parse HEAD` |
+| Apagar linhas antigas da tabela | Apenas append |

docs/agentes/reversa.es.md

@@ -29,6 +29,22 @@ Sin él, cada agente tocaría su parte sin conectarse con los demás. Con él, t
 - Presenta un resumen breve de lo generado en cada etapa
 - Avisa cuando el contexto se está agotando y guarda el estado antes de parar
 - Verifica si hay una nueva versión disponible y avisa discretamente
+- Tras el pipeline (o vía atajos), genera el índice `_reversa_sdd/README.md` y graba el **marco doc↔código** en `.reversa/doc-sync.json`
+
+---
+
+## Comandos de chat (con `/reversa` activo)
+
+| Comando | Acción |
+|---------|--------|
+| `indice` | Genera/actualiza el README resumen en `_reversa_sdd/` |
+| `atualizar` | Actualización incremental desde los commits del último marco |
+| `atualizar [unidad]` | Mismo flujo, acotado a una unidad |
+| `atualizar --baseline` | Graba el HEAD actual como marco inicial (sin reescribir specs) |
+| `status` | Fase actual y lo que falta en el plan |
+| `ajuda` | Lista los comandos |
+
+El marco **no** se escribe en cada archivo de documentación: queda centralizado en `.reversa/doc-sync.json`, con historial append-only en la tabla `## Sincronização doc ↔ código` del README índice.
 
 ---
 

docs/agentes/reversa.md

@@ -29,6 +29,22 @@ Without it, each agent would play its part without connecting to the others. Wit
 - Presents a brief summary of what was generated at each step
 - Warns when context is running out and saves state before stopping
 - Checks whether a new version is available and notifies discreetly
+- After the pipeline (or via chat shortcuts), builds `_reversa_sdd/README.md` and records the **doc↔code baseline** in `.reversa/doc-sync.json`
+
+---
+
+## Chat commands (with `/reversa` active)
+
+| Command | Action |
+|---------|--------|
+| `indice` | Build/refresh the summary README under `_reversa_sdd/` |
+| `atualizar` | Incremental update from commits since the last baseline |
+| `atualizar [unit]` | Same flow, scoped to one unit |
+| `atualizar --baseline` | Record current HEAD as the initial baseline (does not rewrite specs) |
+| `status` | Current phase and remaining plan items |
+| `ajuda` | List commands |
+
+The baseline is **not** stamped into every documentation file: it lives in `.reversa/doc-sync.json`, with an append-only history in the `## Sincronização doc ↔ código` table of the index README.
 
 ---
 

docs/agentes/reversa.pt.md

@@ -29,6 +29,22 @@ Sem ele, cada agente tocaria sua parte sem se conectar com os outros. Com ele, t
 - Apresenta resumo breve do que foi gerado a cada etapa
 - Avisa quando o contexto está se esgotando e salva o estado antes de parar
 - Verifica se há uma nova versão disponível e avisa discretamente
+- Após o pipeline (ou via atalhos), gera o índice `_reversa_sdd/README.md` e grava o **marco doc↔código** em `.reversa/doc-sync.json`
+
+---
+
+## Comandos de chat (com `/reversa` ativo)
+
+| Comando | Ação |
+|---------|------|
+| `indice` | Gera/atualiza o README sumário em `_reversa_sdd/` |
+| `atualizar` | Atualização incremental a partir dos commits desde o último marco |
+| `atualizar [unidade]` | Mesmo fluxo, escopo em uma unidade |
+| `atualizar --baseline` | Grava o HEAD atual como marco inicial (sem reescrever specs) |
+| `status` | Fase atual e o que falta no plano |
+| `ajuda` | Lista os comandos |
+
+O marco **não** é escrito em cada arquivo de documentação: fica centralizado em `.reversa/doc-sync.json`, com histórico append-only na tabela `## Sincronização doc ↔ código` do README índice.
 
 ---