Metadata-Version: 2.4
Name: argos-cli
Version: 0.3.1
Summary: Núcleo genérico in-process para execução de auditorias
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: textual<1,>=0.89
Requires-Dist: PyYAML>=6
Requires-Dist: jsonschema<5,>=4.18
Provides-Extra: dev
Requires-Dist: bandit<2,>=1.9.4; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: coverage<8,>=7.0; extra == "dev"
Requires-Dist: pip-audit<3,>=2.10; extra == "dev"
Requires-Dist: pre-commit<5,>=4.6; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15.14; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Requires-Dist: virtualenv>=21.7.13; extra == "dev"
Provides-Extra: workbooks
Requires-Dist: openpyxl>=3.1; extra == "workbooks"
Provides-Extra: ai
Requires-Dist: google-genai>=1.0; extra == "ai"
Requires-Dist: json-repair<1,>=0.30; extra == "ai"
Provides-Extra: attachments
Requires-Dist: mammoth>=1.8; extra == "attachments"
Requires-Dist: PyMuPDF<3,>=1.24; extra == "attachments"
Requires-Dist: Pillow>=10; extra == "attachments"
Requires-Dist: pypdf>=6.20.1; extra == "attachments"
Requires-Dist: python-docx>=1.1; extra == "attachments"
Requires-Dist: rarfile>=4.2; extra == "attachments"
Requires-Dist: requests>=2.31; extra == "attachments"
Provides-Extra: reports
Requires-Dist: docxcompose<3,>=2.2; extra == "reports"
Requires-Dist: docxtpl>=0.16; extra == "reports"
Requires-Dist: jinja2>=3.1; extra == "reports"
Requires-Dist: lxml>=5; extra == "reports"
Requires-Dist: markdown-it-py<5,>=3; extra == "reports"
Requires-Dist: python-docx>=1.1; extra == "reports"
Provides-Extra: report-parity
Requires-Dist: lxml>=5; extra == "report-parity"
Requires-Dist: Pillow>=10; extra == "report-parity"
Requires-Dist: PyMuPDF<3,>=1.24; extra == "report-parity"
Provides-Extra: charts
Requires-Dist: matplotlib>=3.8; extra == "charts"
Provides-Extra: benchmarks
Requires-Dist: psutil<8,>=5.9; extra == "benchmarks"
Provides-Extra: downloads
Requires-Dist: requests>=2.31; extra == "downloads"
Requires-Dist: urllib3>=2.8.0; extra == "downloads"
Provides-Extra: all
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: google-genai>=1.0; extra == "all"
Requires-Dist: json-repair<1,>=0.30; extra == "all"
Requires-Dist: mammoth>=1.8; extra == "all"
Requires-Dist: PyMuPDF<3,>=1.24; extra == "all"
Requires-Dist: Pillow>=10; extra == "all"
Requires-Dist: rarfile>=4.2; extra == "all"
Requires-Dist: pypdf>=6.20.1; extra == "all"
Requires-Dist: python-docx>=1.1; extra == "all"
Requires-Dist: docxcompose<3,>=2.2; extra == "all"
Requires-Dist: docxtpl>=0.16; extra == "all"
Requires-Dist: jinja2>=3.1; extra == "all"
Requires-Dist: lxml>=5; extra == "all"
Requires-Dist: markdown-it-py<5,>=3; extra == "all"
Requires-Dist: matplotlib>=3.8; extra == "all"
Requires-Dist: requests>=2.31; extra == "all"
Requires-Dist: urllib3>=2.8.0; extra == "all"

# Argos CLI

Motor in-process e multiplataforma para preparar, executar e acompanhar papéis de trabalho de fiscalização e auditoria governamental. A CLI headless e a TUI Textual compartilham o mesmo catálogo de operações, ciclo de execução, publicação de produtos e SQLite.

O Argos organiza fontes canônicas, aplica regras declaradas, executa avaliações de IA com quórum e revisão humana e publica produtos derivados com proveniência. Ele não certifica conformidade, não escolhe metodologia pelo nome de um índice e não substitui o julgamento da equipe: avaliações e mapas gerados são minutas até a revisão humana.

## Instalação

    python -m pip install -e ".[all]"

## Princípios

1. **Arquivos como fonte canônica.** Markdown, YAML, XLSX, CSV e JSON no disco são os papéis de trabalho canônicos. DOCX, PDF, LSS, imagens e JSON calculado são derivados e devem ser regenerados a partir das fontes.
2. **Imutabilidade por cenário.** Ajustes não sobrescrevem a base: geram arquivos derivados e um cenário filho com vínculo explícito ao pai.
3. **Proveniência registrada.** Cada produto é publicado com hash SHA-256 e metadados no SQLite. `status` distingue execução, integridade dos bytes e atualidade frente às entradas usadas.
4. **Revisão humana explícita.** Avaliações de IA e mapas de verificação nascem como draft. A revisão ocorre nos próprios papéis de trabalho ou na TUI, sem tokens de atestação.
5. **Segurança e portabilidade.** Credenciais vêm exclusivamente de variáveis de ambiente e nunca são gravadas em banco, logs ou produtos. Caminhos usam `pathlib` e UTF-8 explícito.

## Vocabulário

| Termo | Significado |
| --- | --- |
| Fiscalização | Trabalho identificado por número e nome (ex.: `22/2026`, `Auditoria LGPD`), com SQLite próprio em `99-Gestao_e_Controle/controle.sqlite`. |
| Insumo canônico | Arquivo autoral ou coletado: `matriz_planejamento.md`, `questionario.md`, `estrutura-*.yaml`, `mapa-verificacao.xlsx`, planilhas de respostas e ajustes. |
| Cenário | Estado imutável da base em uma fase: `base`, `01-pos-ajuste-inicial`, `02-pos-avaliacao-evidencias`, `03-pos-comentarios-gestor`. |
| Produto | Papel de trabalho gerado pelo motor, registrado com hash e proveniência. |
| Draft | Produto que exige revisão humana antes de orientar decisão. |

## Metodologia

### A cadeia rastreável

