@esquadrao/cli 0.0.0-stage → 1.6.0

package/skill-media-producer/references/corte-podcast-3-niveis.md

@@ -0,0 +1,179 @@
+# Prova de Corte de Podcast em 3 Níveis
+
+> **Status:** procedimento validado em 2026-11-11 com o CLI 1.5.0. A skill **consegue** detectar pausas longas e respiros curtos, cortar, remapear legendas, renderizar e medir. A composição visual de comparação (três painéis + timelines) é feita **fora** da skill, com FFmpeg/Python.
+
+Este documento descreve o teste que mostra, na prática, a diferença entre:
+
+1. **Pausa longa:** silêncio de 1,2–1,5 s entre blocos de fala.
+2. **Respiro curto:** pausa de 0,35–0,45 s entre frases.
+3. **Controle:** o mesmo vídeo cortado em três níveis, sem refazer a gravação.
+
+---
+
+## 1. O que a skill faz e o que não faz
+
+| Etapa | A skill faz? | Comando / observação |
+| :--- | :--- | :--- |
+| Detectar pausas e respiros | **Sim** | `esquadrao studio detect-silence <video> --silence-duration <s>` |
+| Cortar pausas longas | **Sim** | `auto-clip` com `--silence-duration 0.8` (padrão) |
+| Cortar respiros curtos | **Sim** | `auto-clip` com `--silence-duration 0.35` |
+| Remapear legendas após o corte | **Sim** | `--captions <arquivo.srt>` |
+| Renderizar e validar QA | **Sim** | `auto-clip` gera MP4 e roda `qa` |
+| Reportar métricas | **Sim** | JSON com `silences_detected`, `silence_cut_s`, `speech_clips_count`, `captions_count`, `qa` |
+| Montar o comparativo de 3 painéis | **Não** | Composição externa com FFmpeg (`xstack`/`hstack`) e timelines |
+| Gerar timeline visual verde/vermelho | **Não** | Script Python/PIL ou SVG externo |
+
+**Conclusão:** o corte e a medição são 100% da skill; a peça de marketing é uma composição posterior.
+
+---
+
+## 2. Fixture de validação
+
+Para o teste ser determinístico, use uma gravação limpa, sem ruído de fundo:
+
+- **8 frases** de 2–3 s cada.
+- **4 pausas longas** de 1,5 s entre blocos.
+- **3 respiros curtos** de 0,40 s entre frases.
+- Áudio final com ~28 s.
+- Legenda SRT com os tempos de cada frase.
+- Vídeo vertical 1080×1920 com cena de apoio contínua (a cena não interfere no corte).
+
+Padrão dos intervalos:
+
+```text
+frase 1 [1,5 s] frase 2 [0,4 s] frase 3 [1,5 s] frase 4
+frase 4 [0,4 s] frase 5 [1,5 s] frase 6 [0,4 s] frase 7
+frase 7 [1,5 s] frase 8
+```
+
+> **Dica:** se usar TTS, corte o silêncio residual do início e do fim de cada arquivo antes de concatenar. Caso contrário, o arredondamento do encoder pode transformar um respiro de 0,40 s em 0,80 s e ele será cortado já no nível padrão.
+
+---
+
+## 3. Passo a passo
+
+### Passo 1 — Montar o bruto
+
+1. Gere ou grave as 8 frases separadas.
+2. Remova o silêncio residual de cada frase:
+
+```bash
+ffmpeg -i frase.mp3 \
+  -af "silenceremove=start_periods=1:start_duration=0:start_threshold=-45dB,areverse,silenceremove=start_periods=1:start_duration=0:start_threshold=-45dB,areverse" \
+  -c:a aac frase-limpa.m4a
+```
+
+3. Concatene na ordem do padrão acima, inserindo os intervalos de 1,5 s e 0,40 s.
+4. Monte o vídeo vertical com a cena de apoio e o áudio concatenado.
+5. Crie o `raw.srt` com os tempos de cada frase.
+
+### Passo 2 — Verificar o que será detectado
+
+Rode a detecção nos dois níveis antes de renderizar:
+
+```bash
+esquadrao studio detect-silence raw.mp4 --silence-duration 0.8 --json
+esquadrao studio detect-silence raw.mp4 --silence-duration 0.35 --json
+```
+
+**Esperado no fixture de referência:**
+
+| Nível | `--silence-duration` | Silêncios detectados | Clipes de fala |
+| :--- | ---: | ---: | ---: |
+| Padrão | `0.8` | 4 (apenas pausas longas) | 5 |
+| Respiro | `0.35` | 7 (4 longas + 3 curtas) | 8 |
+
+Se o nível de 0,35 detectar muito mais que 7, há ruído ou pausas naturais da locução sendo tratadas como respiro. Ajuste para `0.40` ou `0.45`.
+
+### Passo 3 — Rodar os três níveis
+
+O nível “original” é o próprio `raw.mp4`, sem corte. Os outros dois usam o mesmo arquivo e a mesma legenda:
+
+```bash
+# Padrão: remove pausas longas, preserva respiros
+esquadrao studio auto-clip raw.mp4 \
+  --captions raw.srt \
+  --silence-duration 0.8 \
+  --dest workspace-padrao --json
+
+# Respiro: remove pausas longas e respiros curtos
+esquadrao studio auto-clip raw.mp4 \
+  --captions raw.srt \
+  --silence-duration 0.35 \
+  --dest workspace-respiro --json
+```
+
+Cada execução devolve um JSON com os campos usados na comparação:
+
+```json
+{
+  "status": "ok",
+  "silences_detected": 7,
+  "silence_cut_s": 7.339,
+  "speech_clips_count": 8,
+  "captions_count": 17,
+  "qa": { "passed": true, "duration_s": 21.1 }
+}
+```
+
+### Passo 4 — Validar os números
+
+Critérios de aceite:
+
+- [ ] O nível padrão tem menos silêncios que o nível respiro.
+- [ ] O nível respiro tem duração menor que o nível padrão.
+- [ ] Os dois MP4s passam no QA (`qa.passed = true`).
+- [ ] As legendas continuam sincronizadas e sem corte nas duas saídas.
+- [ ] O nível respiro não remove fala: compare os `speech_clips_count` e ouça as junções.
+
+### Passo 5 — Montar o comparativo (fora da skill)
+
+A skill entrega três MP4s verticais. A peça de LP é montada depois:
+
+1. Três painéis verticais de 360×640, centralizados em um canvas 1920×1080.
+2. Rótulos: `Original`, `Corte padrão 0,8 s`, `Corte de respiro 0,35 s`.
+3. Abaixo de cada painel, uma timeline:
+   - verde = fala;
+   - vermelho = trecho removido;
+   - marcações nas pausas longas e nos respiros.
+4. Métricas reais extraídas do JSON:
+   - `8 pausas • 14,2 s removidos • 27% mais curto` (exemplo).
+5. Sem áudio no comparativo; é uma peça visual em loop.
+
+Composição de referência:
+
+```bash
+ffmpeg -i original.mp4 -i padrao.mp4 -i respiro.mp4 \
+  -filter_complex "\
+    [0:v]scale=360:640,setsar=1[a];\
+    [1:v]scale=360:640,setsar=1[b];\
+    [2:v]scale=360:640,setsar=1[c];\
+    [a][b][c]hstack=inputs=3[out]" \
+  -map "[out]" -an -c:v libx264 -pix_fmt yuv420p comparativo.mp4
+```
+
+> A timeline verde/vermelha não é gerada pelo `auto-clip`; use o JSON de `detect-silence` para desenhar os blocos.
+
+---
+
+## 4. Resultado da validação (2026-11-11)
+
+Fixture de referência: 28,4 s de vídeo, 8 frases, 4 pausas de 1,5 s e 3 respiros de 0,40 s.
+
+| Nível | `--silence-duration` | Silêncios | Clipes de fala | Duração final | QA |
+| :--- | ---: | ---: | ---: | ---: | :--- |
+| Original | — | — | 1 | 28,4 s | — |
+| Padrão | `0.8` | 4 | 5 | 22,3 s | aprovado |
+| Respiro | `0.35` | 7 | 8 | 21,1 s | aprovado |
+
+**Leitura:** o nível padrão removeu 6,07 s (4 pausas longas); o nível respiro removeu 7,34 s (as 4 longas + 3 curtas). A diferença de 1,27 s é exatamente o conjunto de respiros, sem perda de fala.
+
+---
+
+## 5. Limites e recomendações
+
+- **0,35 s é agressivo.** Use apenas em áudio limpo, sem ruído e com locução pausada. Para podcast com respiração audível ou ambiente, comece em `0.45` ou `0.5`.
+- **Ruído de fundo impede o `silencedetect`.** Normalize ou aplique redução de ruído antes; caso contrário, o silêncio “real” pode não cruzar o limiar de `-30dB`.
+- **TTS tem silêncio residual.** Sem o corte de bordas, o respiro de 0,40 s pode virar 0,8 s e ser removido no nível padrão.
+- **O comparativo não é um comando da skill.** Se virar item de produto, entra como backlog próprio; hoje é composição externa.
+- **Sempre ouça as junções.** Métrica verde não substitui a checagem auditiva de respiração cortada no meio da palavra.

