Centro de Documentação: Prompt Pipeline + OpenClaw

Estratégia de Migração de Problemas

# Estratégia de Migração de Problemas Legados (WOK)

Este documento descreve a estratégia automatizada para converter problemas legados (geralmente em PDF) para o ecossistema **Universo WOK**. A estratégia é dividida em cinco fases principais, utilizando uma sequência de prompts inteligentes no **Antigravity**.

---

## 🗺️ Fluxo de Trabalho (Pipeline)



---

## 🚀 Fase 1: Análise e Estrutura Inicial
**Objetivo**: Realizar a "limpeza física" e a classificação técnica do problema, preparando o terreno para a expansão pedagógica.

### 0.1: Conversão WOK (PDF → Markdown)
- **Objetivo**: Extrair o texto do PDF original com máxima fidelidade.
- **Ação**: Remove ruídos de extração, organiza tabelas de exemplos e cria a estrutura de pastas `statements/a-{slug}/`.
- **Resultado**: Arquivos `a_pt_{slug}.md` e `a_pt_{slug}.pdf` (Preservação histórica).

### 0.2: Refinamento de Metadados
- **Objetivo**: Criar o "esqueleto" técnico do problema.
- **Ação**: Gera o `metadata.yaml` inicial com `description`, `editorial` (estratégia gulosa, PD, etc) e `timeComplexity`.
- **Resultado**: Classificação inicial de dificuldades e habilidades (`skills`).

### 1.1: Análise de Enunciado
- **Objetivo**: Garantir que o problema seja compreensível e sem ambiguidades.
- **Ação**: Busca por restrições inconsistentes ou casos de borda não mencionados no PDF original.

---

## 🎨 Fase 2: Organização, Expansão e Enunciados
**Objetivo**: Focar na experiência do usuário e na diversidade pedagógica.

### 2.1: Expansão de Níveis (A/B/C/D)
- **Objetivo**: Suportar alunos em diferentes níveis de maturidade.
- **Níveis**:
    - **Nível A**: Enunciado técnico padrão.
    - **Nível B**: PDF original como fonte.
    - **Nível C (Educacional)**: Cita a estratégia recomendada (ex: "Use Sorting").
    - **Nível D (Tutorial)**: Explica o passo a passo da solução.

### 2.2: Geração Temática (Extra/Opcional) ✨
- **Objetivo**: Gamificação e imersão.
- **Ação**: Reescreve o problema no cenário intergaláctico (planetas, naves, alienígenas).

### 2.3: Tradução Multilíngue (Extra/Opcional) 🌍
- **Objetivo**: Alcance global da plataforma.
- **Ação**: Traduz os enunciados para Inglês (EN) e Espanhol (ES) mantendo a consistência.

---

## 🧪 Fase 3: Soluções e Casos de Teste
**Objetivo**: Transformar o enunciado em um problema funcional e testável.

### 3.1: Geração de Soluções
- **Objetivo**: Fornecer referências de código confiáveis.
- **Ação**: Cria soluções **Ótimas (A)** em Java/Python/C++ e **Sub-ótimas (B)** (ex: Brute Force) para validar limites de tempo.

### 3.2: Design de Cenários e Análise de Erros
- **Objetivo**: Planejar a cobertura de testes baseada em possíveis falhas dos alunos.
- **Ação**: Define os `testScenarios` e cria `helpTips` (dicas) acionáveis no `metadata.yaml`.

### 3.3: Criação e Validação de Casos de Teste
- **Objetivo**: Gerar os arquivos físicos de teste (.in/.out).
- **Ação**: Scripts Python automatizados para gerar dados de teste e validar se respeitam as restrições (`min/max`).

---

## 🔍 Fase 4: Verificação Técnica
**Objetivo**: Garantir que o problema se comporte conforme o esperado antes da publicação.

### 4.1: Check de Complexidade e Paradigma
- **Objetivo**: Auditoria de desempenho.
- **Ação**: Verifica se a solução ótima realmente atende à complexidade declarada e se o paradigma (Gulo, PD, etc) está correto.

