Lucasuiii/cumcm-workflow

Flujo de Trabajo CUMCM

Mantén las afirmaciones que importan trazables a fuentes oficiales y a ejecuciones reales, sin convertir cada borrador en un paquete de auditoría.

Dos reglas rigen todo lo siguiente:

1. Las herramientas registran hechos automatizados; tú escribes el juicio. Nunca escribas un hash, un recuento de páginas, un código de salida, una instantánea de fuente o un valor de resultado. record_run.py, index_result.py, record_compile.py y refresh_evidence.py se encargan de eso. Tú escribes los hechos del problema, el modelo, las afirmaciones y el artículo.
2. El modelo se elige tarde, y la elección se gana. El modo de trabajo acepta un borrador de contrato de modelo. Nombra modelos candidatos, di qué evidencia los distinguiría, evalúalos con ejecuciones exploratorias económicas, y solo entonces selecciona uno y congela el contrato.

Iniciar o reanudar

1. Localiza .cumcm/state.json. Reanuda un proyecto exactamente 0.6.0. Los espacios de trabajo anteriores no son compatibles; inicia un nuevo proyecto desde los archivos oficiales.
2. Si no existe estado y el usuario proporciona archivos oficiales, lee 01-intake.md, elige un objetivo seguro y ejecuta scripts/init_project.py por ellos. No hagas que el usuario monte el comando.
3. Lee solo la guía de la etapa activa más handoffs.md al cruzar etapas. Una tarea nueva lee primero su transferencia, no todo el espacio de trabajo.
4. Mantén las seis responsabilidades distintas: orquestador, modelado, cómputo, validación, artículo, entrega. No simules separación inventando muchos Skills pequeños.

Los dos ajustes

mode (en el estado) decide qué debe estar completo. --gate-mode decide si las compuertas humanas cuentan.

• working: modelado rápido, cómputo exploratorio, depuración. Se aplica protección de entrada oficial, ejecución real, localizadores exactos de resultados y no fabricación. Un borrador de contrato de modelo es suficiente; CROSS_QUESTION_LEDGER.json es opcional; el orden de las etapas es indicativo. enforce aquí reporta working_ready, nunca una aprobación formal.
• finalizing: congela los resultados que contienen afirmaciones. El contrato del modelo debe estar completo y su plan de verificación debe asignarse a afirmaciones registradas por una ejecución oficial. Requiere decisiones y instantáneas de la etapa actual, transferencias recientes, revisión independiente acotada, QA de artículo/PDF y vinculación de entrega. enforce no puede pasar a menos que cada etapa hasta la solicitada esté passed con una decisión aceptada actual.

Cambia con scripts/set_mode.py. No hay perfil strict/sprint en v0.6; se aplica un único conjunto de reglas.

Dónde se pide a una persona

Tres puntos de control, uno por bloque, y cada uno registra lo que se puso frente a la persona, no solo lo que decidieron. Una decisión sin nada presentado no es evidencia de que alguien miró. Están situados frente a los tres pasos de coste: rechazar una elección de modelo cuesta una conversación, rechazar una conclusión cuesta una recomputación, rechazar un artículo terminado cuesta una reescritura.

• MODEL_CONTRACT.selection_check, antes de que un candidato se convierta en selected: el criterio de juicio, la discriminating_evidence de cada candidato y el scope que reclamará el ganador. presented_candidate_ids debe cubrir todos los candidatos (MODEL-E018) — mostrar solo al ganador no es una comparación.
• CLAIM_LEDGER.conclusion_check, antes de validation-paper: las conclusiones en sí — texto de la afirmación, scope, estado de la evidencia, P0/P1 abiertos. Sin IDs de ejecución, sin hashes. presented_claim_ids debe cubrir cada afirmación declarada (CLAIM-E023). Este es el lugar económico para escuchar un no; la misma objeción en la entrega cuesta un artículo reescrito.
• DELIVERY_MANIFEST.final_check, antes del envío: el objeto terminado — páginas renderizadas, la respuesta a cada subproblema, hallazgos abiertos. presented_pages debe cubrir cada página renderizada (DELIVERY-E020), y human_user no es reclamable sin nada presentado (DELIVERY-E019).

El informe del artículo no lleva aprobaciones propias: content_report y layout_report son informes. La selección del revisor se registra, no se confirma — la separación proviene de las dos transiciones de corte en su lugar (references/handoffs.md).

Los estados de las etapas son not_started, in_progress, passed, needs_revision.

Roles y transferencias

Responsabilidad	Referencia principal	Transferencia saliente
Modelado	02-problem-analysis.md, 03-model-design.md	modeling-computation
Cómputo	04-computation.md	computation-validation
Validación	05-validation.md	validation-paper
Artículo	06-paper-writing.md, latex-template.md	paper-delivery
Entrega	07-compile-delivery.md	paquete final