package/skill-media-producer/references/llm-agent-guide.md

@@ -0,0 +1,231 @@
+# Guia Operacional para LLMs e Agentes de IA — Esquadrão de Conteúdo Studio
+
+Este guia estabelece o padrão de comportamento, diálogo e orquestração para assistentes inteligentes (Claude Code, Cursor, Codex CLI, Grok Build e Hermes) ao interagir com usuários na produção de vídeos automatizados.
+
+---
+
+## 1. Regra de Ouro: Soberania da Decisão do Usuário
+
+O assistente de IA **nunca** deve impor uma configuração padrão arbitrária:
+- **Não force formato widescreen (16:9):** Mais de 80% do consumo atual de cortes ocorre em formato vertical (9:16). Sempre pergunte a intenção do usuário.
+- **Não force fundo preto (`dark`):** O modo `dark` é voltado para testes ou canais puramente tipográficos. A maioria dos usuários deseja cortar vídeos longos com legendas (`podcast_clip`) ou unir cenas de apoio e filmagens (`edit_only`).
+
+---
+
+## 2. Roteiro de Interação com o Usuário
+
+Ao ser acionado pelo usuário com comandos como *"quero criar um corte"*, *"edite este vídeo"* ou *"configure o estúdio de vídeo"*, siga este fluxo:
+
+### Fase 1: Sondagem e Descoberta
+Envie uma mensagem amigável e direta coletando as decisões essenciais:
+> *"Vou preparar a esteira de edição para você. Para deixar o vídeo no ponto certo, me diga:*
+> *1. **Formato:** Você quer em formato **vertical 9:16** (Reels, TikTok, Shorts) ou **widescreen 16:9** (YouTube tradicional)?*
+> *2. **Estilo:** Você quer **fatiar uma gravação com legendas** sincronizadas, **unir trechos de vídeo** ou prefere **texto sobre fundo escuro**?*
+> *3. Qual é o arquivo de vídeo que vamos usar de fonte?"*
+
+### Fase 2: Checagem de Ambiente
+Antes de criar arquivos, verifique se a máquina possui os requisitos operacionais:
+```bash
+node -v
+ffmpeg -version
+ffprobe -version
+```
+Se o FFmpeg não for encontrado, responda com o comando de instalação imediato:
+- **Windows:** `winget install Gyan.FFmpeg`
+- **macOS:** `brew install ffmpeg`
+- **Linux:** `sudo apt update && sudo apt install -y ffmpeg`
+
+### Fase 3: Preparação do Workspace
+Execute no terminal:
+```bash
+# 1. Instalar o CLI globalmente se ainda não estiver presente
+npm install -g @esquadrao/cli
+
+# 2. Configurar o workspace atual
+esquadrao setup
+
+# 3. Inicializar o estúdio
+esquadrao studio init --dest ./workspace
+```
+
+A inicialização cria a seguinte árvore real no workspace:
+```text
+workspace/
+├── assets/       # Cópias locais das mídias importadas
+├── packages/     # EditPlans (editplan.json), transcrições e ganchos
+├── artifacts/    # Vídeos finais em MP4 gerados pelo renderizador
+└── studio.json   # Manifesto do estúdio e inventário de assets
+```
+*(Nota: O estúdio cria estritamente `assets/`, `packages/`, `artifacts/` e `studio.json`. Pastas como `editplans/`, `renders/` e `qa/` não são geradas.)*
+
+> **Onboarding:** No modo `podcast_clip`, o `esquadrao onboard` executa o pipeline real de `auto-clip` e aceita `--captions`, `--openai`, `--local` ou `--no-captions`. Sem motor de legenda, ele aplica `--no-captions`, gera o corte real sem legendas e avisa; nunca prometa legendas sem informar o pré-requisito.
+
+### Fase 4: Importação da Mídia e Leitura dos Metadados
+Importe o arquivo do usuário e anote o ID do asset:
+```bash
+esquadrao studio import /caminho/do/video.mp4 --dest ./workspace --json
+```
+A resposta retorna:
+```json
+{
+  "id": "AST-A1B2C3D4",
+  "metadata": {
+    "duration_s": 45.2,
+    "width": 1920,
+    "height": 1080,
+    "has_audio": true
+  }
+}
+```
+
+### Fase 5: Montagem do EditPlan
+Com base nas escolhas do usuário, crie `./workspace/packages/editplan.json`.
+- Para formato vertical: `width: 1080`, `height: 1920`.
+- Para formato widescreen: `width: 1920`, `height: 1080`.
+- Ajuste os pontos de corte (`in_ms`, `out_ms`) garantindo que `out_ms <= duration_s * 1000`.
+
+**Apresente um resumo claro para o usuário antes de renderizar:**
+> *"Preparei o plano de corte:*
+> *- Formato: Vertical 9:16 (1080x1920)*
+> *- Trecho: 00:05 a 00:35 (30 segundos)*
+> *- Legendas: 3 frases sincronizadas com áudio nivelado*
+> *Posso iniciar a renderização no seu computador?"*
+
+### Fase 6: Renderização e QA
+Após a confirmação:
+```bash
+esquadrao studio render ./workspace/packages/editplan.json --dest ./workspace --json
+esquadrao studio qa ./workspace/artifacts/video.mp4 --plan ./workspace/packages/editplan.json
+```
+Entregue o caminho do vídeo final gerado e confirme que a checagem técnica passou com sucesso.
+
+### Fase Alternativa Rápida: Pipeline Integrado de Auto-Corte (`auto-clip`)
+Quando o usuário deseja fatiar pausas mortas a partir de um vídeo longo sem montar o `editplan.json` manualmente:
+```bash
+# Executa corte de silêncios (>0.8s), montagem de cortes contíguos e renderização com QA:
+esquadrao studio auto-clip /caminho/do/video.mp4 --dest ./workspace --json
+```
+O comando emite o resumo com total de silêncio expurgado, quantidade de cortes contíguos e o artefato renderizado aprovado.
+
+> **REGRA MANDATÓRIA PARA A LLM — NÃO PROMETER LEGENDA AUTOMÁTICA SEM PRÉ-REQUISITO:**
+> O assistente de IA NÃO deve prometer ao usuário legendas automáticas sem explicitar os três caminhos suportados:
+> 1. `--captions <arquivo.srt>`: Caminho canônico, offline e determinístico (recomendado).
+> 2. `--openai`: Requer a variável de ambiente `OPENAI_API_KEY` para transcrição via API remota OpenAI Whisper.
+> 3. `--local`: Utiliza `@xenova/transformers` + `Xenova/whisper-tiny` (declarada em `optionalDependencies`). Se o pacote opcional não estiver instalado, o comando falha com instrução acionável; use `--no-captions` para cortar sem legendas.
+> O agente deve sempre solicitar um arquivo SRT, instruir a configuração de `OPENAI_API_KEY` ou instalar o modelo local antes de prometer legendas no corte.
+>
+> **Templates de legenda:** existem nove presets documentados em [`caption-templates.md`](caption-templates.md), disponíveis via `--caption-template <id>` ou `captions[].template`. `--caption-style impact|word|full` permanece como legado.
+
+---
+
+## 3. Matriz de Tratamento de Erros Comuns
+
+| Erro Observado | Causa Raiz | Ação Corretiva Determinística |
+| :--- | :--- | :--- |
+| `ffmpeg is not installed` | Binário ausente no PATH | Orientar instalação via `winget`, `brew` ou `apt` e reabrir terminal. |
+| `out_ms exceeds asset duration` | Ponto de saída além do arquivo | Obter duração real com `studio import` e recalcular `out_ms`. |
+| `Missing audio stream in artifact` | Fonte sem áudio ou falha de mix | Garantir `anullsrc` para vídeo mudo ou verificar se o arquivo original tem áudio. |
+| `Caption special characters error` | Caracteres `%` ou `'` na legenda | O motor trata com `\%` e `\'`. Não usar tags HTML em legendas. |
+| `QA duration mismatch > 250ms` | Cortes inconsistentes com a timeline | Alinhar `timeline_start_ms` com o somatório dos cortes anteriores. |
+
+
+---
+
+## 4. Playbook Avançado: Corte de Vídeo Longo, Copy Viral, B-Rolls e Música
+
+Quando o usuário fornecer uma gravação longa (podcast, aula, live ou entrevista de 30min a 2h), siga este roteiro de 5 passos para entregar um corte viral de alto nível:
+
+### Passo 1: Transcrição Estruturada
+Extraia o mapa textual completo com marcações de tempo:
+```bash
+esquadrao studio transcribe /caminho/do/video_longo.mp4 --dest ./workspace --json
+```
+O arquivo `./workspace/packages/transcript.json` conterá todos os blocos com `start_s`, `end_s` e `text`.
+
+> **Aviso de Execução:** O comando `transcribe` utiliza o mesmo mecanismo do auto-clip. Requer chave `OPENAI_API_KEY` configurada ou instalação prévia do módulo `@xenova/transformers`.
+
+### Passo 2: Análise de Copy e Seleção dos Melhores Trechos
+A LLM pode rodar o detector automatizado de ganchos ou analisar manualmente o `transcript.json`:
+```bash
+esquadrao studio find-hooks ./workspace/packages/transcript.json --min-dur 30 --max-dur 60 --json
+```
+O comando retorna os Top 3 candidatos ranqueados com pontuação de gancho, timestamps exatos (`start_ms`, `end_ms`) e punchlines.
+
+A LLM deve aplicar a **Fórmula Tripartite de Retenção Viral**:
+1. **O Gancho (0 a 3 segundos):** Identifique o momento em que o orador faz uma pergunta contraintuitiva, revela um segredo ou expõe um erro comum. O corte DEVE começar exatamente na primeira palavra do gancho (ex: *"O maior erro de quem tenta vender..."*).
+2. **Janela de Retenção (30s a 60s flexível):** A ideia central precisa ser explicada com clareza sem prolixidade. Se o raciocínio exigir 45s ou 55s, respeite a conclusão natural da ideia. Permita ajuste se o usuário solicitar cortes mais curtos ou mais longos.
+3. **Punchline de Fechamento:** O corte encerra no clímax da resposta ou conclusão, cortando antes de transições vazias ("é isso", "então pessoal", "deixa o like").
+
+### Passo 3: Escolha Dinâmica dos B-Rolls e Layouts
+Para evitar que o corte fique monótono ("cabeça falante"), a LLM insere B-rolls (`overlays`) e escolhe o layout ideal:
+- **`layout: "fullscreen"` (Padrão):** Insira a cada 5 a 8 segundos cenas de apoio temáticas (ex: dinheiro, mansões, carros, trabalho) cobrindo 100% da tela durante 2 a 3 segundos, mantendo a voz do orador contínua.
+- **`layout: "split_bottom"` (Dupla Retenção):** Para canais de alta velocidade (TikTok/Shorts), divida a tela com o orador em cima e o vídeo de apoio/pack embaixo. Use `--overlay-duration full` para manter o pack na base durante todo o clipe; sem essa flag, o layout é uma janela de B-roll de 2–4 s.
+- **`layout: "pip"` (Picture-in-Picture):** Quando o orador estiver apontando para um objeto ou reagindo a algo.
+- **`layout: "split_top"` (Pendente / Backlog CLI-06):** Previsto no schema (orador embaixo e B-roll em cima), porém não implementado no renderizador atual (cai em tela cheia). O agente deve utilizar `"split_bottom"`, `"fullscreen"` ou `"pip"`.
+- **Recorte de pessoa / cutout (experimental / CLI-14):** `studio cutout --background <pack> --python <interpretador>` remove o fundo e compõe o pack atrás do orador. Exige Python com `rembg`/OpenCV e custa ~18–20 min de CPU por 60 s em 15 fps; não prometa tempo real. Consulte [`composicoes-especiais.md`](./composicoes-especiais.md).
+
+### Passo 4: Trilha Sonora com Ducking
+Importe a música de fundo e configure a atenuação de volume:
+- **Atenuação Estática de Volume:** A propriedade `ducking: true` em `music_tracks` aplica uma redução fixa de `-22dB` via mixagem `amix`. Não se trata de ducking dinâmico por sidechain com compressão em tempo real sobre a voz (previsto no backlog CLI-05). O volume fixo reduz a trilha para não encobrir a fala.
+
+### Passo 5: Geração do EditPlan Completo e Renderização
+Exemplo canônico de EditPlan com cortes, B-rolls, música e legendas estilo impacto:
+```json
+{
+  "schema_version": 1,
+  "mode": "podcast_clip",
+  "output": {
+    "width": 1080,
+    "height": 1920,
+    "fps_num": 30,
+    "fps_den": 1,
+    "video_codec": "h264",
+    "audio_codec": "aac"
+  },
+  "clips": [
+    {
+      "kind": "video",
+      "clip_id": "fala-principal",
+      "asset_id": "AST-PODCAST01",
+      "in_ms": 124000,
+      "out_ms": 168000,
+      "timeline_start_ms": 0,
+      "speed": 1
+    }
+  ],
+  "audio_tracks": [
+    { "kind": "source", "clip_id": "fala-principal", "gain_db": 0 }
+  ],
+  "overlays": [
+    {
+      "kind": "video",
+      "asset_id": "AST-BROLL-DINHEIRO",
+      "layout": "fullscreen",
+      "in_ms": 0,
+      "out_ms": 3000,
+      "timeline_start_ms": 6000,
+      "duration_ms": 3000
+    }
+  ],
+  "music_tracks": [
+    {
+      "asset_id": "AST-TRILHA01",
+      "gain_db": -22,
+      "ducking": true
+    }
+  ],
+  "captions": [
+    {
+      "text": "O MAIOR ERRO",
+      "timeline_start_ms": 0,
+      "duration_ms": 1200,
+      "style": "impact"
+    }
+  ]
+}
+```
+Renderize e verifique com:
+```bash
+esquadrao studio render ./workspace/packages/editplan.json --dest ./workspace
+esquadrao studio qa ./workspace/artifacts/video.mp4 --plan ./workspace/packages/editplan.json
+```