### 4.2: Script de Verificação Automática
- **Objetivo**: Criar uma ferramenta de teste local rápida.
- **Ação**: O script `verify_solutions.py` julga todas as soluções contra todos os casos de teste.

---

## 🎓 Fase 5: QA Final e Melhoria Pedagógica
**Objetivo**: O toque final de qualidade e valor educacional.

### 5.1: Integridade de Metadados e Estrutura
- **Objetivo**: Conformidade total com o Schema WOK.
- **Ação**: Verifica slugs, IDs, caminhos de arquivos e formatos de habilidades.

### 5.2: Melhoria Educacional
- **Objetivo**: Maximização do aprendizado.
- **Ação**: Refina as `helpTips` e sugere melhorias no enunciado para clareza didática.

---

## 📄 Resultado Final: YAML Consolidado
Ao final de todas as etapas, o arquivo `metadata.yaml` estará totalmente preenchido, validado e pronto para o upload na plataforma, contendo toda a inteligência pedagógica e técnica do Universo WOK.

Fase 0 — Baseline do Pipeline

# Fase 0 — Baseline do Pipeline de Prompts

Este documento formaliza a linha de base do pipeline atual antes de mudanças na ordem e no fluxo.

---

## Escopo da Fase 0

- Congelar o estado atual dos prompts.
- Mapear dependências entre etapas.
- Identificar riscos do fluxo atual.
- Definir métricas para comparar antes/depois.

---

## Inventário Atual de Prompts (Fonte: `PROMPTS_LIST`)

| ID  | Fase | Título                                          |
|-----|------|-------------------------------------------------|
| 0.1 | 0    | Validação de Statement Base (Fonte -> Markdown) |
| 0.2 | 0    | Metadata Mínimo (Descrição + Editorial Inicial) |
| 0.3 | 0    | Garantir Solução Ótima Básica + Editorial D     |
| 0.4 | 0    | Garantir d-sample Mínimo                        |
| 0.5 | 0    | YAML Sanity Check (Alpha)                       |
| 1.1 | 1    | Statement Analysis                              |
| 2.1 | 2    | Statement Expansion (Levels A/B/C/D)            |
| 2.2 | 2    | WOK Statement Generation (Themed)               |
| 2.3 | 2    | Multilingual Translation                        |
| 3.1 | 3    | Solution Generation                             |
| 3.2 | 3    | Scenario Design & Error Analysis                |
| 3.3 | 3    | Test Case Creation & Validation                 |
| 4.1 | 4    | Complexity & Paradigm Check                     |
| 4.2 | 4    | Migração e Classificação de Casos de Teste      |
| 4.3 | 4    | Automated Verification Script                   |
| 5.1 | 5    | Metadata & Structure Integrity Check            |
| 5.2 | 5    | Educational Improvement                         |

---

## Dependências Principais (ordem lógica atual)

1. `0.1` garante statement base com prioridade de fonte (PDF > HTML > MD bruto único).
2. `0.2` garante metadata mínimo obrigatório (`description`, `editorial`, `origin`).
3. `0.3` garante solução `a-otima*` e enunciado editorial `d_pt_{slug}.md`.
4. `0.4` garante cenário `d-sample` com pares `.in/.out` renomeados.
5. `0.5` garante sanidade estrutural do YAML (leve, sem normalização semântica rígida).
6. `1.x+` trabalham melhoria incremental dos artefatos mínimos.

---

## Riscos Detectados no Baseline

1. **Prompts longos e multi-objetivo**: aumentam variação e drift.
2. **Contrato de escrita implícito**: falta delimitação forte de arquivos permitidos/proibidos.
3. **Ordem com sobreposição parcial**: algumas etapas podem reescrever resultados de anteriores.
4. **Ausência de checkpoint de execução**: difícil retomar e auditar automaticamente.
5. **Validação pós-escrita não homogênea**: risco de erro silencioso em disco.

---

## Métricas de Comparação (antes/depois)

