dsh-math-modeling-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yohan Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# MathModelingAgent for DSH
+
+证据驱动的数学建模智能体插件：状态机编排 + 主张/义务/证据账本 + 独立验证协议 + MCM/ICM 终审。继承 MathModelingAgent v3.1 的"分解 + 迭代"方法论，把验证裁决权从 LLM 主观打分换成可复现证据。
+
+## 继承与改良
+
+- **继承**：数据探查、子问题分解、顺序求解、带接受/拒绝标准的建模-分析-修正循环、停滞检测（源自 [IMO25](https://github.com/lyang36/IMO25) 的分解+迭代思想）。
+- **改良**：原项目的验证者是"分析者 LLM 打 1-5 分"；本插件改为**义务账本 + 工具执行证据 + 独立审计**——LLM 只负责提出主张和攻击，不再负责裁决正确性。旧仓库保持原样未动。
+
+## 特性
+
+- **状态机**：9 个可恢复终态（SOLVED / PARTIAL / CONDITIONAL / INCONCLUSIVE / REFUTED / INFEASIBLE / UNIDENTIFIABLE / BLOCKED / CANCELLED），每次转移必须引用证据或 issue。
+- **证据账本**：每个主张强制登记验证义务（数值→独立重算+误差界；最优性→KKT/对偶/精确搜索，否则只能声称"已找到最优"；预测→防泄漏划分+基线+校准……），证据强度不得弱于主张强度。
+- **验证协议**：固定攻击顺序 + PASS / FAIL / INCONCLUSIVE 三态裁决，INCONCLUSIVE 禁止升格。
+- **崩溃恢复**：原子快照 + 追加日志 + 跨进程锁，stale 锁与残留 guard 自动回收。
+- **MCM/ICM 终审**：一票否决与奖项封顶 + 七类 100 分 + 固定 14 节报告。
+- **零运行时依赖**：Python、Lean、Wolfram 全部可选，缺失时验证等级降级，绝不伪造执行。
+
+## 工作流
+
+```mermaid
+stateDiagram-v2
+    [*] --> TRIAGE
+    TRIAGE --> SCOPE_FROZEN
+    SCOPE_FROZEN --> INPUT_PROFILED
+    INPUT_PROFILED --> CLAIMS_REGISTERED
+    CLAIMS_REGISTERED --> CANDIDATES_READY
+    CANDIDATES_READY --> ATTEMPT
+    ATTEMPT --> EXECUTE
+    EXECUTE --> VERIFY
+    VERIFY --> REVISE
+    VERIFY --> RESEARCH
+    VERIFY --> FORK
+    REVISE --> ATTEMPT
+    RESEARCH --> CANDIDATES_READY
+    FORK --> ATTEMPT
+    VERIFY --> SOLVED
+    VERIFY --> PARTIAL
+    VERIFY --> CONDITIONAL
+    VERIFY --> INCONCLUSIVE
+    VERIFY --> REFUTED
+    VERIFY --> INFEASIBLE
+    VERIFY --> UNIDENTIFIABLE
+    VERIFY --> BLOCKED
+    VERIFY --> CANCELLED
+```
+
+任意非终态可直达 BLOCKED / CANCELLED。ATTEMPT 永远不能直接跳到 SOLVED。
+
+## 安装
+
+固定 GitHub 版本（发布流程需先创建 v0.1.0 tag）：
+
+~~~bash
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.1.0
+~~~
+
+npm 发布后，或本地 `npm pack` 生成的 tarball 路径：
+
+~~~bash
+dsh plugin --profile web add dsh-math-modeling-agent
+~~~
+
+不要用 `dsh plugin add .` 安装本地目录：它会按目录名安装且不激活 bundle。安装后验证组合配置并重启 host：
+
+~~~bash
+dsh --profile web --dump-config
+dsh web
+~~~
+
+## 核心机制
+
+### 状态机与 SOLVED 门禁
+
+每轮尝试有一个目标并记录：候选与假设增量、实际执行的命令或推导产物、新证据 ID、关闭的义务、打开/关闭的 issue、是否产生可审计进展、预算消耗、下一步行动。判定"进展"只认：关闭义务、新增可复现证据、反驳候选、收紧界或不确定区间、移除阻塞、正确弱化不支持的断言——重述、同参数重跑、更长的散文、工具 exit 0 都不算。连续两轮无进展进入停滞审查，第三轮无进展必须实质换方向（FORK）、交给用户决策，或以非 SOLVED 终态暂停。
+
+SOLVED 硬门禁：范围冻结 + 全部必选义务 PASS + 关键对抗检查通过 + 可复现材料齐全 + 局限已声明；High-Assurance 模式还必须通过一次只拿产物、不注入思维链的独立审计。
+
+### 主张 / 义务 / 证据
+
+- **主张记录**：ID、原文、类型、量词范围、假设、风险、验证义务、证据 ID、独立反查、状态、局限。
+- **证据记录**：方法、工具、时间戳、覆盖的主张、输入输出哈希、命令/环境、退出码、产物、容差、局限，以及六档等级：NOT_CHECKED / DERIVED / EXECUTED / VERIFIED / INDEPENDENTLY_VERIFIED / EXTERNALLY_VALIDATED。
+- **强度匹配**：训练集分数不能支撑泛化结论；单个优化器返回点不能支撑全局最优；形式化证明不能支撑未形式化的现实假设。不支持的断言只能弱化，不能放宽验证规则。
+
+### 验证协议
+
+冻结输入（哈希题目、数据、代码、配置、环境）→ 重建主张映射 → 按固定顺序攻击：任务覆盖与代理指标替换 → 单位/量纲/定义域/约束 → 推导与实现一致性 → 数据泄漏/标签/划分/后验参数 → 基线/不确定性/敏感性/外部效度 → 可复现性与引用真实性 → 反例/失败案例/更简单替代。裁决只允许 PASS（可复现证据支撑）、FAIL（矛盾/反例/无效方法/复现失败）、INCONCLUSIVE（证据不足），且 INCONCLUSIVE 不得因为"看起来合理"升格为 PASS。
+
+### 崩溃恢复与并发
+
+默认运行根目录 `math-modeling-runs/<task-id>/`。`run.json` 原子快照、`events.jsonl` 追加式转移日志、`ledger.json` 主张账本；`run-state.mjs` 提供 init / transition / validate / recover 四个命令。跨进程互斥锁带 ownerId 与 stale 回收（进程已死且超时自动接管），空锁文件与残留 reclaim guard 按 mtime 回收，Windows 共享冲突自动重试；恢复时校验日志并跳过哈希未变的已完成工作，任何 provider/解析器失败都保留原始产物与最佳候选。
+
+### MCM/ICM 终审
+
+`math-modeling-audit` Skill 内置模拟 100 分终审（非 COMAP 官方评分表）：Stage 1 一票否决与奖项封顶（14 项检查，逐项给出证据链封顶）；Stage 2 七类评分共 100 分（问题理解与分解 10、数据/证据/参数 12、模型构建 22、求解算法与可复现 16、结果验证与可信度 24、结论与推广 8、写作与图表 8）；Stage 3 模型逐个尸检；Stage 4 关键结果审计；Stage 5 按 MCM A/B/C 或 ICM D/E/F 启用专项检查；Stage 6 依据 93-100 Outstanding Candidate 等 band 判定奖项，输出固定 14 节报告。
+
+### 工具与降级
+
+`capability-probe.mjs` 探测 PATH 并实测可用性。Python 可选但推荐：仅在需要计算时用 `python-environment.mjs` 在运行目录内创建隔离 uv/venv 环境，只安装所需 PyPI 包（VCS 依赖与任意索引需用户批准）；Lean 与 Wolfram 可选，永不自动安装，Lean 结果必须附无 sorry/admit 证明与自然语言-形式语句忠实性检查；缺失能力只降低证据等级（unverified / partially_verified），不伪造执行结果。
+
+## 运行产物
+
+~~~text
+math-modeling-runs/<task-id>/
+├── run.json              # 原子状态快照
+├── ledger.json           # 范围、假设、主张、义务、子问题、候选、issue
+├── events.jsonl          # 追加式转移日志
+├── problem-brief.md      # 问题摘要
+├── inputs.json           # 输入与数据画像
+├── attempts/<n>/         # 每轮：report.md + 代码/产物（存在时）
+├── research/             # 文献检索与候选方法矩阵（发生研究时）
+├── walls/                # 放弃方向的突破备忘录（放弃时）
+├── reproducibility.json  # 数据/代码/配置版本、锁、种子、命令
+└── final-report.md       # 终态报告
+~~~
+
+## 卸载
+
+~~~bash
+dsh plugin --profile web remove dsh-math-modeling-agent
+~~~
+
+卸载后重启当前 host。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+- insert:
+    - id: dsh-math-modeling-agent-skills
+      name: '@deepseek-ai/dsh-skill-filesystem'
+      config:
+        providerName: dsh-math-modeling-agent
+        includeDefaultRoots: false
+        bundledSkillDir: !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"
+        watch: false

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dsh-math-modeling-agent",
+  "version": "0.1.0",
+  "description": "Evidence-driven mathematical modeling and verification skills for DeepSeek Harness",
+  "type": "module",
+  "files": [
+    "cordis.patch.yml",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run --json"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yohanchen1/MathModelingAgent.git"
+  },
+  "keywords": [
+    "dsh",
+    "mathematical-modeling",
+    "verification",
+    "lean",
+    "wolfram",
+    "python"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/math-modeling-agent/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: math-modeling-agent
+description: This skill should be used when the user asks to "建立数学模型", "解决数学建模题", "继续上次建模", "寻找新的建模方向", "solve this modeling problem", or needs an evidence-backed mathematical model with computation, research, verification, per-attempt reports, and resumable state.
+whenToUse: Use for open-ended mathematical modeling, prediction, optimization, estimation, simulation, mechanism, decision, or multi-part contest problems; do not use for auditing an already completed artifact without changing it.
+user-invocable: true
+---
+
+# Math Modeling Agent
+
+## Goal
+
+Move one mathematical problem from scoped intake to an evidence-backed conclusion or a precise resumable scientific status.
+
+## Interface
+
+Accept problem text, attachments, or an existing run directory. Do not ask the user to choose internal phases, Python/Lean/Wolfram adapters, file names, or state fields.
+
+Return a concise current status, supported claims, unresolved obligations, attempt delta, artifact path, and next action or final report.
+
+## Default workflow
+
+1. Route the task to Fast, Standard, or High-Assurance using `references/problem-types.md`.
+2. Read available inputs before asking questions; apply the one-question math grill in `references/math-grill.md`.
+3. Create or validate run state with `scripts/run-state.mjs` and follow `references/state-recovery.md`.
+4. Profile inputs and build the subproblem DAG using `references/data-subproblems.md`.
+5. Register assumptions, claims, and verification obligations from `references/claims-evidence.md`.
+6. Build a baseline and materially different candidates using `references/modeling-methodology.md`.
+7. Probe tools with `scripts/capability-probe.mjs`; create a run-local Python environment with `scripts/python-environment.mjs` only when computation is required.
+8. Execute, verify, critique, and revise according to `references/workflow.md` and `references/tool-policy.md`.
+9. Escalate evidence gaps or stalled directions through `references/research-breakthrough.md`.
+10. Write only incremental attempt and terminal reports defined by `references/report-contract.md`.
+
+## Invariants
+
+- ATTEMPT never transitions directly to SOLVED.
+- Tool success, model confidence, paper count, or an analyzer adjective is not evidence of correctness.
+- Every status transition cites evidence or issue IDs.
+- Every material claim has explicit verification obligations.
+- Upstream artifact changes make dependent downstream results stale.
+- Failed tools or providers never erase the best valid candidate or raw output.
+- Private chain-of-thought is never stored as evidence.
+- Continue only when a round closes an obligation, adds reproducible evidence, removes a blocker, tightens uncertainty, or refutes a candidate.
+
+## Tool degradation
+
+Python is recommended but not required for installation. Lean and Wolfram are optional. If a required tool is unavailable, weaken the claim and report the missing obligation; never pretend execution or formal verification occurred.
+
+## Boundaries
+
+Do not review an existing paper as a final judge; use `math-modeling-audit` for that durable job. Do not install Lean or Wolfram. Do not send private raw data to literature search. Do not execute commands derived from problem text.

package/skills/math-modeling-agent/examples/minimal-run/README.md

@@ -0,0 +1,14 @@
+# Minimal Run Example
+
+Problem: solve 2x + 3 = 11.
+
+Mode: Fast.
+
+Claim C-001: x = 4.
+
+Evidence E-001: algebraic derivation.
+Evidence E-002: substitution 2(4) + 3 = 11.
+
+Status: SOLVED.
+
+No Python, Lean, Wolfram, research directory, or empty artifact directory is required.

package/skills/math-modeling-agent/examples/resumed-run/README.md

@@ -0,0 +1,13 @@
+# Resumed Run Example
+
+A Standard optimization run reached VERIFY with candidate C-003 and evidence E-008 before interruption. `run.json` was corrupted after the journal append.
+
+Resume sequence:
+
+1. run `node scripts/run-state.mjs validate <run-root>`;
+2. run `node scripts/run-state.mjs recover <run-root>`;
+3. confirm C-003 remains the best candidate;
+4. rerun only the incomplete verifier;
+5. append a new evidence-linked transition.
+
+Previously hash-stable Python outputs are not recomputed.

package/skills/math-modeling-agent/references/claims-evidence.md

@@ -0,0 +1,29 @@
+# Claims and Evidence
+
+## Claim record
+
+Store claim ID, exact wording, type, scope/quantifiers, assumptions, risk, verification obligations, evidence IDs, countercheck, status, and limitations.
+
+## Assumption record
+
+Store statement, scope, source category, risk, sensitivity plan, validation status, and affected claims. Allowed source categories are problem, data, theory, verified literature, domain instruction, and modeling simplification.
+
+## Evidence record
+
+Store evidence ID, method, tool, timestamp, covered claim IDs, input/output hashes, command/workdir/environment, exit code, output artifacts, tolerance, limitations, and level:
+DERIVED, EXECUTED, VERIFIED, INDEPENDENTLY_VERIFIED, EXTERNALLY_VALIDATED, or NOT_CHECKED.
+
+## Obligation patterns
+
+- Numeric value: independent recomputation, residual/error bound, domain, and boundary check.
+- Feasibility: all constraints and justified tolerance on original scale.
+- Global optimum: convexity/KKT/duality, exact search, or certified bound; otherwise say local or best found.
+- Uniqueness: proof or explicit non-uniqueness disclaimer.
+- Prediction: untouched test/external validation, leakage-safe split, baseline, uncertainty, and calibration.
+- Causal effect: estimand, identification, temporal order, confounding, and sensitivity.
+- Robustness: parameter, data, seed, specification, and scenario perturbation.
+- Theorem: readable or kernel-checked proof plus formalization-fidelity audit.
+- Literature support: resolvable source, exact location, excerpt, retrieval date, and mapped claim.
+- Reproducibility: data/code/config versions, lock, seed, tolerance, commands, and clean rerun.
+
+Evidence strength may not be weaker than claim strength. Weaken unsupported claims; never weaken the verification rule.

package/skills/math-modeling-agent/references/data-subproblems.md

@@ -0,0 +1,17 @@
+# Inputs, Data, and Subproblems
+
+## Input manifest
+
+For each accessible artifact record stable ID, cryptographic hash, source, path, type, size, encoding, readability, and extraction provenance. For tables record sheets, rows, columns, inferred types, units, missingness, duplicates, ranges, anomalies, label source, time structure, group structure, and leakage risk.
+
+Do not silently ignore unsupported files. Mark them unreadable and state the minimum representation needed.
+
+## Leakage audit
+
+Before model selection, identify target labels, future information, repeated entities, grouped observations, temporal ordering, and preprocessing fit scope. Fit imputation, scaling, feature selection, dimensionality reduction, and thresholds only inside training folds. Use time or group splits when ordinary random splits leak information.
+
+## Subproblem DAG
+
+Each subproblem records ID, exact task, required inputs, produced claims/artifacts, dependencies, acceptance criteria, and status. Downstream work references upstream IDs rather than copied prose.
+
+When an upstream artifact changes, mark every dependent output stale. If an upstream node is blocked, downstream work must choose exactly one state: blocked, provisional with explicit condition, or alternative independent path.

package/skills/math-modeling-agent/references/math-grill.md

@@ -0,0 +1,33 @@
+# Math-Grill Protocol
+
+Ask one question at a time. Read the problem and attachments first. Ask only questions whose answer can change the model, evidence obligation, or deliverable.
+
+## Minimum routing questions
+
+1. What output is required: number, proof, model, prediction, optimum, or decision?
+2. Does data exist, and what is its source?
+3. Is the requested claim proof, global optimality, causality, safety, or a useful approximation?
+4. What error, confidence, or decision risk is acceptable?
+5. Is the result for practice, competition, publication, production, or high-stakes use?
+
+## Selective modeling fields
+
+Collect only applicable fields:
+
+- background and practical objective;
+- explicit and hidden subproblems;
+- data, label source, units, quality, time, and group structure;
+- decision/state variables and parameters;
+- objective or evaluation metric;
+- equality, inequality, integer, nonnegative, logical, initial, and boundary constraints;
+- assumptions and their source category;
+- acceptance criteria and final deliverable.
+
+## Rules
+
+- Infer before asking.
+- Ask the highest-impact unknown first.
+- Mark irrelevant fields “not applicable” with a reason.
+- Turn “自行判断” into an explicit modeling assumption with risk and sensitivity plan.
+- Do not freeze scope while a missing answer can change the problem type or claim strength.
+- Do not force a proof problem to invent data or an exploratory analysis to invent an objective function.

package/skills/math-modeling-agent/references/modeling-methodology.md

@@ -0,0 +1,38 @@
+# Modeling Methodology
+
+## Mechanism first
+
+Map real objects to variables, mechanism to equations, reality constraints to mathematical constraints, and requested decisions to objective/evaluation criteria. Never choose a named method first and force the problem into it.
+
+## Candidate portfolio
+
+Always begin with a defensible baseline. Add a more complex candidate only when it targets a documented baseline failure. Candidates must differ in mechanism, information, assumptions, or verification route—not wording.
+
+For each candidate record:
+
+- stable ID and parent/fork;
+- target subproblem and claims;
+- mechanism and equations;
+- assumptions and parameter sources;
+- input requirements;
+- expected information gain;
+- verification obligations;
+- stop/abandon conditions;
+- complexity, interpretability, and compute cost.
+
+## Selection
+
+Prefer the simplest candidate that meets evidence and accuracy requirements. Compare verification coverage, critical issues, empirical performance, robustness, complexity, interpretability, cost, and reproducibility. Do not reward model count, deep learning, metaheuristics, AHP, TOPSIS, entropy weights, or Monte Carlo by name.
+
+## Core checks
+
+- units and dimensions;
+- limiting and boundary cases;
+- known special cases;
+- constraint completeness;
+- identifiability and conditioning;
+- convergence and numerical stability;
+- data leakage and post-hoc parameters;
+- baseline and ablation;
+- sensitivity of conclusion-changing parameters;
+- model-result-conclusion traceability.

package/skills/math-modeling-agent/references/problem-types.md

@@ -0,0 +1,20 @@
+# Problem Types and Obligations
+
+| Type | Primary output | Mandatory checks |
+|---|---|---|
+| Symbolic calculation | exact expression or roots | domain, equivalence, substitution, singular cases |
+| Theorem/proposition | proof or counterexample | quantifiers, assumptions, boundary cases, proof completeness |
+| Deterministic numerical | approximation | residual, convergence, stability, discretization error |
+| Feasibility | satisfying assignment | every constraint, tolerance, certificate |
+| Optimization | local/global solution | objective fidelity, constraints, bounds, optimality gap/certificate |
+| Statistical estimation | estimate and uncertainty | sampling assumptions, interval, residual diagnostics |
+| Prediction/classification | out-of-sample performance | leakage-safe split, baseline, calibration, uncertainty |
+| Causal inference | identified effect | estimand, temporal order, confounding, sensitivity |
+| Stochastic/risk | distribution or risk measure | distribution assumptions, Monte Carlo error, tail behavior |
+| Inverse problem | recovered parameter/structure | identifiability, conditioning, regularization |
+| Mechanism/system | dynamic behavior | structural validity, units, calibration, initial/boundary conditions |
+| Decision analysis | recommendation | preference/weight source, constraints, sensitivity, regret |
+| Exploratory analysis | hypotheses/patterns | no causal upgrade, multiplicity, robustness |
+| Literature synthesis | supported method/fact | source verification, applicability, conflicting evidence |
+
+Use multiple labels when necessary, but choose one primary output and one explicit assurance mode.

package/skills/math-modeling-agent/references/report-contract.md

@@ -0,0 +1,29 @@
+# Report Contract
+
+## Attempt report
+
+Every attempt report contains exactly:
+
+1. one round objective;
+2. candidate/direction;
+3. assumption delta;
+4. claims changed;
+5. actual execution or derivation artifacts;
+6. new evidence IDs;
+7. obligations closed;
+8. issues opened and closed;
+9. delta from prior attempt;
+10. valid-progress decision;
+11. budget usage;
+12. current status;
+13. one next action.
+
+Do not copy full prior solutions or private reasoning.
+
+## Terminal report
+
+State the frozen question, final scientific status, answer/recommendation, verified claims and evidence links, conditional/unresolved claims, assumptions and sensitivity, candidate comparison, data and parameter sources, validation, failure cases, limitations, reproducibility commands, and resume conditions when non-SOLVED.
+
+## Chat summary
+
+After each round show only attempt number, direction, tool execution status, obligations passed/failed, most important failure, artifact path, and next action.

package/skills/math-modeling-agent/references/research-breakthrough.md

@@ -0,0 +1,27 @@
+# Research and Breakthrough
+
+Research only when it closes a named evidence gap, validates a parameter/assumption, supplies an applicable method, or explains a failure.
+
+## Source record
+
+Record author, title, year, venue, DOI/stable URL, version, retrieval date, exact page/section/theorem/table, excerpt, mapped claim, source quality, applicability, and support strength. Distinguish full text, abstract only, metadata only, secondary source, conflicting evidence, and citation needed.
+
+## Method matrix
+
+For each candidate method record applicability, assumptions, data needs, implementation cost, verification route, reason to try, and reason to reject.
+
+## Isolated campaign
+
+For genuinely hard multi-direction problems, give isolated subagents independent briefs and prevent cross-talk. Require a counterexample family, the first unproved step, honest evidence level, and direction-exhaustion discipline. The coordinator reads final reports and adjudicates.
+
+## Wall memo
+
+A direction may be abandoned only when refuted, blocked by a precise missing tool/theory/information, or after natural variants are exhausted. Write:
+
+- target and direction;
+- paths tried and evidence;
+- exact wall and wall type;
+- breakthrough condition;
+- restart checklist.
+
+On a new tool, model, source, or resumed request, scan wall memos before restarting from zero.

package/skills/math-modeling-agent/references/state-recovery.md

@@ -0,0 +1,18 @@
+# State and Recovery
+
+Default run root: `math-modeling-runs/<task-id>/`.
+
+Required durable files:
+
+- run.json: atomic current snapshot;
+- ledger.json: scope, assumptions, claims, obligations, subproblems, candidates, and issues;
+- events.jsonl: append-only transition journal;
+- problem-brief.md and inputs.json;
+- attempts/<number>/report.md plus code/artifacts only when they exist;
+- research/sources.jsonl and methods.md only when research occurs;
+- walls/ only when a direction is abandoned;
+- reproducibility.json and final-report.md for terminal output.
+
+Use `scripts/run-state.mjs` for initialization, transition, validation, and recovery. A transition without evidence/issue references is invalid. Provider, parser, or verifier failure preserves raw output and the best candidate. Resume by validating state, recovering from the last journal snapshot when needed, then skipping hash-stable completed work.
+
+Failure classes include data missing/schema/leakage, tool unavailable/dependency/license, runtime/timeout/numerical instability, model/assumption/parameter, verification/formalization, citation/research, parser/provider, no progress, and budget exhausted.

package/skills/math-modeling-agent/references/tool-policy.md

@@ -0,0 +1,21 @@
+# Tool Policy
+
+## Capability discovery
+
+Run `scripts/capability-probe.mjs`; treat PATH hits as candidates, then verify version and usability through the available DSH shell. Record unavailable, candidate, available, or unknown with reason.
+
+## Python
+
+Use `scripts/python-environment.mjs`. Prefer uv, then an existing Python runtime plus venv. Keep the environment under the run directory. Install only required normalized PyPI package names; VCS URLs, local wheels, or arbitrary indexes require explicit user approval. Record lock, seed, command, workdir, timeout, stdout/stderr, exit code, and generated files.
+
+## Lean
+
+Never auto-install. Use only for formalizable obligations. Record Lean/Lake/library versions, axioms/imports, proof artifact, absence of sorry/admit, and a separate natural-language-to-formal-statement fidelity check.
+
+## Wolfram
+
+Never auto-install. Verify executable and license usability. Use for applicable symbolic, exact, or high-precision claims and state the exact coverage boundary.
+
+## Search, PDF, and images
+
+Use available web, PDF, vision/OCR, or local Python readers. Do not send private raw data in search queries. Missing capabilities lower evidence level rather than causing fabricated execution.

package/skills/math-modeling-agent/references/workflow.md

@@ -0,0 +1,39 @@
+# Modeling Workflow
+
+## Modes
+
+- Fast: explicit low-risk calculation; at most two clarifications; direct inverse, substitution, domain, or unit check.
+- Standard: normal modeling; input profile, baseline, candidates, execution, sensitivity, and reproducibility.
+- High-Assurance: publication, proof, global optimum, causal, safety, guarantee, or high-stakes use; require independent audit.
+
+## States
+
+TRIAGE → SCOPE_FROZEN → INPUT_PROFILED → CLAIMS_REGISTERED → CANDIDATES_READY → ATTEMPT → EXECUTE → VERIFY.
+
+VERIFY may move to REVISE, RESEARCH, FORK, an independent audit, or one terminal status:
+SOLVED, PARTIAL, CONDITIONAL, INCONCLUSIVE, REFUTED, INFEASIBLE, UNIDENTIFIABLE, BLOCKED, CANCELLED.
+
+## Round contract
+
+Each round has one objective and records:
+
+- candidate and assumption delta;
+- actual command or derivation artifact;
+- new evidence IDs;
+- obligations closed;
+- issues opened and closed;
+- whether auditable progress occurred;
+- budget used;
+- one next action.
+
+## Progress test
+
+Count progress only when a round closes an obligation, adds reproducible evidence, refutes a candidate, tightens a bound or uncertainty interval, removes a blocker, or weakens an unsupported claim correctly.
+
+Do not count rewording, same-parameter reruns, training-only gains, longer prose, tool exit success, or unverified search titles.
+
+After two no-progress rounds, run a stagnation review. A third no-progress round requires a material fork, user decision, or resumable non-SOLVED status.
+
+## SOLVED gate
+
+SOLVED requires frozen scope, all required obligations passed, critical adversarial checks passed, reproducibility material present, limitations stated, and—under High-Assurance—an independent artifact-only audit.

package/skills/math-modeling-agent/schemas/attempt.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/yohanchen1/MathModelingAgent/schemas/attempt.schema.json",
+  "title": "Math Modeling Attempt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "attempt",
+    "candidateId",
+    "objective",
+    "evidenceIds",
+    "closedObligationIds",
+    "issuesOpened",
+    "issuesClosed",
+    "progress",
+    "nextAction",
+    "status"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "attempt": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "candidateId": {
+      "type": "string"
+    },
+    "objective": {
+      "type": "string",
+      "minLength": 1
+    },
+    "evidenceIds": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "closedObligationIds": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "issuesOpened": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "issuesClosed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "progress": {
+      "type": "boolean"
+    },
+    "nextAction": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string"
+    }
+  }
+}