Spec — AI CLI/TUI Status and Recap Hooks

1. Princípios

1. Transparência de Estado: O operador deve saber imediatamente se o agente está trabalhando, esperando um processo em segundo plano ou aguardando comandos.
2. Rastreabilidade (Handoff): Cada encerramento de turno de IA deve deixar um rastro mecânico claro do trabalho realizado e da próxima ação recomendada.
3. Independência de Provedor: A mecânica de exibição no terminal e os ganchos do ciclo de vida são agnósticos e devem se aplicar igualmente a qualquer CLI de agente (Claude Code, Antigravity CLI, etc.).
4. Consumo Eficiente de Espaço: O rodapé da CLI deve se adaptar de forma compacta (2 ou 3 linhas), minimizando desperdício de tela em terminais estreitos.

2. A Convenção de Encerramento de Turno (Feito: / Próximo:)

Toda resposta do assistente de IA que devolva o controle para o operador humano (fechamento de turno) deve terminar obrigatoriamente com dois blocos destacados em negrito no corpo do chat:

• Feito: — Um resumo curto das ações realizadas no turno (commits, edições, correções).
• Próximo: — A sugestão clara da próxima tarefa imediata a ser feita.

**Feito:**
- Implementada a spec do KVIQ em specs/ai/kviq.kmd.
- Registrado o termo em vocabulary.md.

**Próximo:**
Refatorar o resolver de rotas do gateway para suportar estratégias KVIQ.

3. O Ciclo de Vida dos Ganchos (Hooks Interface)

O motor do CLI/TUI deve interceptar as transições de estado do agente através dos seguintes ganchos de ciclo de vida (hooks):

4. O Layout do Rodapé TUI/CLI (Status Line)

O rodapé do terminal deve renderizar uma área persistente (atualizada via timer de intervalo, ex: 1s) contendo 2 a 3 linhas formatadas em ANSI:

Linha 1: Contexto e Identidade

Exibe a localização do repositório/slug em foco, o usuário ativo e o consumo de créditos acumulado.

• Formato: <repo>/<component-slug> · <user> · <usage-summary>
• Exemplo: koder/kds · rodrigo · 5h: 0.12M tkn

Linha 2: LED de Status (Semáforo de Atividade)

Exibe uma bolinha colorida sinalizando o estado atual do processo:

• 🔵 Ciano (Steady - Trabalhando): O agente está processando a resposta ou executando uma ferramenta local.
• 🟡 Amarelo (Blinking - Aguardando): O agente concluiu sua vez de fala, mas há tarefas em segundo plano (builds, testes, compilações) ainda ativas no terminal do harness. A linha 3 exibe o comando ou label da tarefa.
• 🟢 Verde (Steady - Sua Vez): O agente está ocioso e sem nenhuma tarefa pendente em segundo plano, aguardando entrada humana.

Linha 3: Mini-descrição Dinâmica

Exibida apenas quando há contexto relevante para relatar, usando o prefixo ↳ em cinza (se vazia, o rodapé recolhe para 2 linhas):

• No estado Verde: Exibe o texto extraído da linha Próximo: para guiar o operador.
• No estado Amarelo: Exibe o label do koder-job ou o comando que está executando no background.
• No estado Ciano: Exibe a última ação realizada extraída dinamicamente do tail de logs (ex: $ go test ou editando layout.templ).

5. Histórico de Handoff (Recaps Log)

O gancho Stop deve alimentar um arquivo centralizado de auditoria em meta/context/handoff/recaps/YYYY-MM.md. Cada fechamento de turno anexa uma entrada formatada contendo:

1. Timestamp (RFC3339).
2. Session ID (identificador único da sessão).
3. Git Branch e último commit durável na árvore.
4. Worktree (lista curta de arquivos modificados).
5. Next Action (o valor extraído do rótulo Próximo:).