```text
Fonte F1 → Informação IR1 → Procedimento P1 → Evidência E1
                                                  ↓
                                    Situação S1.1 + Critério C1 → Achado A1
```

Cada item aponta para o antecedente: `IR` referencia `F`, `P` referencia `IR`, `E` referencia `P`, e a situação referencia riscos, procedimentos, evidências e critérios. A matriz valida essa cadeia antes de gerar documentos; o mapa de verificação a traduz em regras executáveis.

### Quem decide o quê

| Etapa | Decide | Não decide |
| --- | --- | --- |
| Avaliadores de IA | Se a evidência sustenta o item declarado. | Conformidade legal. |
| Juiz | Consolida as opiniões em um parecer com justificativa. | Substituir a decisão da equipe. |
| Mapa de verificação | Resolve a situação e o achado aplicando a regra declarada. | Redigir o encaminhamento. |
| Equipe | Conformidade, encaminhamento e redação final. | — |

O parecer de evidência usa vocabulário de **suporte probatório** (`suportada`, `parcialmente_suportada`, `nao_suportada`, `sem_evidencia`, `nao_avaliada`). O veredito de conformidade nasce depois, na regra da situação e na revisão humana.

### O que é derivado do quê

```text
SurveyMD
  └─► LSS + guia de respondentes
        └─► coleta: respostas.xlsx + auditados/<orgao>-r<id>/

matriz_planejamento.md
  ├─► DOCX/PDF
  └─► mapa de verificação (draft) ──► revisão ──► mapa revisado (XLSX)

respostas + anexos + catálogo de avaliações
  └─► avaliação de evidências ──► pareceres + revisão prioritária
        └─► painel de evidências (planilha mantida pela equipe)

mapa revisado + fontes + painel
  └─► argos auditar ──► resultado-auditoria.json
        └─► relatórios DOCX e entrega
```

## Fluxo padrão

```text
init ─ matriz ─ revisar mapa ─ survey ─ coleta ─ evidências ─ revisão ─ ajustar ─ auditar ─ relatório ─ entrega
                                                      │
                                                      └─ comentários ─ contraditório ─ auditar de novo
```

| Etapa | Comando | Produto | Obrigatório |
| --- | --- | --- | --- |
| 1. Bootstrap | `argos init` | Projeto com `fiscalizacao.yml`, `DIRETRIZES.md`, skills e SQLite. | Sim |
| 2. Planejamento | `argos matriz` (`init`, `validar`, `publicar`, `mapa`) | Matriz Markdown validada, DOCX e mapa XLSX draft. | Sim |
| 3. Revisão do mapa | Edição no XLSX; `argos matriz arvore` gera a árvore HTML do mapa revisado | Mapa apto a orientar a auditoria. | Sim |
| 4. Instrumento | `argos survey gerar --guia` | LSS e guia do respondente. | Quando há questionário |
| 5. Coleta | `argos survey coletar` | Respostas e anexos por auditado, com manifesto. | Quando há coleta |
| 6. Evidências | `argos catalogo` (`gerar`, `validar`, `aprovar`), `argos evidencias preparar` e `argos evidencias avaliar` | Catálogo de avaliações aprovado, árvore de evidências e pareceres por item, com revisão prioritária. | Quando há evidência obrigatória |
| 7. Revisão humana | `argos revisao` (`exportar`, `decidir`, `importar`, `finalizar`) | Decisão registrada por caso e item. | Se houver prioridades |
| 8. Ajustes | `argos ajustar` | Base derivada e cenário filho. | Quando há ajuste |
| 9. Auditoria | `argos auditar` | Resultado com situações, achados e encaminhamentos. | Sim |
| 10. Contraditório | `argos contraditorio` (`preparar`, `avaliar`, `consolidar`, `projetar`) | Manifestações avaliadas e ajustes propostos. | Opcional |
| 11. Índices | `argos indice` | Escores com rastreabilidade. | Opcional |
| 12. Relatório | `argos matriz rascunho` (matriz de achados), `argos documento relatorio-individual`, `argos documento relatorio-auditoria`, `argos documento anexo-evidencias` e, para gráficos, `argos graficos` | Matriz de achados em draft, DOCX individual, consolidado e anexo de evidências. | Sim, para a entrega |
| 13. Controle | `argos status` e `argos controle` (`backup`, `restaurar`, `limpar`, `avaliacoes`) | `status` confere atualidade e integridade; `controle backup` e `controle restaurar` copiam o SQLite; `controle limpar` retira do controle produtos com arquivo removido ou substituídos por um registro mais recente no mesmo caminho; `controle avaliacoes` lista as avaliações de IA gravadas. | Recomendado |

As etapas 4 a 8 e 10 a 11 não se aplicam a toda fiscalização: sem questionário não há coleta, sem evidência obrigatória não há avaliação, sem ajuste não há cenário derivado. A etapa 9 depende do mapa revisado e a 12 depende do resultado da 9. O mapa da etapa 2 é draft até a etapa 3: usá-lo antes da revisão apenas antecipa achados que ainda serão alterados.