- **M1 — Taxa de retrabalho por prompt**: quantas vezes uma etapa precisa ser refeita.
- **M2 — Alterações fora do esperado**: arquivos modificados fora do escopo da etapa.
- **M3 — Tempo por fase**: duração média por execução.
- **M4 — Falhas de validação**: quantidade de erros estruturais após cada fase.
- **M5 — Estabilidade**: diferença de resultado em reexecução (idempotência).

---

## Gate de Saída da Fase 0

Considera-se Fase 0 concluída quando:

- [x] Prompt `0.1` definido e validado por heurística de artefatos A/B.
- [x] Prompt `0.2` definido e validado por campos mínimos no YAML.
- [x] Prompt `0.3` definido e validado (solução `a-otima*` + editorial D).
- [x] Prompt `0.4` definido e validado (`d-sample` + `sample-XX.in/.out`).
- [x] Prompt `0.5` definido e validado (YAML parseável/top-level mapping).
- [x] Status dos prompts exposto na UI e no endpoint de status da API.
- [ ] Coleta real de métricas em 2 problemas piloto (simples + real).

---

## Próxima Ação Imediata (Fase 1)

Com a baseline definida, iniciar mudanças de fluxo com baixo risco:

1. Distribuir validações semânticas (skills, origem, complexidade) em prompts focados.
2. Ajustar ordem de etapas com foco em reduzir retrabalho.
3. Testar em `0001-hello-world` e `0022-alarme-despertador`.

Fase 1 — Kickoff

# Fase 1 — Kickoff (Contrato de Prompt e Fluxo)

Esta fase começa com a baseline congelada da Fase 0.

## Decisão de Governança

- O pipeline atual permanece **congelado** durante a Fase 1.
- Melhorias candidatas (ex.: alternativas para `0.1` como HTML->MD, OCR/normalização extra, reorder de prompts) entram como **backlog controlado**.
- Nenhuma mudança estrutural no fluxo entra sem passar pelo contrato de prompt e critérios de aceite.

---

## Objetivo da Fase 1

Transformar prompts em etapas operacionais e auditáveis, reduzindo ambiguidade de escrita em disco.

---

## Backlog Inicial (capturado)

1. `0.1` com alternativa `html -> md` para comparar qualidade contra `pdf -> md`.
2. Ajuste de ordem entre prompts da Fase 2 para reduzir retrabalho.
3. Regras mais rígidas para arquivos permitidos/proibidos por etapa.
4. Pós-validação padronizada após cada prompt.
5. Distribuir validação semântica em prompts específicos (não centralizar no `0.5`).

---

## Contrato Padrão por Prompt (v1)

Cada prompt deve declarar:

1. **Inputs obrigatórios**
   - caminhos absolutos e arquivos de referência;
2. **Escopo de escrita**
   - arquivos que pode criar/editar;
   - arquivos explicitamente proibidos;
3. **Formato de saída**
   - blocos `...`;
4. **Critérios de aceite**
   - checklist técnico objetivo;
5. **Validação pós-escrita**
   - comandos/regras mínimas de verificação.

---

## Ordem de Execução Proposta (para teste controlado)

Ordem candidata da Fase 1 (sem aplicar ainda em produção):

1. `0.1` Conversão de enunciado base
2. `1.1` Análise de enunciado (clareza e consistência)
3. `0.2` Refinamento técnico de metadata
4. `2.1` Expansão C/D
5. `2.2` Versão temática
6. `2.3` Tradução
7. `3.x` Soluções e testes
8. `4.x` Verificação técnica
9. `5.x` QA final

Racional: analisar cedo para calibrar metadata e reduzir reescrita de editorial/nível.

---

## Entregáveis da Fase 1

- [ ] Template de contrato aplicado aos prompts críticos (`0.1`, `0.2`, `1.1`, `2.1`, `2.2`).
- [ ] Definição de prompts focados para validação semântica (origem, skills, complexidade, limites).
- [ ] Matriz de impacto da nova ordem (antes/depois).
- [ ] Execução piloto em `0001-hello-world` e `0022-alarme-despertador`.
- [ ] Decisão de go/no-go para alterar ordem oficial.

---

## Critério de Saída da Fase 1

A Fase 1 termina quando:

