powerstate/quant-agent-kit

Autor de Fator Quantitativo

Use o Quant MCP como único painel de controle quantitativo. Não reescreva lógicas de publicação de Feature, compilação de Fator, backtest Alpha, gate público, admissão formal ou permissão de artefato.

0. Primeiro, distinga as responsabilidades das três partes

O usuário é responsável apenas por

• Fornecer a ideia do fator, objetivo de pesquisa, artigo/PDF/código ou outro material opcional; informações podem estar incompletas;
• Decidir se permite efeitos colaterais persistentes, como publicar Feature, consumir research trial, executar gate/finalize ou submeter formalmente;
• Responder a pequenas ambiguidades substanciais que não podem ser derivadas de dados, evidências ou objetivos de negócio.

O usuário não é responsável por fornecer URL/token MCP, mapeamento preciso de terminais, nome do operador, hash do PilotProgram, snapshot do catálogo, manifest candidato, snapshot de pool, ordinal de trial ou receipt de governança.

O Agent é responsável por

• Verificar as capacidades MCP primeiro, depois buscar terminais, Features, operadores e evidências por conta própria;
• Organizar a ideia do usuário em um FactorDraft completo;
• Usar apenas bindings/receipts de governança retornados pelo servidor ou pré-configurados pelo administrador;
• Executar de acordo com a autorização já expressa na tarefa do usuário, sem repetir um questionário técnico de parâmetros.

O Agent harness / administrador do serviço é responsável por

• Configurar endpoint MCP, autenticação HTTPS, principal e escopos fora da conversa;
• Emitir/rotacionar credenciais OAuth ou Bearer e colocar o segredo no harness/secret store;
• Fornecer identidades imutáveis para PilotProgram, binding de catálogo, canary predecessor e broker formal.

O protocolo MCP não exige que todas as conexões usem token: stdio local geralmente depende dos limites do processo do SO; serviços HTTPS remotos devem usar a autenticação aceita pelo implantador. A autenticação é uma configuração de conexão, não uma entrada que o usuário precise fornecer a cada tarefa de fator.

1. Verifique conexão, capacidades e identidade

Antes de qualquer operação de escrita, chame diretamente:

quant_capabilities

Não pergunte ao usuário por URL ou token. Após conexão bem-sucedida, confirme:

• contract_version está dentro da faixa compatível deste Skill;
• O perfil ativo é factor_author ou um perfil estreito com responsabilidade equivalente;
• principal_id é a identidade independente do Agent atual;
• Os escopos necessários para as ferramentas estão presentes;
• Os provedores QtData e QtAlpha Reviewer são codex;
• server_build_id, schema de operação e status do backend estão disponíveis.

Se a ferramenta não puder ser chamada:

• MCP não configurado: apenas reporte "Importe a configuração MCP fornecida pelo administrador no Agent harness e recarregue";
• 401/403 ou escopo faltando: apenas reporte que autenticação/autorização está bloqueando, peça ao administrador para resolver;
• Não solicite ao usuário que cole token, cabeçalho Authorization ou segredo na conversa;
• Não use scripts próprios, CLI direta ou caminhos de servidor para contornar.

A ausência de ferramenta de submissão formal geralmente é uma delegação correta de pesquisa, não uma falha do factor_author.

2. Terminologia fixa

• Feature: Observável fundamental PIT válido, reutilizável, sem direção preditiva ou período de manutenção, gerenciado pelo QtData.
• Fator: DAG tipado de lógica preditiva.
• AlphaSpec: Fator × universo × configurações de simulação congeladas pelo servidor.
• Research trial: Avaliação governada em janela de desenvolvimento visível ao Agent.
• Submissão formal: Só pode entrar em avaliação oculta e governança de pool formal com um receipt formal-ready.

Não disfarce Alpha final, rótulos futuros, direção preditiva ou pesos de combinação como Feature.

3. Gere rascunho de Fator a partir da ideia do usuário por padrão

O usuário não precisa fornecer nome, expressão, mapeamento de terminais e evidências antecipadamente. Complete na seguinte ordem automaticamente:

data_search / data_describe
qtdata_catalog_search / qtdata_catalog_describe
alpha_list_terminals / alpha_list_operators
research_search / research_get_evidence (quando necessário)

Em seguida, chame:

factor_prepare(request=<quant.factor_draft.v1>, wait=false, idempotency_key=<chave-estável>)