### Exemplo de ponta a ponta

    argos init ./auditoria-lgpd --numero 22/2026 --nome "Auditoria LGPD" --objetivo "Avaliar o programa de privacidade"
    cd auditoria-lgpd
    argos matriz init --tipo planejamento
    argos matriz publicar matriz_planejamento.md --pdf
    argos matriz mapa matriz_planejamento.md --config-fontes fontes.yml --output mapa-draft.xlsx
    argos survey gerar questionario.md --guia --pdf
    argos survey coletar --survey-id 123456 --output-dir 02-Execucao/01-Coleta --coluna-auditado firstname
    argos catalogo gerar questionario.md --id lgpd-2026 --output catalogo-evidencias.yml
    argos catalogo validar catalogo-evidencias.yml
    argos catalogo aprovar catalogo-evidencias.yml --revisor "Equipe de auditoria" \
      --output catalogo-evidencias.aprovado.yml
    argos evidencias preparar --coleta 02-Execucao/01-Coleta --respostas respostas.xlsx \
      --output-dir 02-Execucao/04-Evidencias --output preparo-evidencias.json
    argos evidencias avaliar --catalogo catalogo-evidencias.aprovado.yml --questionario questionario.md \
      --respostas respostas.xlsx --raiz-evidencias 02-Execucao/04-Evidencias \
      --avaliadores gemini:gemini-2.5-pro:equipe-v1 --preflight
    argos evidencias avaliar --catalogo catalogo-evidencias.aprovado.yml --questionario questionario.md \
      --respostas respostas.xlsx --raiz-evidencias 02-Execucao/04-Evidencias \
      --avaliadores gemini:gemini-2.5-pro:equipe-v1 --output avaliacao.json
    argos revisao exportar --run-id <ID> --formato xlsx --output revisao.xlsx
    argos revisao importar revisao.xlsx
    argos ajustar --respostas respostas.xlsx --ajustes ajustes.xlsx --output respostas-01.xlsx \
      --scenario-id 01-pos-ajuste-inicial
    argos auditar --base-auditados bd_auditados.xlsx --mapa mapa-revisado.xlsx --matriz matriz_planejamento.md \
      --fontes respostas-01.xlsx --fontes painel-avaliacao-evidencias.xlsx \
      --mapa-fontes questionario=respostas-01.xlsx \
      --mapa-fontes avaliacao_evidencias_ajustes=painel-avaliacao-evidencias.xlsx \
      --output resultado-auditoria.json
    argos documento relatorio-individual --resultado-auditoria resultado-auditoria.json --template relatorio.md --output-dir relatorios/

Cada caminho acima é um exemplo: o mapa revisado, o catálogo de avaliações, o painel de evidências e as demais fontes vêm da equipe, não do `init`.

## Começar um projeto

    argos init ./auditoria-2026 \
      --numero 18/2026 \
      --nome "Fiscalização de exemplo" \
      --processo "000123-4/2026" \
      --objetivo "Examinar a conformidade do objeto"

`init` é o bootstrap e não é uma operação do catálogo de operações; `criar-projeto` é seu alias. Sem `--numero`, `--nome` e `--objetivo`, os três valores são perguntados no terminal — em execução não interativa, informe-os. Opções adicionais: `--objeto`, `--jurisdicionados`, `--area` (repetível; sem ela, cria a estrutura completa) e `--git`.

O projeto recebe `fiscalizacao.yml`, `README.md`, `AGENTS.md`, `DIRETRIZES.md`, `docs/` com as especificações e exemplos das matrizes, `.templates/`, `scripts/`, as skills em `.agents/skills/` e o SQLite de controle.

`DIRETRIZES.md` é a referência de método do projeto: descreve controles esperados, avaliação de evidências por IA, cenários e releases. Leia-o antes de alterar o fluxo. Dentro da raiz, os comandos usam o projeto automaticamente; fora dela, informe `--project-root`.

## Interface

- `argos` sem argumentos abre a TUI; `argos <objeto> [<ação>]` (id `objeto.acao`) ou `argos --run <id>` executa em modo headless. `argos <objeto> --help` lista as ações do objeto.
- `--list-operations` (ou `--list`) mostra as operações, agrupadas por objeto, e seus parâmetros; `--json` imprime o resultado como JSON.
- `--param chave=valor` informa parâmetros sem flag; `--force` não reutiliza uma execução idêntica; `--resume <id>` retoma uma execução pendente.
- Nenhuma credencial é solicitada na linha de comando: provedores de IA, LimeSurvey e download usam variáveis de ambiente. Para não exportá-las a cada sessão, copie `.env.example` (criado pelo `argos init`) para `.env` na raiz do projeto: o Argos o carrega ao iniciar, sem sobrescrever variáveis já definidas e sem nunca exibir os valores. O `.env` já vem no `.gitignore`.
- Operações longas (hoje, `evidencias avaliar` e `contraditorio avaliar`) mostram o andamento em stderr: fase, barra, contagens de reuso/falhas/bloqueios, tempo decorrido e ETA; em logs e pipes saem linhas curtas a cada 15 s. O stdout continua só com o resultado (`--json`); `--no-progress` desliga.

## As operações

O catálogo de operações é compartilhado pela CLI e pela TUI e está organizado em `argos <objeto> [<ação>]`: cada ação é uma operação própria, só com os seus parâmetros. Use `argos --list-operations` para ver parâmetros e defaults.

| Objeto | Uso |
| --- | --- |
| status | Consultar execuções, integridade e atualidade de produtos |
| controle | `backup`: gerar um backup consistente do SQLite; `restaurar`: restaurar um backup em um novo arquivo; `limpar`: retirar do controle produtos obsoletos; `avaliacoes`: listar as avaliações de IA gravadas, com filtros |
| matriz | `init`: criar o boilerplate Markdown; `rascunho`: gerar o draft da matriz de achados a partir do resultado da auditoria; `validar`: conferir a matriz e a rastreabilidade F → IR → P → E → S + C; `publicar`: gerar DOCX, PDF e HTML interativo; `mapa`: derivar o mapa XLSX draft; `arvore`: gerar a árvore HTML do mapa revisado |
| survey | `gerar`: validar SurveyMD e gerar LSS e guia DOCX/PDF; `coletar`: baixar respostas e evidências pela API; `baixar-anexos`: baixar anexos de um XLSX exportado |
| contraditorio | `preparar`: gerar o survey de comentários do gestor (LSS e ZIP de anexos) a partir do resultado da auditoria; `avaliar`: avaliar os comentários recebidos (situações, itens ou ambos); `consolidar`: gerar propostas de ajuste, contexto e painel em draft; `projetar`: projetar o contexto pelos ajustes aplicados |
| ajustar | Aplicar XLSX de ajustes em uma cópia derivada e registrar o cenário pai |
| catalogo | `gerar`: derivar o draft do catálogo de avaliações (prompts) do questionário; `validar`: compilar as definições; `aprovar`: publicar a cópia aprovada; `prompts`: publicar um Markdown por prompt |
| evidencias | `preparar`: montar a árvore de evidências a partir da coleta; `avaliar`: executar avaliadores e juiz sobre as evidências |
| revisao | `exportar`: projetar a revisão prioritária em JSON/XLSX; `decidir`: registrar uma decisão; `importar`: importar o lote preenchido; `finalizar`: exportar os resultados e o painel de evidências |
| indice | Calcular o índice declarado em YAML `argos-index-dsl/v1` sobre XLSX ou CSV (e, com `--config-estatisticas`, o contexto estatístico dos relatórios); `lote`: calcular várias definições sobre a mesma base |
| auditar | Executar mapa XLSX sobre as fontes e aplicar variantes jurídicas da matriz |
| comparar | Calcular o impacto de um resultado de auditoria sobre o anterior, por auditado, e publicar o JSON de impactos |
| graficos | Gerar tabelas e gráficos analíticos e o manifesto de ativos consumido por `documento --ativos` |
| documento | Publicar Markdown avulso em DOCX/PDF; `relatorio-individual`, `relatorio-auditoria` e `anexo-evidencias` geram os documentos da auditoria |
| pipeline | Executar etapas declarativas com fingerprints, retomada e referências entre produtos |