- contratos de prompt estiverem padronizados;
- mudança de ordem mostrar redução de retrabalho;
- não houver aumento de alterações fora do escopo.

Roadmap de Evolução dos Prompts

# Roadmap de Evolução dos Prompts para Arquitetura OpenClaw

Este roadmap descreve como evoluir o pipeline de prompts do modo manual atual para um fluxo robusto, validável e orquestrável via API/OpenClaw.

---

## Objetivo Geral

Transformar prompts longos e abertos em etapas operacionais, idempotentes e seguras para escrita em disco, com observabilidade e automação progressiva.

---

## Fase 0 — Baseline e Congelamento

**Meta**: Criar uma linha de base confiável antes de refatorar.

- Mapear todos os prompts atuais (`id`, `fase`, entradas, arquivos alterados).
- Definir critérios mínimos por prompt:
  - idempotência;
  - arquivos permitidos/proibidos;
  - validação pós-escrita.
- Congelar versão atual com tag interna de referência.

**Saída esperada**:
- Matriz de prompts (`prompt-matrix.md`).
- Checklist de qualidade por etapa.

### Status Atual da Fase 0

- `0.1`: statement base + fonte prioritária (PDF > HTML > MD bruto único).
- `0.2`: metadata mínimo obrigatório (`description`, `editorial`, `origin`).
- `0.3`: solução `a-otima*` + editorial `d_pt_{slug}.md`.
- `0.4`: `d-sample` + pares `sample-XX.in/.out`.
- `0.5`: sanidade estrutural do YAML (leve).
- Checks disponíveis na UI de prompts e no endpoint de status da API.

---

## Fase 1 — Prompt Contract (modo manual assistido)

**Meta**: Tornar cada prompt executável sem ambiguidade.

Para cada prompt:
1. Declarar entradas obrigatórias (paths absolutos e contexto).
2. Definir escrita permitida e arquivos bloqueados.
3. Exigir formato de saída com blocos `...`.
4. Definir critérios de aceite objetivos.

**Regras-chave**:
- Não escrever fora da pasta do problema.
- Não alterar arquivos não listados no prompt.
- Reexecução deve produzir o mesmo resultado (idempotente).

**Saída esperada**:
- Prompts revisados e padronizados.
- Menor variação de resultado entre execuções.
- Validações semânticas distribuídas em prompts focados por domínio (origem, skills, complexidade, cenários).

---

## Fase 2 — Fluxo transacional de escrita em disco

**Meta**: Reduzir risco de corrupção/inconsistência.

- Implementar escrita em duas etapas:
  - gerar `*.tmp`;
  - validar;
  - efetivar com rename atômico.
- Criar checkpoint de execução:
  - arquivo `.wok-run/state.json` com `prompt_id`, `status`, `outputs`, `timestamp`.

**Saída esperada**:
- Rastreabilidade completa de cada etapa.
- Recuperação mais simples após falha.

---

## Fase 3 — Agente interno via API (beta)

**Meta**: Tirar dependência de copy/paste manual.

- Evoluir `POST /api/v1/pipeline/run` com:
  - `dry_run` (sem escrita real);
  - relatório de diff previsto;
  - validação pós-run automática.
- Registrar auditoria:
  - duração;
  - arquivos alterados;
  - erros;
  - status final.

**Saída esperada**:
- Execução reproduzível por API.
- Visibilidade de impacto antes de escrever.

---

## Fase 4 — Orquestração OpenClaw (E2E)

**Meta**: Operar em loop de curadoria automatizado.

Loop recomendado:
1. `GET /api/v1/problems//status`
2. `POST /api/v1/pipeline/run`
3. `POST /api/v1/verify/run`
4. Decisão da próxima etapa (seguir, repetir, pedir revisão)

**Saída esperada**:
- Pipeline ponta a ponta com estados explícitos:
  - `pending`, `running`, `needs_review`, `done`, `failed`.

---

## Fase 5 — Qualidade contínua e documentação viva

**Meta**: Evitar regressões e manter governança.

- Atualizar docs a cada mudança de contrato:
  - arquitetura;
  - endpoints;
  - roadmap;
  - changelog do pipeline.