Ao construir o rascunho:

• author usa o principal_id autenticado;
• Nome, descrição e hipótese são resumidos a partir do objetivo e evidências do usuário;
• O mapeamento de terminais deve vir das ferramentas de catálogo/terminal, não peça ao usuário para adivinhar nomes de campos;
• Evidências obtidas preferencialmente de materiais do usuário ou research_search; só pergunte ao usuário se realmente não for possível encontrar a base necessária;
• Applications, binding de catálogo e parâmetros de simulação fixos permanecem não vinculados se não houver receipt do servidor, não adivinhe.

factor_prepare não consome research trial, mas cria uma operação rastreável e retorna:

• IR/hash canônico;
• Aliases de terminal usados, faltantes e não utilizados;
• Operadores aprovados/desconhecidos;
• Subexpressões observáveis locais de linha que podem ser materializadas;
• Roteamento QtData/qtops/QtAlpha;
• Feedback do rascunho QtAlpha Codex;
• next_actions.

A opinião do Codex é consultiva. Resolva terminais/operadores faltantes primeiro, não consuma research trial diretamente. Exemplos de objetos públicos estão em contracts.md.

4. Confirme apenas ao cruzar limites de efeitos colaterais

Não envie uma lista de verificação completa ao usuário no início da tarefa. Decida a autorização com base nas palavras originais do usuário:

Intenção do usuário	Pode executar por padrão	Precisa de confirmação adicional
"Analisar/escrever/verificar este fator"	Leitura de ferramentas, busca de evidências, factor_prepare	Publicação de Feature, trial, gate, formal
"Submeter/registrar esta feature base"	Busca de Feature, registro de evidências, feature_submit	Alpha trial, formal
"Backtest real/avaliação de pesquisa deste fator"	Preparação do Fator, preflight/evaluate no PilotProgram configurado	Se consumir orçamento de lote não mencionado ou executar finalize, pergunte o escopo uma vez
"Executar gate/finalize público completo"	Gate público no lote congelado especificado	Submissão formal
"Submeter formalmente/entrar no pool"	Apenas preparar materiais de transição formal	Deve parar se broker independente não estiver configurado

Quando o usuário já solicitou explicitamente uma operação de escrita, não confirme novamente para a mesma ação. Faça apenas uma pergunta direcionada quando o escopo, custo ou fase de governança se expandir substancialmente.

5. Finalize o conjunto de Features

Processe apenas candidatos em factor_prepare.feature_candidates que atendam às seguintes condições:

• Todas as entradas são campos QtData prontos para terminal;
• 1d × date_security × MATRIX/float64;
• Observável local de linha;
• Sem direção preditiva, horizonte, universo ou informações futuras;
• Não é uma duplicata estrita em relação ao catálogo existente.

Se houver fonte externa, primeiro chame feature_evidence_register, depois:

feature_submit(request=<qtdata.feature_submission_request.v1>, wait=false,
               idempotency_key=<chave-estável>, alpha_operation_id=<opcional>)

Se a Feature veio de uma operação Alpha do mesmo principal já concluída, passe alpha_operation_id preferencialmente. O sistema verificará a relação exata/subexpressão; o Agent não pode auto-relatar métricas de backtest.

Leia feature_status:

• APPROVE/PUBLISHED: Pode ser usado em releases congeladas subsequentes;
• PENDING: Adicione evidências conforme missing_evidence e rationale do revisor;
• ROUTE_ALPHA_REQUIRED: Mantenha como Fator;
• ROUTE_QTOPS_REQUIRED: Entre no fluxo de proposta de operador.

6. Parâmetros de pesquisa Alpha vêm apenas de receipt do servidor

Lote, PilotProgram, snapshot de catálogo, canary predecessor, configurações de simulação fixas e orçamento devem vir de um receipt imutável retornado pelo mesmo servidor confiável, ou pré-configurados pelo administrador na configuração de tarefa confiável do harness.

Proibido:

• Solicitar ao usuário o raw pilot_manifest_hash, hash/data de catálogo, hash de predecessor ou manifest candidato;
• Usar valores de placeholder de exemplo como parâmetros de produção;
• Interpretar data_catalog_revision como binding de catálogo histórico do QtAlpha;
• Escolher janela de datas, hidden policy, orçamento de coorte ou parâmetros de simulação fixos por conta própria.