package/skill-orchestrate/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: skill-orchestrate
+version: "1.0.0"
+description: "Orchestrate autonomous multi-agent missions, manage checkpoints, and coordinate execution."
+allowed-tools: ["terminal"]
+---
+
+# Agent Orchestrate
+
+Orchestrate end-to-end missions, autonomous pipelines, and checkpoint rollbacks via CLI or git branches.
+
+## When to Use
+
+- Executing end-to-end autonomous missions across multi-phase tasks.
+- Coordinating autonomous multi-agent swarms with bounded resource budgets.
+- Capturing atomic state snapshots (`checkpoints`) before high-risk mutations.
+- Reverting failed or regressed mission states deterministically (`rollback`).
+
+## NOT for
+
+- AST slicing or syntax graph extraction (`skill-context`).
+- WCAG accessibility or visual TDD audits (`skill-ui`).
+- Isolated forensic ledger verification (`skill-audit`).
+- Single-wave pipeline scheduling (`skill-pipeline`).
+
+## Workflow & CLI
+
+Execute via local script and git commands:
+
+```bash
+# 1. Validate DAG and execution waves
+node scripts/dag_validator.js tasks.json
+
+# 2. Capture git checkpoint before mutation
+git checkout -b checkpoint/pre-mutation
+
+# 3. Rollback to checkpoint on failure
+git reset --hard HEAD
+```
+
+## UX & Operational Rules
+
+- **Anti-Context-Dumping**: Dispatch minimal context packets (<3,000 tokens). Never dump full workspace trees.
+- **Structured Communication**: Return concise status summaries with work IDs, checkpoint hashes, and gate results.
+
+## References
+
+- Mission lifecycle & transitions: [references/mission-lifecycle.md](references/mission-lifecycle.md)
+- Swarm coordination & arbitration: [references/swarm-coordination.md](references/swarm-coordination.md)