- Definir smoke tests fixos (problema simples + problema real).
- Acompanhar métricas:
  - taxa de sucesso;
  - prompts com retrabalho;
  - tempo médio por fase.

---

## Priorização Recomendada

1. **Primeiro**: Fase 1 + Fase 2 (robustez de prompt e escrita).
2. **Depois**: Fase 3 (API interna com dry-run e auditoria).
3. **Por fim**: Fase 4 (OpenClaw em produção de fluxo).

---

## Critérios de Pronto (Definition of Done)

- Prompts críticos sem ambiguidade de escrita.
- Nenhuma alteração fora da árvore do problema.
- Logs e checkpoints por execução.
- Página de estratégia com seção de roadmap atualizada.
- Fluxo E2E validado em pelo menos 2 problemas.

Arquitetura OpenClaw

# VPS Architecture: problem-tools & OpenClaw

This document describes the infrastructure and integration between the `problem-tools` application and the `OpenClaw` agent on the VPS.

## Context

The system is designed for high-performance exercise curation and validation. It leverages a VPS to host both the main application and a containerized agent (OpenClaw) that interacts with the same codebase.

## Infrastructure Overview

- **Host (VPS)**: Runs the `problem-tools` application directly (using Python/Flask).
- **Docker Container (OpenClaw)**: An instance of OpenClaw running inside Docker, specifically configured to access the host's filesystem.
- **Shared Source Code**: The core element of this architecture is that both the Host and the OpenClaw container access the **same physical directory** on the disk.

### Interaction Diagram

```mermaid
graph TD
    subgraph VPS_Host [VPS Host]
        PT[problem-tools App]
        FS[(Shared Source Code)]
    end

    subgraph Docker_Environment [Docker]
        OC[OpenClaw Agent]
    end

    %% Interactions
    PT <--> FS
    OC <--> FS
    OC -- API Calls --> PT
    PT -- Webhooks/Events --> OC
```

## Key Benefits

1.  **Zero Latency Data Access**: Since both entities share the same filesystem, there is no need to transfer large datasets (like test cases or problem statements) over the network.
2.  **Synchronized Workspace**: Any file modification (e.g., a prompt generating a new Markdown statement) is immediately visible to both components.
3.  **Decoupled Intelligence**: OpenClaw can focus on high-level orchestration and reasoning, while `problem-tools` handles low-level file management, validation logic, and UI.

## Operational Workflow

1.  **OpenClaw** receives a high-level task (e.g., "Validate problem X").
2.  **OpenClaw** checks the shared workspace for the current state of problem X.
3.  **OpenClaw** triggers a validation task in `problem-tools` via a dedicated endpoint.
4.  **problem-tools** executes the validation (using `verify_solutions.py` or similar scripts) and writes the results to the workspace or returns them via API.
5.  **OpenClaw** reads the updated state/results and continues the workflow.

Estratégia de Endpoints OpenClaw

# Endpoint Strategy — OpenClaw API v1

Este documento define a API REST exposta pelo `problem-tools` para integração
com o OpenClaw e outros agentes externos. A primeira versão foi implementada
em `app/controllers/api_controller.py` como um Blueprint Flask no prefixo `/api/v1/`.

---

## Autenticação

Todos os endpoints (exceto `/health`) são protegidos por um token simples:

```
Header: X-Agent-Token: 
```

O valor esperado é lido da variável de ambiente `AGENT_API_TOKEN`. Se a
variável não estiver definida, a autenticação é **desativada** (modo dev).

---

## Formato de Resposta

Todas as respostas seguem o envelope padrão:

```json
// Sucesso
{ "ok": true,  "data": { ... }, "error": null }

// Erro
{ "ok": false, "data": null,  "error": "Mensagem de erro." }
```

---

## Endpoints Implementados

### 🔎 Saúde e Diagnóstico

#### `GET /api/v1/health`

Verifica se a API está ativa. **Não requer token.**

```bash
curl http://localhost:5000/api/v1/health
```

**Resposta:**
```json
{
  "ok": true,
  "data": { "status": "ok", "version": "1.0" },
  "error": null
}
```