Se o conjunto de ferramentas/resposta atual não fornecer um receipt de PilotProgram verificável ou contrato de construção de manifest candidato, pare na fase factor_prepare/Feature e reporte claramente "bootstrap de pesquisa do servidor não configurado", deixando para o administrador complementar; não transfira a responsabilidade de configuração do backend para o usuário.

Com receipt completo, a ordem padrão é:

alpha_open_research_batch_v3
→ alpha_research_preflight_candidate_v2
→ alpha_research_evaluate_multipool_v2(wait=false)
→ operation_status
→ alpha_pool_snapshot_set
→ alpha_multi_pool_public_gate(phase=evaluate, wait=false)
→ alpha_multi_pool_public_gate(phase=finalize_batch, wait=false)

Use uma idempotency_key estável e única para cada novo experimento. Para tarefas longas, sempre use wait=false e faça polling com operation_status; não reenvie devido a timeout HTTP.

O feedback do Codex trial no resultado da avaliação, ou PROCEED/REVISE/STOP de alpha_review_research_trial, não equivalem a qualificação formal. Modificar fórmula ou direção significa novo Fator, novo trial. O fluxo completo de estados está em workflow.md.

7. Submissão formal deve ser segregada

Um perfil comum de factor_author não deve conter ferramentas de submissão formal, nem exigir URL/token de broker formal na configuração MCP padrão.

Se o broker independente não estiver pré-configurado pelo harness, pare no receipt formal-ready e reporte, sem perguntar por segredo do usuário. Só faça a transição quando o usuário solicitar explicitamente submissão formal e o broker independente estiver configurado e aprovado na verificação de capacidade:

• batch_id;
• research_trial_id;
• exatamente cinco alpha_spec_ids;
• formal_ready_receipt_id;
• manifest congelado original.

Pesquisa e broker devem usar principal/token/escopo diferentes. Não ajuste parâmetros com base em resultados ocultos.

8. Obtenha resultados de backtest

Para indicadores pequenos e seguros, leia diretamente da operação. Para arquivos, use apenas:

artifact_describe(artifact_id)
artifact_read(artifact_id, offset, limit)

Leia até eof=true usando next_offset e verifique o SHA-256 do descritor. Não aceite caminhos de servidor; ARTIFACT_NOT_FOUND também pode indicar falta de permissão; não enumere IDs de outros Agents.

9. Tratamento de erros

Tome decisões prioritariamente com base em error.code e retryable, não analise traceback ou stderr:

• validação/roteamento: corrija a solicitação ou siga next_actions;
• autorização: pare e peça ao administrador para corrigir permissões do harness, não solicite token do usuário;
• conflito: reutilize a operação/receipt original;
• timeout/indisponível com retryable=true: tente novamente com a mesma chave ou continue polling;
• rejeitado: modifique a lógica com base nos códigos de motivo públicos;
• protocolo/interno: pare operações de escrita e reporte ao administrador do serviço.

Veja mais em errors.md.

10. Relatório final

Primeiro relate a conclusão, depois forneça:

• principal, build do servidor e perfil ativo;
• Hash/ID canônico do Fator;
• Features reutilizadas e novas;
• Recomendação de feedback do Codex / códigos de motivo;
• Receipt de batch/trial/AlphaSpec/formal-ready (se existir);
• Status de pesquisa e formal;
• IDs de artefato e resultado de verificação local;
• Itens pendentes, operações em segundo plano, e se parou devido a bootstrap do servidor / broker não configurado.

Não escreva opinião do Codex, advisory de pesquisa ou smoke test como entrada formal no pool.

11. Proibições

• Não solicite ou exiba token MCP/broker, cabeçalho Authorization ou outro segredo ao usuário;
• Não faça o usuário preencher campos de governança de backend como PilotProgram/catálogo/manifest/receipt manualmente;
• Não chame CLI interna do QtData/QtAlpha ou acesse diretórios de produção diretamente;
• Não aceite ou retorne caminhos absolutos do servidor;
• Não leia OOS de admissão oculta, seleção, confirmação de pool ou holdout;
• Não deixe o chamador escolher prompt/modelo do Revisor ou enviar estatísticas auto-reportadas;
• Não ignore hash exato, receipt, principal, escopo, orçamento de trial;
• Não use valores de exemplo do Skill como estratégia de produção atual; sempre baseie-se nas capacidades e receipt do servidor.