## Matriz

Cada ação da matriz é uma operação própria, só com os seus parâmetros (a ajuda de `argos matriz` lista as seis;
a de `argos matriz publicar` mostra as flags da publicação). `tipo` (`planejamento`, padrão, ou `achados`)
existe em `init`, `validar` e `publicar`; `rascunho` é só de achados; `mapa` e `arvore` são só de planejamento.

    argos matriz init --tipo planejamento
    argos matriz init --tipo achados
    argos matriz validar matriz_planejamento.md --strict
    argos matriz publicar matriz_planejamento.md --config-layout layout-matriz.yml --pdf --html-output matriz.html
    argos matriz mapa matriz_planejamento.md --config-fontes fontes.yml --output mapa-draft.xlsx
    argos matriz arvore --mapa mapa-revisado.xlsx --questionario questionario.md --output arvore.html
    argos matriz rascunho resultado_auditoria.json
    argos matriz validar matriz_achados.md --tipo achados --strict
    argos matriz publicar matriz_achados.md --tipo achados --template .templates/matriz-achados.docx --pdf
    argos matriz publicar matriz_achados.md --tipo achados --resultado-auditoria resultado_auditoria.json --pdf

`publicar` valida o Markdown antes de gerar o DOCX; o destino padrão é `<input>.docx` (o PDF, com `--pdf`, tem o
mesmo nome). `rascunho` grava `matriz_achados.md` ao lado do resultado da auditoria.

`init` cria `matriz_planejamento.md` ou `matriz_achados.md` na raiz do projeto;
use `--output outro/caminho.md` para escolher o destino. Os dados gerais vêm de
`fiscalizacao.yml`; o conteúdo editorial contém marcadores `[PREENCHER: ...]`,
IDs de exemplo e os percentuais padrão das colunas. Substitua os marcadores e
adapte os códigos de questionário/regras antes de publicar. O destino deve ser
novo, inclusive com `--force`. A inicialização dispensa entrada, resultado de
auditoria e template DOCX; o draft a partir de resultados é a ação `rascunho`.

As matrizes de planejamento e de achados começam com front matter YAML contendo
`title`, `fiscalizacao`, `jurisdicionados` e `objetivo_auditoria`; os quatro
valores são obrigatórios no próprio arquivo e prevalecem sobre o cadastro do
projeto. Consulte as especificações ligadas abaixo para a sintaxe completa.
Para controlar a distribuição das colunas, declare `larguras_colunas_percentuais`
no front matter com as seis chaves do tipo da matriz e soma exata de 100. Sem o
campo, o Argos preserva as larguras do template. Os exemplos completos com mapas
estão nas especificações e são distribuídos por `argos init`.

O planejamento segue como Markdown autoral. Para achados, o primeiro comando
cria um draft determinístico; após a revisão, a publicação lê somente o
Markdown, o template e os metadados efetivos — o front matter local prevalece
por campo sobre `fiscalizacao.yml`. O parâmetro `--resultado-auditoria` é **opcional**:
sem ele o DOCX/PDF é editorial, com os seis blocos aprovados; com ele, o Argos
valida o JSON do resultado (`argos.audit-result/v2` ou `/v1`; ver
[formato](docs/ESPECIFICACAO_RESULTADO_AUDITORIA.md)) e acrescenta contagens e vínculos por
auditado. JSON inválido ou incompatível falha sem fallback.

O template institucional de achados precisa ser declarado em `templates.matriz_achados`
no `fiscalizacao.yml` ou informado com `--template`; colocar o arquivo em `.templates/`
não o registra. Ele precisa conter a tabela de seis colunas. `argos init` distribui
apenas o template de planejamento, que já vem registrado no cadastro.

`--config-layout` (só `--tipo planejamento`) é opcional e controla apenas o espaçamento visual dos critérios. Por padrão, cada parágrafo usa 60 twips; exceções podem ser declaradas por ID de questão:

```yaml
criterios:
  espacamento_apos_twips: 60
  espacamento_apos_por_questao:
    Q1: 40
```

Os identificadores compactados e referências exibidos no DOCX são uma projeção de apresentação; o Markdown, o mapa draft e a execução de auditoria mantêm os IDs canônicos.

O mapa produzido pela matriz é um draft e precisa de revisão antes de orientar a auditoria. Ele reúne as ações de verificação, os procedimentos e as regras de situação que o `auditar` executa; as fontes físicas e os vínculos de campo são declarados em `--config-fontes` de `matriz mapa` ([modelo](docs/configuracoes/fontes-mapa.example.yml)). O PDF requer Microsoft Word no Windows ou LibreOffice disponível no ambiente.