package/skill-orchestrate/references/mission-lifecycle.md

@@ -0,0 +1,36 @@
+# Mission Lifecycle Specification
+
+Governs mission state transitions and atomic checkpointing in agent orchestration.
+
+## Lifecycle States
+
+- **INIT**: Task intake and contract refinement (`refine_prompt`). WorkRecord instantiated with DAG.
+- **RUNNING**: Topological waves executing subtasks concurrently with GREEN test gates.
+- **CHECKPOINT**: Execution paused to persist immutable state snapshot before risky mutations.
+- **COMPLETED**: All subtasks verified GREEN (`verify_subtask`) and Merkle ledger exported.
+- **FAILED**: Unrecoverable regression or exhausted remediations; triggers fail-closed state.
+
+```
+INIT ──> RUNNING ──┬──> CHECKPOINT ──> RUNNING
+                   ├──> COMPLETED (all gates GREEN)
+                   └──> FAILED (unrecoverable / budget exhausted)
+```
+
+## Checkpoint & Rollback Protocol
+
+1. **Snapshot (`create_checkpoint`)**:
+   - Takes `work_id` and optional `label`.
+   - Serializes atomic snapshot of `WorkRecord` (DAG, task outputs, event log).
+   - Returns immutable `checkpoint_id`.
+2. **Rollback (`rollback_checkpoint`)**:
+   - Takes `work_id` and `checkpoint_id`.
+   - Deterministically restores `WorkRecord` to snapshot and releases acquired locks.
+   - Appends signed rollback event to audit ledger.
+
+```bash
+# Capture checkpoint via git branch or stash
+git stash save "checkpoint-pre-patch"
+
+# Rollback checkpoint on failure
+git reset --hard HEAD
+```