Construye las transferencias con scripts/build_handoff.py. Llevan rutas canónicas, una carga útil compacta aguas abajo y un resumen aguas arriba. Nunca copies registros completos, ejecuciones fallidas, historial de depuración o conversaciones de revisión antiguas. Un resumen obsoleto requiere reconstrucción.

Elegir el modelo

El diseño del modelo no elige un modelo. Propone candidatos y dice cómo se resolverá la elección:

"candidates": [
  {"candidate_id": "CAND-ENUM", "method": "complete enumeration",
   "why_considered": "the declared policy class is finite and small",
   "discriminating_evidence": ["whether the greedy pick equals the enumerated minimum"],
   "status": "under_evaluation"},
  {"candidate_id": "CAND-GREEDY", "method": "greedy first-fit",
   "why_considered": "constant time, adequate if the set is already ordered by cost",
   "discriminating_evidence": ["whether the greedy pick equals the enumerated minimum"],
   "status": "under_evaluation"}
]

Luego resuélvelo con evidencia en lugar de con una opinión:

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

Establece el ganador a status: "selected", los demás a "rejected", dale a cada uno un decision_rationale que se refiera a lo que mostraron esas ejecuciones, y lista las ejecuciones en evaluation_run_ids. Solo entonces el modelo seleccionado recibe una ejecución oficial.

El verificador te exige esto: exactamente un candidato puede terminar selected (MODEL-E013), una selección debe citar una ejecución que lo evaluó (MODEL-W014), un candidato seleccionado o rechazado necesita una razón registrada (MODEL-E014), y un candidato sin nada que lo distinga se marca (MODEL-W012). En working, esto son advertencias; al congelar, se convierten en errores. cumcm_check.py imprime la comparación bajo model_candidates.

Dos cosas que esto deliberadamente no hace: no requiere más de un candidato cuando uno es obviamente correcto (eso es MODEL-W007, una advertencia), y no juzga qué candidato es mejor — solo insiste en que la elección se hizo contra evidencia registrada.

Registrar el cómputo

# la exploración no cuesta nada al registrar
python3 scripts/record_run.py --project <p> -- python3 code/try.py

# congelar una ejecución para resultados formales cuesta unas pocas declaraciones
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

# el valor se lee de la salida, nunca se transcribe
python3 scripts/index_result.py --project <p> --result-id RES-Q1-001 \
  --run RUN-Q1-001 --locator results/q1.json#/minimum_cost \
  --name "Minimum cost" --unit CNY --scope "declared candidates only"

# una repetición añade un sucesor; el padre y su evidencia permanecen intactos
python3 scripts/record_run.py --project <p> --rerun RUN-Q1-001 --official
python3 scripts/index_result.py --project <p> --follow-lineage

Las ejecuciones exploratorias se registran, nunca se confían y nunca bloquean: una afirmación fallida o un código de salida distinto de cero dentro de una es un hecho sobre el experimento, no sobre la cadena formal. Solo una ejecución exitosa official_run: true puede respaldar un resultado formal.

Las ejecuciones son de solo añadidura. --rerun añade RUN-Q1-002 con parent_run_id: RUN-Q1-001; nunca sobrescribe, porque el padre es el único registro de lo que la ejecución reemplazada ejecutó y produjo. Cada ejecución congela su fuente y salidas declaradas en runs/<id>/source/… y runs/<id>/outputs/…, reflejando la estructura original, y hashea esas copias — por lo que una ejecución preservada permanece verificable independientemente de cómo cambie el espacio de trabajo, y output_locator nombra un archivo inmutable.

Una ejecución solo puede reclamar lo que produjo y lo que verificó: el registrador compara la marca de tiempo de cada salida declarada durante la ejecución y se niega a registrar un archivo sobrante como evidencia de afirmación de esta ejecución, y una repetición nunca hereda los veredictos de afirmación de su padre. Solo una repetición oficial exitosa reemplaza a su padre, y cada consumidor formal resuelve la ejecución actual a través del mismo código.

Eso no debilita la detección de desviación, la agudiza. RUN-E020 ahora compara la copia congelada con el archivo vivo y dice que el árbol de trabajo ha avanzado desde la ejecución que respalda tus resultados; las ejecuciones reemplazadas están exentas, y alterar una copia congelada es RUN-E021. La sustitución se deriva de la cadena padre y nunca se escribe de nuevo — marcar el manifiesto antiguo cambiaría su hash y dejaría obsoleta cada decisión vinculada a él. RESULT-E017 detecta un resultado que aún cita una ejecución reemplazada; index_result.py --follow-lineage lo reasigna, explícitamente, porque qué ejecución respalda una afirmación es un juicio, no un hecho automatizado.

Elegir un backend

El estado del proyecto por defecto es {"preferred":"matlab","fallback":"python","selection":"auto"}. Usa scripts/backend_selection.py o los mismos criterios: métodos numéricos, optimización, EDO/EDP, procesamiento de señales, limpieza de datos, Excel/CSV, aprendizaje automático, toolboxes disponibles, código existente, complejidad, estabilidad en tiempo de ejecución. La preferencia por MATLAB solo desempata. Un backend preferido no disponible puede recurrir al respaldo; una tarea required_backend no disponible debe fallar. Implementa y ejecuta oficialmente un lenguaje. No construyas implementaciones paralelas a menos que el usuario lo solicite.