Consulte a [especificação completa do Markdown da matriz de planejamento](docs/ESPECIFICACAO_MARKDOWN_MATRIZ_PLANEJAMENTO.md)
para todos os atributos, rastreabilidade, critérios estruturados, variantes por
público, regras de identificação e exemplos de preenchimento.
Consulte também a [especificação completa do Markdown da matriz de achados](docs/ESPECIFICACAO_MARKDOWN_MATRIZ_ACHADOS.md)
para conhecer todos os atributos e o ciclo draft → revisão → DOCX/PDF.
O [contrato unificado v1.3](docs/ESPECIFICACAO_UNIFICADA_MATRIZES_V1_3.md)
detalha os metadados, os dois modos de publicação e o enriquecimento pelo JSON.
Um [draft integral de exemplo](docs/exemplos/matriz_achados_draft.md) mostra os
marcadores de causas e efeitos que a equipe deve completar, e o
[exemplo normativo](docs/exemplos/matriz_achados_v1_3.md) mostra o arquivo
revisado. A faixa superior de cada achado ocupa a matriz inteira;
`situacao_encontrada` preenche a primeira coluna com a narrativa revisada.

## Survey e coleta

O objeto `survey` tem três ações, cada uma com os seus parâmetros (`argos survey <ação> --help`):

- `survey gerar` valida o SurveyMD e gera o LSS (`<questionario>.lss`); `--guia` gera também o guia DOCX, e `--pdf`, o PDF do guia;
- `survey coletar` baixa pela API as respostas e os anexos de um survey publicado;
- `survey baixar-anexos` baixa os anexos listados em um XLSX de respostas já exportado.

Gerar LSS, guia para respondentes e PDF:

    argos survey gerar questionario.md --guia --pdf

Coletar respostas e anexos de um survey publicado:

    argos survey coletar --survey-id 123456 --output-dir 02-Execucao/01-Coleta --coluna-auditado firstname

Baixar os anexos de um XLSX exportado do LimeSurvey:

    argos survey baixar-anexos respostas-exportadas.xlsx --output-dir 02-Execucao/01-Coleta/anexos --manifesto-output manifesto-anexos.xlsx

Cada pasta de `--output-dir` representa um survey: o snapshot bruto fica em `exportacoes_brutas/`, os anexos correntes em `auditados/<auditado>-r<id>/` (`respostas.pdf` e `evidencias.zip`) e as versões antigas em `auditados/.versoes/`. O manifesto de cada execução é imutável e o `manifesto-geral.xlsx` é um índice derivado. Anexos são reutilizados por fingerprint da resposta e SHA-256; `--refresh` força nova consulta sem perder a deduplicação. `--extract` é desativado por padrão e, quando ativado, extrai para `derivados/` ou para `extract_dir`; `--nome-consolidado` escolhe o nome-base das cópias consolidadas das respostas.

A coleta usa credenciais de ambiente (`LIMESURVEY_PHPSESSID` e `LIMESURVEY_YII_CSRF_TOKEN`); `--dry-run` valida localmente sem rede. Consulte a [especificação completa do SurveyMD v1](docs/SURVEYMD_V1.md) para gramática, atributos, aliases, condições e exemplos executáveis.

Preparar o survey de comentários do gestor (contraditório) a partir do resultado da auditoria:

    argos contraditorio preparar --resultado-auditoria resultado-auditoria.json \
      --config-comentarios comentarios.yml --lss-output comentarios.lss \
      --anexos-output anexos-comentarios.zip --template-anexos modelos/anexo-comentarios.docx \
      --questionario questionario.md --ajustes ajustes-evidencias.xlsx --data-final 31/12/2026

`--sem-lss` e `--sem-anexos` omitem um dos dois produtos.

## Avaliações e revisão humana

Há dois caminhos: a avaliação de evidências (`catalogo`, `evidencias` e `revisao`) e a dos comentários do gestor.

1. **Evidências**, a partir do questionário, das respostas e da raiz de anexos:

        argos evidencias avaliar \
          --catalogo catalogo-evidencias.yml \
          --questionario questionario.md \
          --respostas respostas.xlsx \
          --raiz-evidencias 02-Execucao/04-Evidencias \
          --avaliadores gemini:gemini-2.5-pro:equipe-v1 \
          --output avaliacao.json

   O catálogo de avaliações e a árvore de evidências têm ações próprias, sem chamar modelos:

        argos catalogo gerar questionario.md --id ID --output catalogo.yml
        argos catalogo validar catalogo.yml
        argos catalogo aprovar catalogo.yml --revisor "Equipe" --output catalogo.aprovado.yml
        argos catalogo prompts catalogo.aprovado.yml --questionario questionario.md --output-dir prompts/
        argos evidencias preparar --coleta 02-Execucao/01-Coleta --respostas respostas.xlsx \
          --output-dir 02-Execucao/04-Evidencias --output preparo.json

   `catalogo gerar` liga cada upload à questão indicada no `visible_if` do questionário. Os avaliadores só se declaram por `--avaliadores` (obrigatório); não há avaliador padrão.

2. **Comentários do gestor**, na fase de contraditório:

        argos contraditorio avaliar --escopo ambos \
          --catalogo catalogo-comentarios.yml --config-comentarios comentarios.yml \
          --comentarios comentarios.xlsx --raiz-evidencias anexos/ --lss comentarios.lss \
          --resultado-auditoria resultado-auditoria.json --mapa mapa.xlsx \
          --ajustes ajustes-evidencias.xlsx --questionario questionario.md \
          --avaliadores gemini:gemini-2.5-pro:equipe-v1 \
          --output contraditorio.json

   `--escopo` escolhe as situações (`situacao`, seção 1), os itens (`item`, seção 2) ou as duas (`ambos`, o padrão), sempre num único documento `argos.evaluation/v1` com `fase: contraditorio`. Com `ambos`, as duas seções têm um plano só: `--preflight` informa as duas e o total sem chamar modelo, e `--max-model-requests` vale para a soma, antes de qualquer chamada. `--situacoes` filtra a seção 1 e leva as questões dessas situações para a seção 2. Com `--mapeamento mapeamento.yml` (`response_sources` e `compatible_items`; [modelo](docs/configuracoes/mapeamento-comentarios.example.yml)) e `--respostas base-atual.xlsx` (a base de respostas atual do questionário; `--comentarios` é o XLSX exportado do survey de comentários), os itens que a seção 1 restaurou com segurança (parecer de prioridade já revisada, fonte e item compatíveis) saem da seção 2, e o resumo traz `safe_restoration_proposals` e `mapping_pending`; os dois parâmetros vêm juntos e só valem com `--escopo ambos`.

