Lucasuiii/cumcm-workflow

Fluxo de Trabalho CUMCM

Mantenha as alegações importantes rastreáveis até fontes oficiais e execuções reais, sem transformar cada rascunho em um pacote de auditoria.

Duas regras moldam tudo abaixo:

1. As ferramentas registram fatos da máquina; você escreve o julgamento. Nunca digite um hash, uma contagem de páginas, um código de saída, um snapshot de origem ou um valor de resultado. record_run.py, index_result.py, record_compile.py e refresh_evidence.py observam isso. Você escreve os fatos do problema, o modelo, as alegações e o artigo.
2. O modelo é escolhido tardiamente, e a escolha é merecida. O modo de trabalho aceita um contrato de modelo de rascunho. Você nomeia modelos candidatos, diz quais evidências os diferenciariam, avalia-os com execuções exploratórias baratas e só então seleciona um e congela o contrato.

Iniciar ou retomar

1. Localize .cumcm/state.json. Retome um projeto exato 0.6.0. Espaços de trabalho mais antigos não são suportados; inicie um novo projeto a partir dos arquivos oficiais.
2. Se nenhum estado existir e o usuário fornecer arquivos oficiais, leia 01-intake.md, escolha um alvo seguro e execute scripts/init_project.py para eles. Não faça o usuário montar o comando.
3. Leia apenas o guia do estágio ativo mais handoffs.md ao cruzar estágios. Uma nova tarefa lê seu handoff primeiro, não o espaço de trabalho inteiro.
4. Mantenha as seis responsabilidades distintas: orquestração, modelagem, computação, validação, artigo, entrega. Não simule separação inventando muitas Skills pequenas.

Os dois botões

mode (no estado) decide o que deve estar completo. --gate-mode decide se as portas humanas contam.

• working: modelagem rápida, computação exploratória, depuração. Proteção de entrada oficial, execução real, localizadores exatos de resultados e não-fabricação são aplicados. Um contrato de modelo de rascunho é suficiente; CROSS_QUESTION_LEDGER.json é opcional; a ordem dos estágios é consultiva. enforce aqui relata working_ready, nunca uma aprovação formal.
• finalizing: congele resultados que sustentam alegações. O contrato do modelo deve estar completo e seu plano de verificação deve mapear para asserções que uma execução oficial registrou. Requer decisões e snapshots do estágio atual, handoffs frescos, revisão independente limitada, QA do artigo/PDF e vinculação de entrega. enforce não pode passar a menos que cada estágio até o solicitado esteja passed com uma decisão aceita atual.

Mude com scripts/set_mode.py. Não há perfil strict/sprint no v0.6; um conjunto único de regras se aplica.

Onde uma pessoa é consultada

Três pontos de verificação, um por bloco, e cada um registra o que foi colocado diante da pessoa, não apenas o que ela decidiu. Uma decisão sem nada apresentado não é evidência de que alguém olhou. Eles ficam diante das três etapas de custo: rejeitar uma escolha de modelo custa uma conversa, rejeitar uma conclusão custa uma recomputação, rejeitar um artigo finalizado custa uma reescrita.

• MODEL_CONTRACT.selection_check, antes de um candidato se tornar selected: o critério de julgamento, a discriminating_evidence de cada candidato e o scope que o vencedor reivindicará. presented_candidate_ids deve cobrir cada candidato (MODEL-E018) — mostrar apenas o vencedor não é uma comparação.
• CLAIM_LEDGER.conclusion_check, antes de validation-paper: as próprias conclusões — texto da alegação, scope, estado da evidência, P0/P1 abertos. Sem IDs de execução, sem hashes. presented_claim_ids deve cobrir cada alegação declarada (CLAIM-E023). Este é o lugar barato para ouvir 'não'; a mesma objeção na entrega custa um artigo reescrito.
• DELIVERY_MANIFEST.final_check, antes da submissão: o objeto finalizado — páginas renderizadas, a resposta para cada subproblema, descobertas abertas. presented_pages deve cobrir cada página renderizada (DELIVERY-E020), e human_user não é reivindicável com nada apresentado (DELIVERY-E019).

O relatório do artigo não carrega aprovações próprias: content_report e layout_report são relatórios. A seleção do revisor é registrada, não confirmada — a separação vem das duas transições de corte (references/handoffs.md).

Os status dos estágios são not_started, in_progress, passed, needs_revision.

Funções e handoffs

Responsabilidade	Referência principal	Handoff de saída
Modelagem	02-problem-analysis.md, 03-model-design.md	modeling-computation
Computação	04-computation.md	computation-validation
Validação	05-validation.md	validation-paper
Artigo	06-paper-writing.md, latex-template.md	paper-delivery
Entrega	07-compile-delivery.md	pacote final