package/skill-orchestrate/references/swarm-coordination.md

@@ -0,0 +1,33 @@
+# Swarm Coordination Specification
+
+Framework for coordinating autonomous multi-agent swarms, budgets, and concurrency locks via CLI and filesystem locks.
+
+## Autonomous Swarm Coordination (`coordinate_mission_swarm`)
+
+Swarms execute autonomous agents across topological DAG waves:
+- **Wave Partitioning**: Subtasks grouped by disjoint file paths for safe parallelism.
+- **Context Virtualization**: Minimal surgical context packets (<3,000 tokens) dispatched per agent.
+- **Evidence Gates**: Subtask progression requires deterministic GREEN test verification.
+
+## Budget Allocation (Tokens & Time)
+
+Strict operational ceilings prevent runaway resource consumption:
+- **Token Quotas**: Per-task allocation with SHA-256 context deduplication (>75% token savings).
+- **Timeout Ceilings**: Bounded wall-clock timeouts trigger auto-remediation or fail-closed abort.
+
+## Concurrency Arbitration (`arbitrate_concurrency`)
+
+Prevents file access collisions and deadlocks across concurrent subagents:
+- **Lock Modes**:
+  - `SHARED`: Simultaneous read-only access by multiple agents.
+  - `EXCLUSIVE`: Single-agent write lock on specific file paths.
+- **Lease Operations**:
+  - `acquire`: Claims lock on `paths` with `agent_id`, `workspace_id`, and `ttl_seconds`.
+  - `renew`: Heartbeat extends `expires_at` for long-running executions.
+  - `release`: Deterministic cleanup requiring matching `agent_id` in `finally` blocks.
+- **Zombie Purging**: Expired leases (`expires_at < now()`) auto-evict, promoting waiters.
+
+```bash
+# Acquire path lockfile with atomic file write
+node -e "fs.writeFileSync('.lock-src-core', JSON.stringify({agent_id: 'agent-1', expires_at: Date.now() + 30000}), {flag: 'wx'})"
+```