---

### 📚 Informação dos Problemas

#### `GET /api/v1/problems`

Lista todos os problemas disponíveis no workspace local.

| Query param | Tipo   | Descrição                    |
|:------------|:-------|:-----------------------------|
| `q`         | string | Filtra por substring no slug |

```bash
curl -H "X-Agent-Token: $AGENT_API_TOKEN" \
     http://localhost:5000/api/v1/problems?q=labirinto
```

**Resposta:**
```json
{
  "ok": true,
  "data": {
    "total": 2,
    "problems": ["0229-labirinto", "0244-labirinto-basico"]
  }
}
```

---

#### `GET /api/v1/problems//metadata`

Retorna o conteúdo completo do `metadata.yaml` de um problema como JSON.

```bash
curl -H "X-Agent-Token: $AGENT_API_TOKEN" \
     http://localhost:5000/api/v1/problems/0229-labirinto/metadata
```

**Resposta:**
```json
{
  "ok": true,
  "data": {
    "id": "0229",
    "slug": "labirinto",
    "name": "Labirinto",
    "skills": ["grafos", "bfs"],
    ...
  }
}
```

---

#### `GET /api/v1/problems//status`

Retorna um snapshot completo do estado do problema: metadata, soluções
encontradas no filesystem, contagem de casos de teste e status de validação
dos prompts (gate de qualidade).

```bash
curl -H "X-Agent-Token: $AGENT_API_TOKEN" \
     http://localhost:5000/api/v1/problems/0229-labirinto/status
```

**Resposta:**
```json
{
  "ok": true,
  "data": {
    "slug": "0229-labirinto",
    "path": "/workspace/0229-labirinto",
    "metadata": { ... },
    "solutions": [ ... ],
    "test_cases": { ... },
    "prompt_validations": {
      "0.1": {"state":"done","done":true,"reason":"ok"},
      "0.2": {"state":"pending","done":false,"reason":"missing_or_invalid_editorial"},
      "0.3": {"state":"pending","done":false,"reason":"missing_d_editorial_statement"},
      "0.4": {"state":"pending","done":false,"reason":"missing_metadata_d_sample"},
      "0.5": {"state":"done","done":true,"reason":"ok"}
    }
  }
}
```

---

### 🤖 Pipeline de Prompts (LLM)

#### `GET /api/v1/pipeline/prompts`

Lista todos os templates de prompt disponíveis no pipeline, com ID, fase e título.
Inclui prompts de gate da Fase 0 (`0.1` a `0.5`).

```bash
curl -H "X-Agent-Token: $AGENT_API_TOKEN" \
     http://localhost:5000/api/v1/pipeline/prompts
```

**Resposta:**
```json
{
  "ok": true,
  "data": {
    "total": 15,
    "prompts": [
      { "id": "0.1", "phase": 0, "phase_label": "Gate de Qualidade Minima", "title": "Validacao de Statement Base (Fonte -> Markdown)", "description": "..." },
      { "id": "0.5", "phase": 0, "phase_label": "Gate de Qualidade Minima", "title": "YAML Sanity Check (Alpha)", "description": "..." },
      { "id": "1.1", "phase": 1, "phase_label": "Análise Inicial", "title": "Statement Analysis", "description": "..." },
      ...
    ]
  }
}
```

---

#### `POST /api/v1/pipeline/run`

Executa um prompt de pipeline para um problema via LLM. Salva automaticamente
os arquivos que o LLM retornar no formato `...`.

**Payload:**
```json
{
  "problem_slug": "0229-labirinto",
  "phase_id":     "1.1",
  "lang":         "pt",
  "model_name":   "gemini-1.5-flash-latest"
}
```

| Campo          | Tipo   | Obrigatório | Padrão                      |
|:---------------|:-------|:------------|:----------------------------|
| `problem_slug` | string | ✅           | —                           |
| `phase_id`     | string | ✅           | —                           |
| `lang`         | string | ❌           | `"pt"`                      |
| `model_name`   | string | ❌           | `"gemini-1.5-flash-latest"` |