Compuertas de evidencia

• invariante duro / P0: datos o cómputo incorrectos, desajuste de tarea (una capacidad que nadie asumió, o una aún sin terminar cuando el artículo se autodenomina final, es la mitad visible por máquina de esto: CAP-E013, CAP-E014), una afirmación cuyo alcance declarado excede el rango realmente verificado, desacuerdo código/resultado/artículo, una suposición que contradice una condición establecida, procedencia obsoleta, aprobación o revisión falsificada, datos simulados presentados como observados, desajuste de versión final. Estos bloquean.
• advertencia / P1, juzgado dentro del rango verificado: suposiciones fuertes, línea base débil, validación o sensibilidad más delgada de lo ideal, ajuste limitado, sección delgada. Visibles, nunca bloquean.
• sugerencia / P2: redacción, diseño, gráfico opcional, experimento adicional. No está en la compuerta.

La validación independiente usa accepted, accepted_with_concerns, revision_required, inconclusive. Solo un P0 abierto permite revision_required. Después de una revisión completa que encuentra problemas P0, el siguiente paquete por defecto es una re-revisión dirigida exactamente a esos hallazgos.

El paquete de revisión copia solo evidencia canónica para resultados indexados formalmente y registra context_excluded — el razonamiento previo que físicamente omitió. No afirma que el revisor no tenga opinión. La plantilla de resultado deja cada campo de independencia null: el revisor debe afirmarlos, y un null falla IREVIEW-E027. El usuario ya no confirma al revisor; la separación proviene del corte en su lugar — computation-validation y validation-paper llevan la tarea que los construyó, y una tarea consumidora que coincide es HANDOFF-E010. Ver references/handoffs.md.

Iterar

Reabrir una etapa aguas arriba es un comando, no una edición 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 "Q2 model does not fit the observed regime"

Eso invalida la etapa y todo lo posterior. Para saber qué costará realmente un cambio antes de rehacer algo:

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

plan_redo.py recorre source -> official run -> result -> claim -> section -> PDF y nombra las ejecuciones, hallazgos y secciones específicas afectadas — y las que no. Nunca suprime una verificación; cumcm_check.py aún valida todo hasta la etapa solicitada, porque es económico. El trabajo caro es re-ejecutar, re-revisar y re-escribir, y eso es lo que el plan delimita.

Invariantes del concurso

• Preserva e identifica por bytes las fuentes oficiales. El OCR enruta la atención; las páginas renderizadas deciden fórmulas, tablas y notación ambigua.
• Nunca inventes datos observados, aprobaciones, revisión independiente o ejecución exitosa. Etiqueta las simulaciones genuinas y registra su generador y semilla.
• Mantén el modelo matemático y los contratos de resultados neutrales en cuanto al idioma.
• Usa SHA-256 solo para identidad crítica para la evidencia: fuentes oficiales, entradas formales, salidas que contienen afirmaciones, instantáneas/transferencias compactas, paquetes de revisión, árboles de origen seleccionados y el PDF final revisado.
• Mantén los IDs internos, estados de evidencia, rutas locales, cobertura de ejecución y lenguaje del flujo de trabajo fuera del artículo visible.
• Las limitaciones de transferencia del artículo provienen solo de limitaciones de afirmaciones elegibles para el artículo compatibles, preocupaciones P1 actuales y campos explícitos de aplicabilidad/suposición/limitación conocida — no de afirmaciones contradichas o alcance del modelo.
• Vincula el PDF final a sus bytes revisados y a la instantánea exacta del código fuente LaTeX editable utilizada para la compilación.
• La falta de reglas o plantillas oficiales actuales bloquea la entrega; no autoriza la búsqueda o envío autónomos.
• La entrega final contiene el PDF revisado, el LaTeX editable y el código fuente del cómputo como roles separados.

Lee artifact-contracts.md al crear archivos legibles por máquina y evidence-rules.md para reglas de verificación. Las guías de etapa individuales se encuentran en references/:

Archivo	Contenido
references/01-intake.md	Ingesta inicial de problemas y archivos, selección de objetivo
references/02-problem-analysis.md	Análisis del problema y estructuración
references/03-model-design.md	Diseño del modelo y contratos de modelo
references/04-computation.md	Diseño e implementación del cómputo
references/05-validation.md	Validación y verificación
references/06-paper-writing.md	Redacción y diseño del artículo
references/07-compile-delivery.md	Compilación LaTeX y paquete de entrega
references/handoffs.md	Reglas de transferencia entre etapas
references/latex-template.md	Plantilla y guía de LaTeX
references/artifact-contracts.md	Contratos de artefactos legibles por máquina
references/evidence-rules.md	Reglas de verificación de evidencia