package/skill-pipeline/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: skill-pipeline
+version: "1.0.0"
+description: "Decompose complex tasks into acyclic execution DAGs, compute topological waves, and auto-heal test failures."
+allowed-tools: ["terminal"]
+---
+
+# Agent Pipeline
+
+Decompose tasks into topological waves, enforce acyclic dependencies, and trigger deterministic auto-healing.
+
+## When to Use
+
+- Breaking down epics into granular, testable DAG tasks.
+- Validating dependency acyclicity and computing execution waves.
+- Automated error diagnosis and targeted test remediation (auto-healing).
+
+## NOT for
+
+- Merkle ledger verification (`skill-audit`).
+- Multi-agent swarm leasing and concurrency locks (`skill-orchestrate`).
+- Codebase outline and AST extraction (`skill-context`).
+
+## Workflow & CLI
+
+Execute via local script:
+
+```bash
+# Validate DAG and compute topological waves
+node scripts/dag_validator.js tasks.json
+```
+
+## UX & Operational Rules
+
+- Tasks must declare strict `depends_on` lists referencing valid IDs.
+- Never execute cyclical DAGs; validate with Kahn's algorithm before running.
+
+## References
+
+- Topological waves: [references/topological-waves.md](references/topological-waves.md)
+- DAG decomposition rules: [references/dag-decomposition-rules.md](references/dag-decomposition-rules.md)
+- Auto-healing patterns: [references/auto-healing-patterns.md](references/auto-healing-patterns.md)