O catálogo de avaliações (prompts) é uma fonte mantida pela equipe no formato `argos.prompt-catalog/v2` ([sintaxe completa](docs/CATALOGO_AVALIACAO.md); [modelo mínimo](docs/configuracoes/prompt-catalog.example.yml); [modelo completo](docs/configuracoes/prompt-catalog-lgpd.example.yml)). Ele declara, por coluna de evidência, os itens avaliáveis, as asserções que definem o escopo, os critérios de conformidade e de não conformidade e se a entrada gera achado. Os critérios são autorais: o Argos valida estrutura, escopo e schema, mas não inventa critério. Para provedor remoto, o catálogo precisa ser aprovado no workspace, com hash do arquivo exato.

Cada caso recebe `min_opinions` avaliadores independentes e é consolidado por um juiz:

    argos evidencias avaliar --catalogo catalogo-evidencias.yml \
      --questionario questionario.md --respostas respostas.xlsx \
      --raiz-evidencias 02-Execucao/04-Evidencias \
      --avaliadores gemini:gemini-2.5-pro:equipe-v1 \
      --avaliadores gemini:gemini-2.5-flash:equipe-v1 \
      --provider-juiz gemini --modelo-juiz gemini-2.5-pro \
      --preflight

O juiz recebe as opiniões anonimizadas e os mesmos critérios e anexos, e a decisão dele é a decisão efetiva. Ele pode usar o mesmo provider e modelo de um avaliador. A maioria estrita é registrada por item; quando o juiz diverge da maioria ou não há maioria, o item entra na revisão prioritária. Quórum insuficiente não produz conclusão: o caso fica pendente.

`--preflight` planeja sem chamar modelo e informa pedidos novos e teto de juiz; com providers remotos, verifica a mesma aprovação do catálogo de avaliações exigida na execução. A aprovação registrada pelo Argos acompanha o conteúdo, o revisor e a data, mesmo após renomear o YAML ou descartar seu produto com `controle limpar`. `--max-model-requests` limita o lote; `--questoes`, `--auditados` e `--casos` restringem o escopo. A revisão humana é exportada e importada nos próprios papéis de trabalho, e cada linha identifica a execução, o caso e o item avaliados:

Os anexos seguem limites parametrizáveis, iguais para todos os providers: `--max-paginas-pdf` (padrão 100), `--min-bytes-imagem` (5120, imagens derivadas), `--max-imagens-requisicao` (50), `--max-linhas-planilha` (1000) e `--limite-tokens provider=N` (padrão Gemini 1M; OpenCodeGo, `openai-proxy` e OpenRouter 400k; `0` desliga). Providers remotos: `gemini`, `opencodego`, `opencodego-ant` (o mesmo gateway pelo protocolo Messages da Anthropic, com PDF nativo, e o único que serve o `claude-haiku-5-5`; usa a mesma `OPENCODEGO_API_KEY`, o endereço `ARGOS_OPENCODEGO_ANT_BASE_URL` e o limite de resposta `ARGOS_ANTHROPIC_MAX_TOKENS`, padrão 32000; aceita `@low`, `@medium`, `@high`, `@xhigh` e `@max`; limite de tokens padrão 200k), `openai-proxy` (OpenAI por um proxy compatível, padrão `http://127.0.0.1:8787/v1`) e `openrouter`, com chaves `GEMINI_API_KEY`, `OPENCODEGO_API_KEY`, `OPENAI_API_KEY` (opcional em endereço local) e `OPENROUTER_API_KEY` no ambiente ou no `.env`. PDFs viram texto por página para providers sem PDF nativo, com OCR do Tesseract só nas páginas sem camada de texto (`--ocr false` desliga; instale o executável `tesseract` e os dados do idioma português, `tesseract-ocr-por`, e use `ARGOS_OCR_LANG` para outro idioma), DOC/PPTX/ODS passam pelo LibreOffice, e RAR e atalhos `.url` de domínios `.gov.br` são aceitos. **Um anexo que não pôde ser preparado bloqueia a requisição daquele caso** e o motivo é registrado; truncamentos não bloqueiam e são informados ao modelo. O pré-voo lista bloqueios, estimativa de tokens e truncamentos. O nível de raciocínio é definido por avaliador e para o juiz com o sufixo `@nivel` (`--avaliadores openai-proxy:gpt-6-luna:a@max`, `--modelo-juiz gpt-6-luna@xhigh`); `--nivel-raciocinio` é o padrão de quem não tem sufixo, e o provider recusa antes da chamada o nível que não suporta.

    argos revisao exportar --run-id ID_DA_EXECUCAO --formato xlsx --output revisao.xlsx
    argos revisao importar revisao.xlsx
    argos revisao decidir --run-id ID --caso "ORG|Q1" --item Q1 --identidade-revisao ... --identidade-semantica ... \
      --acao confirmar --justificativa "Parecer do juiz conferido" --revisor "Equipe"
    argos revisao finalizar --run-id ID_DA_EXECUCAO --output final.xlsx --formato xlsx
    argos revisao finalizar --run-id ID_DA_EXECUCAO --painel-output painel-avaliacao-evidencias.xlsx