```bash
curl -X POST http://localhost:5000/api/v1/pipeline/run \
     -H "X-Agent-Token: $AGENT_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"problem_slug":"0229-labirinto","phase_id":"1.1"}'
```

**Resposta:**
```json
{
  "ok": true,
  "data": {
    "problem_slug": "0229-labirinto",
    "phase_id": "1.1",
    "model_name": "gemini-1.5-flash-latest",
    "prompt_title": "Statement Analysis",
    "response_text": "...(resposta do LLM sem tags XML)...",
    "saved_files": ["statements/a-labirinto/a_pt_labirinto.md"]
  }
}
```

---

### ✅ Verificação de Soluções

#### `POST /api/v1/verify/run`

Executa o verificador completo (`VerifierRunner`) para um problema.
Compila e testa todas as soluções contra todos os casos de teste.

**Payload:**
```json
{
  "problem_slug": "0229-labirinto"
}
```

```bash
curl -X POST http://localhost:5000/api/v1/verify/run \
     -H "X-Agent-Token: $AGENT_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"problem_slug":"0229-labirinto"}'
```

**Resposta:**
```json
{
  "ok": true,
  "data": {
    "problem_slug": "0229-labirinto",
    "report": "...relatório de texto gerado pelo VerifierRunner..."
  }
}
```

---

## Estratégia de Integração com OpenClaw

O OpenClaw segue um loop **Check → Run → Validate**:

```mermaid
sequenceDiagram
    participant OC as OpenClaw
    participant PT as problem-tools API
    participant FS as Shared Filesystem

    OC->>PT: GET /api/v1/problems//status
    PT->>FS: Lê metadata.yaml + solutions + test-cases
    PT-->>OC: Snapshot do estado atual

    OC->>PT: POST /api/v1/pipeline/run {phase_id: "2.1"}
    PT->>LLM: Envia prompt com contexto do problema
    LLM-->>PT: Resposta + blocos 
    PT->>FS: Salva arquivos gerados
    PT-->>OC: {saved_files: [...], response_text: ...}

    OC->>PT: POST /api/v1/verify/run
    PT->>FS: Compila e executa soluções
    PT-->>OC: Relatório de verificação

    OC->>OC: Avalia resultado e decide próxima ação
```

---

## Notas de Implementação

- **Sync na v1**: Todas as chamadas são síncronas. O LLM tem timeout de 240s.
- **Segurança**: `X-Agent-Token` via env var `AGENT_API_TOKEN`. Se ausente, a autenticação é ignorada (dev mode).
- **Arquivo-fonte**: `workspace/problems-tools/app/controllers/api_controller.py`
- **Prefixo**: Todos os endpoints estão sob `/api/v1/`.
- **File saving**: O endpoint `pipeline/run` salva arquivos retornados pelo LLM no formato XML `` diretamente no diretório do problema.
- **Prompt execution mode**: Os prompts são gerados com instrução de modo híbrido:
  - escrita direta em disco quando o agente suporta;
  - fallback para blocos `` quando escrita direta não está disponível.

Roadmap OpenClaw

# OpenClaw Onboarding & Test Roadmap (Fase 0 pronta)

Este documento foi atualizado para guiar um colaborador que esta iniciando no OpenClaw e precisa executar os primeiros testes com seguranca, agora que os gates da Fase 0 (`0.1` a `0.5`) estao definidos.

---

## Objetivo deste roadmap

Colocar o colaborador para:

1. subir e validar conectividade da API;
2. entender os checks da Fase 0;
3. executar a primeira skill/fluxo no OpenClaw sem quebrar o workspace;
4. validar resultado via `prompt_validations`.

---

## Estado atual (resumo rapido)

- Arquitetura: host + OpenClaw com filesystem compartilhado.
- API v1 funcional.
- Prompts com modo hibrido (escrita direta em disco quando possivel; fallback ``).
- Fase 0 implementada:
  - `0.1` statement base
  - `0.2` metadata minimo
  - `0.3` solucao `a-otima*` + `d_pt`
  - `0.4` `d-sample` com `sample-XX`
  - `0.5` sanidade YAML estrutural