package/skill-pipeline/references/auto-healing-patterns.md

@@ -0,0 +1,17 @@
+# Auto-Healing Patterns
+
+Deterministic remediation patterns for test failures and execution anomalies.
+
+## Failure Classification
+
+1. **Assertion Failure**: Code output deviates from expected contract.
+   - *Remediation*: Inspect AST diff, locate mutated function, revert to last known green contract.
+2. **Environment Failure**: Missing dependency or uninitialized database/service.
+   - *Remediation*: Trigger idempotent initialization hook; re-verify preflight prerequisites.
+3. **Flaky / Timing Failure**: Race condition or asynchronous event timeout.
+   - *Remediation*: Isolate concurrent promises, replace arbitrary sleep with deterministic event listener.
+
+## Remediation Protocol
+
+- Maximum 3 auto-healing cycles per subtask.
+- If cycle count exceeds threshold, escalate to parent orchestrator with full error trace.

package/skill-pipeline/references/dag-decomposition-rules.md

@@ -0,0 +1,18 @@
+# DAG Decomposition Rules
+
+Rules for breaking complex engineering goals into parallelizable execution units.
+
+## Core Rules
+
+1. **Atomic Boundaries**: Each task touches at most 3 related source files.
+2. **Explicit Verification**: Every task must define at least one executable check (unit test or command).
+3. **Strict Acyclicity**: No task may directly or transitively depend on its own output.
+4. **Declared Dependencies**: All inputs from previous tasks must be listed in `depends_on`.
+
+```json
+[
+  { "id": "task_1", "description": "Define data schema", "depends_on": [] },
+  { "id": "task_2", "description": "Implement repository", "depends_on": ["task_1"] },
+  { "id": "task_3", "description": "Create HTTP routes", "depends_on": ["task_2"] }
+]
+```