Na coluna `action` do lote (e em `--acao`), os valores são `confirmar` (mantém a decisão do juiz), `substituir` (troca a decisão; exige `replacement_decision` e `rationale`) e `adiar` (mantém o item pendente). A revisão vale para qualquer execução, de evidências ou de contraditório, pelo `run_id`. A finalização é recusada enquanto houver item prioritário sem decisão registrada. `--painel-output` grava, junto ou no lugar de `--output`, o painel de avaliação de evidências, a fonte `aevi:` das regras da matriz: uma linha por auditado, uma coluna por `item_code` do catálogo (na ordem dele) e as colunas `__resposta_afirmada`, `__decisao` e `__justificativa`. A célula do item recebe `Não conforme` quando o parecer efetivo é `nao_fundamentada` ou `parcialmente_fundamentada` (`--criterio-painel parcial`, padrão) ou só `nao_fundamentada` (`estrito`); pareceres favoráveis, inconclusivos e itens não avaliados ficam vazios. O catálogo e as respostas vêm da própria execução (`--catalogo` e `--respostas` os substituem). Uma resposta de avaliador que viola o contrato (por exemplo, `fundamentos` fora do formato ou vazio numa decisão favorável) não conta para o quórum; `--max-correcoes-avaliadores 1` ou `2` devolve ao avaliador o erro do validador e pede nova resposta (cada correção é outra chamada, somada ao teto do pré-voo; padrão 0). Chamadas cujo resultado ficou `unknown` (timeout ou erro de transporte) só são reenviadas com `--retry-unknown`, que pode cobrar de novo no provider; `--retry-failed` continua cobrindo apenas falhas confirmadas. O cache semântico evita chamadas idênticas: mover arquivo ou recriar ZIP não repete a avaliação, mas alterar critério, prompt ou anexo gera nova identidade. Credenciais de IA vêm de variáveis de ambiente.

Depois de revisar as prioridades (`revisao`), `contraditorio consolidar` propõe ajustes, produz o contexto do relatório e limpa o painel de evidências apenas nas células seguras (tudo em draft):

    argos contraditorio consolidar --respostas base-atual.xlsx --ajustes ajustes-evidencias.xlsx \
      --mapeamento mapeamento.yml --execucao-situacoes ID_DA_EXECUCAO --execucao-itens ID_DA_EXECUCAO \
      --painel painel.xlsx --painel-output painel-pos-comentarios.xlsx \
      --ajustes-output propostas.xlsx --contexto-output contexto-comentarios.json

`contraditorio projetar --contexto contexto-comentarios.json --scenario CENARIO_FILHO --contexto-output contexto-aplicado.json` projeta o contexto pelos ajustes aprovados e aplicados no cenário derivado (com `--painel` e `--painel-output`, também o painel).

## Ajustes e cenários

    argos ajustar \
      --respostas respostas-base.xlsx \
      --ajustes ajustes-iniciais.xlsx \
      --output respostas-01.xlsx \
      --scenario-id 01-pos-ajuste-inicial

A base original permanece intacta. O cenário gerado registra seu pai e os valores aplicados. A sequência comum é `base → 01-pos-ajuste-inicial → 02-pos-avaliacao-evidencias → 03-pos-comentarios-gestor`; cada geração seguinte declara explicitamente seu cenário.

## Índices e auditoria

    argos indice \
      --memoria docs/index-dsl-v1/exemplos/ilgpd-2026.yaml \
      --respostas respostas.csv \
      --output ilgpd.json \
      --rastreio-output ilgpd-rastreabilidade.json
    argos auditar \
      --base-auditados bd_auditados.xlsx \
      --mapa mapa-verificacao.xlsx \
      --matriz matriz_planejamento.md \
      --fontes respostas-03.xlsx \
      --mapa-fontes questionario=respostas-03.xlsx \
      --output resultado-auditoria.json

`argos indice` calcula uma definição por vez; `argos indice lote --memorias lote.json --respostas respostas.csv [--jobs N] [--output combinado.json] [--xlsx-output combinado.xlsx]` calcula várias sobre a mesma base, lendo a planilha uma vez (o descritor do lote está na especificação da DSL). `--memoria` recebe uma definição `argos-index-dsl/v1`. Ela declara conversores,
regras, referências, operações e faixas de maturidade; o Argos não escolhe uma
metodologia pelo nome do índice. Um desconto só é aplicado quando a definição
declara a operação correspondente. A configuração de estatísticas e comparação
para relatórios é um YAML separado `argos.report-config/v1`, informado por
`--config-estatisticas` junto com `--contexto-output` ou `--contexto-json-output`.

Consulte a [especificação completa da DSL de índices](docs/ESPECIFICACAO_ARGOS_INDEX_DSL_V1.md)
para estrutura YAML, fórmulas, seletores, regras de entrada, execução em lote
e exemplos de configuração. Os exemplos integrais ficam em
[docs/index-dsl-v1/exemplos](docs/index-dsl-v1/exemplos/).

O resultado JSON contém todos os nós, a raiz, a classificação, estatísticas e
hashes dos insumos. JSON, XLSX e CSV exportam os escores; `--rastreio-output`
adiciona um produto explicativo sem copiar as respostas brutas. Consulte o
[contrato dos resultados e erros](docs/INDEX_DSL_V1_RESULTADOS.md).

Em `auditar`, `--fontes` aceita várias fontes e `--mapa-fontes id=caminho` associa cada id lógico usado no mapa ao arquivo físico; é o mecanismo que liga o painel de avaliação de evidências às regras de situação. `--validar-insumos` valida os insumos canônicos antes de executar (com `--exportacao-survey`) e pode publicar o relatório da validação em `--validacao-output`. `--expandido-output` grava a visão expandida (v1) e `--tabelas-output` as tabelas consolidadas. A aplicabilidade jurídica é resolvida por auditado a partir das variantes declaradas na matriz.

Comparar resultados anterior e atual, opcionalmente associados a cenários já registrados (`comparar` lê os dois arquivos do disco):

    argos comparar \
      --resultado-anterior auditoria-base.json \
      --resultado-auditoria resultado-auditoria.json \
      --output impactos.json \
      --cenario-anterior base \
      --cenario-atual 03-pos-comentarios-gestor

O JSON de impactos (`argos.audit-impact.v1`) é o `--impactos` dos relatórios e dos gráficos.

## Relatórios e pipeline

    argos documento relatorio-individual \
      --resultado-auditoria resultado-auditoria.json \
      --template relatorio.md \
      --output-dir relatorios/
    argos documento relatorio-auditoria \
      --resultado-auditoria resultado-auditoria.json \
      --template consolidado.md \
      --output relatorio-auditoria.docx
    argos documento anexo-evidencias \
      --resultado-auditoria resultado-auditoria.json \
      --output anexo-evidencias.docx