Construa handoffs com scripts/build_handoff.py. Eles carregam caminhos canônicos, um payload downstream compacto e um digest upstream. Nunca copie logs completos, execuções falhas, histórico de depuração ou conversas antigas de revisão. Um digest desatualizado requer reconstrução.

Escolhendo o modelo

O design do modelo não escolhe um modelo. Propõe candidatos e diz como a escolha será resolvida:

"candidates": [
  {"candidate_id": "CAND-ENUM", "method": "enumeração completa",
   "why_considered": "a classe de política declarada é finita e pequena",
   "discriminating_evidence": ["se a escolha gulosa é igual ao mínimo enumerado"],
   "status": "under_evaluation"},
  {"candidate_id": "CAND-GREEDY", "method": "guloso primeiro-encaixe",
   "why_considered": "tempo constante, adequado se o conjunto já está ordenado por custo",
   "discriminating_evidence": ["se a escolha gulosa é igual ao mínimo enumerado"],
   "status": "under_evaluation"}
]

Em seguida, resolva com evidências em vez de com uma opinião:

python3 scripts/record_run.py --project <p> --candidate CAND-ENUM   -- python3 code/enum.py
python3 scripts/record_run.py --project <p> --candidate CAND-GREEDY -- python3 code/greedy.py

Defina o vencedor como status: "selected", os outros como "rejected", dê a cada um um decision_rationale que se refira ao que essas execuções mostraram e liste as execuções em evaluation_run_ids. Só então o modelo selecionado recebe uma execução oficial.

O verificador te obriga a isso: exatamente um candidato pode terminar como selected (MODEL-E013), uma seleção deve citar uma execução que a avaliou (MODEL-W014), um candidato selecionado ou rejeitado precisa de uma razão registrada (MODEL-E014) e um candidato sem nada que o diferencie é sinalizado (MODEL-W012). Em working, estes são avisos; congelar os transforma em erros. cumcm_check.py imprime a comparação sob model_candidates.

Duas coisas que isso deliberadamente não faz: não exige mais de um candidato quando um é obviamente correto (isso é MODEL-W007, um aviso) e não julga qual candidato é melhor — apenas insiste que a escolha foi feita com base em evidências registradas.

Registrando computação

# exploração não custa nada para registrar
python3 scripts/record_run.py --project <p> -- python3 code/try.py

# congelar uma execução para resultados formais custa algumas declarações
python3 scripts/record_run.py --project <p> --official \
  --capability CAP-Q1-001 --source code/solve.py \
  --input data/q1.csv:formal --output results/q1.json:claim \
  --assert "feasibility=pass" -- python3 code/solve.py

# o valor é lido da saída, nunca transcrito
python3 scripts/index_result.py --project <p> --result-id RES-Q1-001 \
  --run RUN-Q1-001 --locator results/q1.json#/minimum_cost \
  --name "Custo mínimo" --unit CNY --scope "apenas candidatos declarados"

# uma reexecução anexa um sucessor; o pai e suas evidências permanecem intactos
python3 scripts/record_run.py --project <p> --rerun RUN-Q1-001 --official
python3 scripts/index_result.py --project <p> --follow-lineage

Execuções exploratórias são registradas, nunca confiadas e nunca bloqueiam: uma asserção falha ou um código de saída diferente de zero dentro de uma é um fato sobre o experimento, não sobre a cadeia formal. Apenas uma execução bem-sucedida com official_run: true pode sustentar um resultado formal.

Execuções são somente anexação. --rerun anexa RUN-Q1-002 com parent_run_id: RUN-Q1-001; nunca sobrescreve, porque o pai é o único registro do que a execução substituída executou e produziu. Cada execução congela sua fonte declarada e saídas em runs/<id>/source/… e runs/<id>/outputs/…, espelhando o layout original, e faz hash dessas cópias — portanto, uma execução preservada permanece verificável independentemente de como o espaço de trabalho muda, e output_locator nomeia um arquivo imutável.

Uma execução só pode reivindicar o que produziu e o que verificou: o gravador compara o timestamp de cada saída declarada durante a execução e se recusa a registrar um arquivo residual como evidência de alegação desta execução, e uma reexecução nunca herda os veredictos de asserção de seu pai. Apenas uma reexecução oficial bem-sucedida substitui seu pai, e todo consumidor formal resolve a execução atual através do mesmo código.

Isso não enfraquece a detecção de desvio, ela a aguça. RUN-E020 agora compara a cópia congelada com o arquivo vivo e diz que a árvore de trabalho evoluiu desde a execução que sustenta seus resultados; execuções substituídas são isentas, e alterar uma cópia congelada é RUN-E021. A substituição é derivada da cadeia pai e nunca escrita de volta — carimbar o manifesto antigo mudaria seu hash e tornaria obsoleta toda decisão vinculada a ele. RESULT-E017 detecta um resultado que ainda cita uma execução substituída; index_result.py --follow-lineage o redireciona, explicitamente, porque qual execução sustenta uma alegação é julgamento, não um fato de máquina.