package/skill-pipeline/references/topological-waves.md

@@ -0,0 +1,16 @@
+# Topological Waves Specification
+
+Topological wave computation partitions tasks into ordered parallel batches using Kahn's algorithm.
+
+## Computation Algorithm
+
+1. Calculate in-degrees (number of incoming dependencies) for each node.
+2. Wave 0 contains all nodes with `in_degree == 0`.
+3. Process Wave N: decrement in-degrees of dependent nodes.
+4. Nodes reaching `in_degree == 0` form Wave N+1.
+5. If processed node count does not equal total nodes, the graph contains cycles.
+
+## Execution Model
+
+- Tasks within the same wave run concurrently up to configured `max_concurrency`.
+- Progression to Wave N+1 is blocked until all tasks in Wave N pass their verification gates.

package/skill-product-manager/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-product-manager
+version: "1.0.0"
+description: "Synthesize user intent and business needs into unambiguous requirements, scope boundaries, and acceptance criteria."
+allowed-tools: ["terminal"]
+---
+
+# Product Manager
+
+Synthesize product vision into crisp, testable requirements and explicit boundary constraints.
+
+## When to Use
+
+- Translating high-level feature requests into formal requirement contracts.
+- Defining bounded scope (`in_scope`, `out_of_scope`) before engineering kickoff.
+- Establishing verifiable acceptance criteria and risk classifications.
+
+## NOT for
+
+- Generating code patches (`skill-software-engineer`).
+- Arbitrating architectural trade-offs (`skill-tech-lead`).
+- Slicing repository ASTs (`skill-context`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. Inspect role definition and constraints
+esquadrao role info product-manager
+
+# 2. Generate calibrated prompt for requirements synthesis
+esquadrao role prompt product-manager "Build headless authentication with OAuth2"
+```
+
+## UX & Operational Rules
+
+- Scope must be concrete: name specific workflows or modules, not open-ended epics.
+- Acceptance criteria must be binary and verifiable (true/false).
+- Classify risk objectively based on data sensitivity and operational blast radius.