`argos documento` é o objeto de toda saída DOCX/PDF de texto corrido, e cada ação tem só os seus parâmetros (`argos documento --help` lista as ações). Os modelos podem vir do cadastro: `templates.relatorio_individual`, `templates.relatorio_consolidado` e `templates.anexo_evidencias`. O motor verifica a proveniência do resultado e do cenário antes de renderizar. `--config-publicacao` compõe o corpo num modelo DOCX institucional com slots declarativos; consulte a [especificação da publicação](docs/ESPECIFICACAO_PUBLICACAO_RELATORIOS.md).

Um Markdown avulso também é um documento: `argos documento nota.md` o renderiza como template Jinja (com `--contexto` e `--fontes-contexto` opcionais, e campos `[[secao.chave]]` do cadastro) e publica `nota.docx`; `--pdf` gera também `nota.pdf` (exige Word ou LibreOffice). Variável indefinida no template interrompe a geração e cita o nome.

`--ativos` (repetível) inclui as imagens de manifestos `argos.asset-manifest/v1`, gerados por `argos graficos` ou por scripts do pipeline, nas três ações de texto corrido e em `documento`.

Um pipeline pode vir de JSON/YAML ou da seção pipeline em fiscalizacao.yml. Cada etapa usa um ID do catálogo de operações:

    argos pipeline --plan-file pipeline.json --dry-run
    argos pipeline --plan-file pipeline.json --until-stage auditoria
    argos pipeline --plan-file pipeline.json --from-stage relatorio

As referências {"$stage": "auditoria", "kind": "audit-result"} consomem o caminho realmente publicado pela etapa anterior. Entradas alteradas produzem fingerprints novos; status identifica produtos antigos como desatualizados. Ativos produzidos por scripts externos seguem o [contrato de scripts no pipeline](docs/PIPELINE_SCRIPTS.md).

## Analítica genérica

    argos graficos --resultado-auditoria resultado_auditoria.json \
      --avaliacoes avaliacao-evidencias.json --avaliacoes avaliacao-contraditorio.json \
      --output-dir analises
    argos documento relatorio-auditoria --resultado-auditoria resultado_auditoria.json \
      --template consolidado.md --output relatorio-auditoria.docx --ativos analises/manifest.json

As avaliações são opcionais e devem declarar `fase=evidencias` ou `fase=contraditorio`. Consulte [docs/ANALYTICS_CONTRACT.md](docs/ANALYTICS_CONTRACT.md).

## Dados e compatibilidade

O SQLite corrente guarda identidade do workspace, cenários, execuções/eventos, produtos e cache semântico de IA. Os bytes dos produtos ficam em arquivos, com proveniência SHA-256 registrada no banco.

Esta versão de desenvolvimento usa um schema novo e não migra bancos anteriores nem importa ou preserva seu acervo de avaliação. O comportamento ao abrir um banco v1 não é garantido; crie um workspace novo para esta versão. Não há instalação em produção que exija retrocompatibilidade.

## Documentação e skills

Especificações canônicas:

- [Arquitetura](docs/arquitetura.md) — módulos, ciclo de execução, cenários, persistência e adapters, com diagramas Mermaid das camadas e do fluxo de avaliação.
- [SurveyMD v1](docs/SURVEYMD_V1.md) — gramática e semântica do questionário.
- [Matriz de planejamento](docs/ESPECIFICACAO_MARKDOWN_MATRIZ_PLANEJAMENTO.md) e [matriz de achados](docs/ESPECIFICACAO_MARKDOWN_MATRIZ_ACHADOS.md).
- [Contrato unificado das matrizes v1.3](docs/ESPECIFICACAO_UNIFICADA_MATRIZES_V1_3.md).
- [Contexto de relatórios](docs/ESPECIFICACAO_CONTEXTO_RELATORIOS.md) e [publicação de relatórios](docs/ESPECIFICACAO_PUBLICACAO_RELATORIOS.md).
- [Index DSL v1](docs/ESPECIFICACAO_ARGOS_INDEX_DSL_V1.md) e [contrato dos resultados](docs/INDEX_DSL_V1_RESULTADOS.md).

Guias e exemplos:

- [Contrato analítico](docs/ANALYTICS_CONTRACT.md) e [scripts no pipeline](docs/PIPELINE_SCRIPTS.md).
- [Configurações de exemplo](docs/configuracoes/) — catálogo de avaliações, fontes do mapa, comentários do gestor e mapeamento.
- [Exemplos de matrizes](docs/exemplos/) e [exemplos do Index DSL](docs/index-dsl-v1/exemplos/).

`skills/` é a fonte das quatro skills distribuídas por `init` para `.agents/skills/`: `criar-matriz-planejamento`, `elaborar-survey-limesurvey`, `operar-argos` e `verificar-diretrizes-fiscalizacao`.

## Desenvolvimento e verificação

O CI constrói uma distribuição única (`argos-cli-dist`) e instala seu wheel em
venvs novas no Linux e no Windows, com Python 3.10, 3.12 e 3.14. Os testes são
copiados para uma pasta temporária fora do checkout. A verificação inclui o
executável `argos`, catálogo de operações, bootstrap, skills com seus recursos, templates,
geração de DOCX/LSS e a suíte completa. Os testes reais de PDF continuam
condicionais à presença de Word/LibreOffice.

Para reproduzir a instalação limpa no Linux, use um diretório de trabalho novo:

    python -m build
    python .github/scripts/test_wheel.py --dist-dir dist --work-dir /tmp/argos-package-test

`dist/` deve conter exatamente um wheel. `--smoke-only` executa apenas as
verificações do pacote instalado, sem a suíte completa. No Windows, o mesmo
script funciona com um destino novo em `%TEMP%`. O wheel e o sdist ficam
disponíveis como artefato na execução do GitHub Actions; o workflow de release
publica essa mesma distribuição depois de todos os jobs aprovarem.

Execute os testes focados do módulo alterado durante a implementação. Rode os gates completos ao concluir a tarefa:

    python -m ruff check argos tests --output-format=concise
    python -m bandit --quiet --recursive argos --severity-level medium
    PYTHONDONTWRITEBYTECODE=1 python -m coverage run -m unittest discover -s tests -q
    python -m coverage report --fail-under=80