Escolhendo um backend

O estado do projeto padrão é {"preferred":"matlab","fallback":"python","selection":"auto"}. Use scripts/backend_selection.py ou os mesmos critérios: métodos numéricos, otimização, EDO/EDP, processamento de sinais, limpeza de dados, Excel/CSV, aprendizado de máquina, toolboxes disponíveis, código existente, complexidade, estabilidade de tempo de execução. A preferência por MATLAB desempata apenas. Um backend preferido indisponível pode recorrer ao fallback; um required_backend de tarefa indisponível deve falhar. Implemente e execute oficialmente uma linguagem. Não construa implementações paralelas a menos que o usuário peça.

Portas de evidência

• invariante forte / P0: dados ou computação errados, incompatibilidade de tarefa (uma capacidade que ninguém assumiu, ou uma ainda inacabada quando o artigo se autodenomina final, é a metade visível pela máquina disso: CAP-E013, CAP-E014), uma alegação cujo escopo declarado excede o intervalo realmente verificado, discordância entre código/resultado/artigo, uma suposição contradizendo uma condição declarada, proveniência desatualizada, aprovação ou revisão fabricada, dados simulados apresentados como observados, incompatibilidade de versão final. Isso bloqueia.
• aviso / P1, julgado dentro do intervalo verificado: suposições fortes, baseline fraco, validação ou sensibilidade mais fina que o ideal, ajuste limitado, seção fina. Visível, nunca bloqueia.
• sugestão / P2: redação, layout, gráfico opcional, experimento extra. Não está na porta.

A validação independente usa accepted, accepted_with_concerns, revision_required, inconclusive. Apenas um P0 aberto permite revision_required. Após uma revisão completa encontrar problemas P0, o próximo pacote padroniza para uma re-revisão direcionada exatamente dessas descobertas.

O pacote de revisão copia apenas evidências canônicas para resultados indexados formalmente e registra context_excluded — o raciocínio anterior que fisicamente deixou de fora. Não afirma que o revisor não tem opinião. O modelo de resultado deixa cada campo de independência como null: o revisor deve afirmá-los, e um null falha IREVIEW-E027. O usuário não confirma mais o revisor; a separação vem do corte — computation-validation e validation-paper carregam a tarefa que os construiu, e uma tarefa consumidora que corresponde é HANDOFF-E010. Veja references/handoffs.md.

Iterando

Reabrir um estágio upstream é um comando, não uma edição manual de state.json:

python3 scripts/record_decision.py --project <p> --stage model-design \
  --decision revision_requested --decision-id DEC-007 --reviewer <name> \
  --task-turn-ref <ref> --summary "O modelo Q2 não se ajusta ao regime observado"

Isso invalida o estágio e tudo downstream. Para descobrir o que uma mudança realmente custa antes de refazer qualquer coisa:

python3 scripts/plan_redo.py --project <p> --changed code/solve_q2.py

plan_redo.py percorre source -> official run -> result -> claim -> section -> PDF e nomeia as execuções, descobertas e seções específicas que são afetadas — e as que não são. Nunca suprime uma verificação; cumcm_check.py ainda valida tudo até o estágio solicitado, porque isso é barato. O trabalho caro é reexecutar, re-revisar e reescrever, e é isso que o plano escopa.

Invariantes da competição

• Preserve e identifique por byte as fontes oficiais. OCR direciona a atenção; páginas renderizadas decidem fórmulas, tabelas e notação ambígua.
• Nunca invente dados observados, aprovações, revisão independente ou execução bem-sucedida. Rotule simulações genuínas e registre seu gerador e semente.
• Mantenha o modelo matemático e os contratos de resultado neutros em termos de linguagem.
• Use SHA-256 apenas para identidade crítica de evidência: fontes oficiais, entradas formais, saídas que sustentam alegações, snapshots/handoffs compactos, pacotes de revisão, árvores de fonte selecionadas e o PDF final revisado.
• Mantenha IDs internos, estados de evidência, caminhos locais, cobertura de execução e linguagem do fluxo de trabalho fora do artigo visível.
• As limitações do handoff do artigo vêm apenas de limitações de alegações elegíveis para artigo suportadas, preocupações P1 atuais e campos explícitos de aplicabilidade/suposição/limitação conhecida — não de alegações contraditas ou escopo do modelo.
• Vincule o PDF final aos seus bytes revisados e ao snapshot exato do código fonte LaTeX editável usado para a compilação.
• A falta de regras ou modelos oficiais atuais bloqueia a entrega; não autoriza pesquisa autônoma ou submissão.
• A entrega final contém o PDF revisado, o LaTeX editável e a fonte da computação como funções separadas.

Leia artifact-contracts.md ao criar arquivos legíveis por máquina e [evidence-rules.md](references/evide... [truncado para tradução]