- Endpoint de status ja retorna `prompt_validations`.

---

## Trilha de onboarding do colaborador (detalhada)

### Etapa 1 — Setup local/VPS

- [ ] Configurar `.env` com:
  - `GEMINI_API_KEY`
  - `AGENT_API_TOKEN`
- [ ] Iniciar app:
  - `python run.py`
- [ ] Confirmar API no ar:
  - `GET /api/v1/health`

### Etapa 2 — Smoke tests de leitura

- [ ] `GET /api/v1/problems`
- [ ] `GET /api/v1/problems//status`
- [ ] Confirmar retorno de `prompt_validations` no status.

### Etapa 3 — Entender gate da Fase 0 no problema alvo

Usar um problema piloto (ex.: `1318-bilhetes-falsos`):

- [ ] Ver quais checks estao `done` e `pending`.
- [ ] Anotar `reason` de cada pendencia.
- [ ] Nao executar prompts de melhoria (1.x+) antes de fechar 0.x.

### Etapa 4 — Primeira skill/fluxo OpenClaw

Fluxo recomendado (primeira skill):

1. `GET /api/v1/problems//status`
2. Se houver pendencias em 0.x, executar apenas prompts da Fase 0 na ordem:
   - `0.1 -> 0.2 -> 0.3 -> 0.4 -> 0.5`
3. Reconsultar `status`
4. Encerrar quando todos os 0.x estiverem `done`.

### Etapa 5 — Critério de sucesso da primeira skill

- [ ] Todos os checks de `0.1` a `0.5` estao `done`.
- [ ] Nenhuma alteracao fora da arvore do problema.
- [ ] `metadata.yaml` parseavel.
- [ ] `d-sample` com pares `sample-XX.in/.out`.
- [ ] `a-otima*` + `d_pt_{slug}.md` presentes.

---

## Primeiros comandos de teste (referencia)

### 1) Health

```bash
curl http://localhost:5000/api/v1/health
```

### 2) Status com validações

```bash
curl -H "X-Agent-Token: $AGENT_API_TOKEN" \
  http://localhost:5000/api/v1/problems/1318-bilhetes-falsos/status
```

### 3) Listar prompts

```bash
curl -H "X-Agent-Token: $AGENT_API_TOKEN" \
  http://localhost:5000/api/v1/pipeline/prompts
```

### 4) Executar um prompt (exemplo 0.5)

```bash
curl -X POST http://localhost:5000/api/v1/pipeline/run \
  -H "X-Agent-Token: $AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"problem_slug":"1318-bilhetes-falsos","phase_id":"0.5","lang":"pt"}'
```

---

## Regras operacionais para o colaborador (importante)

1. Sempre rodar por problema isolado (nunca em lote no inicio).
2. Sempre reconsultar `status` apos cada `pipeline/run`.
3. Nunca pular direto para prompts 1.x+ com Fase 0 pendente.
4. Em caso de erro, registrar:
   - prompt executado
   - payload
   - `reason` retornado em `prompt_validations`
   - trecho relevante de log

---

## Backlog imediato (apos onboarding)

- [ ] Implementar `minimum_quality` agregado no status da API.
- [x] Criar skill OpenClaw "phase0-gate-runner" (especificacao inicial em documento).
- [ ] Adicionar retries controlados por prompt (max tentativas por ID).
- [ ] Criar relatorio final de gate por problema (json/markdown).

Documento da skill:
- `docs/openclaw-skill-phase0-gate-runner.md`

---

## Risco conhecido e mitigacao

- Risco: agente responder em modo chat sem aplicar em disco.
  - Mitigacao: prompts com modo hibrido + rechecagem por `prompt_validations`.

- Risco: normalizacao semantica precoce (ex.: `origin`, `timeComplexity`).
  - Mitigacao: manter semantica distribuida em prompts especializados; `0.5` permanece estrutural.

---

> Dica pratica
>
> Para quem esta aprendendo OpenClaw, o melhor ciclo inicial e curto:
> `status -> run(0.x) -> status -> corrigir pendencias`.
> Isso cria confianca antes de evoluir para fluxos 1.x+.