dsh-math-modeling-agent 0.1.2 → 0.2.1

package/README.md

@@ -81,14 +81,20 @@ NOT_CHECKED → DERIVED → EXECUTED → VERIFIED → INDEPENDENTLY_VERIFIED →
 默认运行目录 `math-modeling-runs/<task-id>/`：
 
 ```text
-run.json            # 原子状态快照
-ledger.json         # 范围、假设、主张、义务、子问题、候选、issue
-events.jsonl        # 追加式转移日志
-attempts/<n>/       # 每轮报告与产物
-research/  walls/   # 文献检索 / 放弃方向的突破备忘录
+run.json  ledger.json  events.jsonl   # 原子状态 + 契约（interactions/decisionStack）+ 日志
+problem-brief.md  inputs.json         # 冻结的问题重述 + 输入清单
+attempts/<n>/                         # 每轮：report.md + code/ + data/ + plots/ + _drafts/
+failed/directions/<id>/               # 方向级失败：wall memo + 代码 + 放弃理由
+failed/code-drafts/<attempt>-<name>/  # 实现级失败：bug 版/超时版/弃用版（不删除）
+failed/issues.md                      # 失败账本（DATA/TOOL/IMPLEMENTATION/MODEL/VALIDATION/EVIDENCE/RESEARCH_GAP）
+research/  walls/                     # 文献检索 / 突破备忘录
 reproducibility.json  final-report.md
 ```
 
+v0.2.0 起：每个会改变模型结构的决策在对话中交互确认并写入 ledger（D0 重述/D1 路由/
+D2 子问题假设/D3 方向/D4 裁决），`run-state.mjs gate` 在每次状态转移前强制校验；
+终态前强制鲁棒性敏感度分析；失败尝试按类归档到独立目录。
+
 崩溃恢复：跨进程互斥锁 + stale 锁与 reclaim guard 回收 + Windows 共享冲突重试；已完成且输入未变的工作不重跑；任何失败都保留最佳候选与原始产物。
 
 ## MCM / ICM 终审（audit Skill）
@@ -100,14 +106,17 @@ reproducibility.json  final-report.md
 安装：
 
 ```bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.1.2
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.2.1
 dsh --profile web --dump-config   # 检查组合层
 dsh web                          # 然后重启
 ```
 
 （npm 通道：`dsh plugin --profile web add dsh-math-modeling-agent`）
 
-开始建模——直接描述任务即可，不需要选内部状态、验证器或文件名：
+开始建模——直接描述任务即可。v0.2.0 起每个会改变模型结构的决策都会在对话中交互确认
+（任务路由、各子问题假设、候选方向、每轮裁决），每轮在对话直接输出 runlog 式摘要
+（问题重述/分析/假设/建模求解/验证/鲁棒性/评价改进/参考文献），失败尝试按类归档到独立目录，
+终态前强制鲁棒性敏感度分析：
 
 ```text
 建立这个数学建模问题的模型，先分析题目和数据。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-math-modeling-agent",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Evidence-driven mathematical modeling and verification skills for DeepSeek Harness",
   "type": "module",
   "files": [

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

@@ -13,22 +13,26 @@ Move one mathematical problem from scoped intake to an evidence-backed conclusio
 
 ## 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.
+Accept problem text, attachments, or an existing run directory.
+
+Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is interactive — D0 restatement / D1 routing once per task, D2 assumptions and D3 direction per subproblem, D2' on mid-subproblem discoveries, D4 verdict per round. Show the runlog digest in the chat after every round (references/report-contract.md); announce one status line before every transition; the user may interrupt at any time.
 
 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`.
+1. Route the task to Fast, Standard, or High-Assurance using `references/problem-types.md`; ask D1 (task type + assurance mode).
+2. Read available inputs before asking questions; apply the per-subproblem math grill in `references/math-grill.md`; show the D0 restatement and intake digest in the chat.
+3. Create or validate run state with `scripts/run-state.mjs` and follow `references/state-recovery.md`. Gate EVERY transition: `run-state.mjs gate <dir> --to <status> --reason "..."`.
 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`.
+5. Register assumptions (per subproblem), claims, and verification obligations from `references/claims-evidence.md`; ask D2 for the subproblem being started.
+6. Build a baseline and materially different candidates using `references/modeling-methodology.md`; ask D3 (candidate matrix).
+7. Probe tools with `scripts/capability-probe.mjs`; create a run-local Python environment with `scripts/python-environment.mjs` only when computation is required. Announce the tool choice and fallback for the phase (references/tool-policy.md).
+8. Execute, verify, critique, and revise according to `references/workflow.md` and `references/tool-policy.md`; ask D4 after each VERIFY.
+9. Dispatch subagents for parallel exploration, blind verification, and audits per `references/subagent-dispatch.md`.
+10. Escalate evidence gaps or stalled directions through `references/research-breakthrough.md`; write wall memos and the failure ledger per `references/run-directory.md`.
+11. Write only incremental attempt and terminal reports defined by `references/report-contract.md`; output the per-round runlog digest in the chat.
+12. Before any terminal transition, run the cleanup gate (references/run-directory.md) and the robustness gate (a PASSED robustness-kind obligation, or scope.robustnessExempt with reason).
 
 ## Invariants
 
@@ -36,10 +40,11 @@ Return a concise current status, supported claims, unresolved obligations, attem
 - 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.
+- Upstream artifact changes make dependent downstream results stale; assumption revisions mark dependent claims 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.
+- The run directory stays clean at every moment, and every failed path is preserved in its own folder (references/run-directory.md).
 
 ## Tool degradation
 

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

@@ -1,4 +1,4 @@
-# Minimal Run Example
+# Minimal Run Example (v2)
 
 Problem: solve 2x + 3 = 11.
 
@@ -11,4 +11,10 @@ Evidence E-002: substitution 2(4) + 3 = 11.
 
 Status: SOLVED.
 
+v2 interaction records (ledger.scope.interactions): D0 restatement (auto), D1 routing
+(algebra / Fast), D2 assumptions (none beyond the equation), D3 direction
+(direct inverse), D4 verdict (user accepted). scope.robustnessExempt = true —
+a pure algebraic equation has no perturbable parameters, so the robustness
+gate is exempted with that reason. decisionStack holds the D3 entry.
+
 No Python, Lean, Wolfram, research directory, or empty artifact directory is required.

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

@@ -7,7 +7,9 @@ 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.
+4. run `node scripts/run-state.mjs gate <run-root> --to REVISE --reason "回退到 D3-SP1：..."` (the reason must reference the decisionStack entry);
+5. rerun only the incomplete verifier;
+6. append a new evidence-linked transition (the CLI enforces the gate).
 
-Previously hash-stable Python outputs are not recomputed.
+Previously hash-stable Python outputs are not recomputed. Interaction records,
+the decision stack, and the failure ledger survive the crash unchanged.

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

@@ -4,15 +4,23 @@
 
 Store claim ID, exact wording, type, scope/quantifiers, assumptions, risk, verification obligations, evidence IDs, countercheck, status, and limitations.
 
-## Assumption record
+## Assumption record (v2)
 
-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.
+Store id, statement, scope (subproblem ids or global), source category, risk, sensitivity plan, validation status, affected claims, status (active/revised/superseded), and revisionHistory [{at, reason, changedTo}]. Allowed source categories are problem, data, theory, verified literature, domain instruction, and modeling simplification.
+
+Revisions are hard operations: when an assumption is revised, every claim/obligation that depended on it is marked `stale: true` with the revising assumption id, and the affected verification reruns (or the conclusion is explicitly downgraded) before any terminal state.
+
+## Robustness obligation (v2, terminal gate)
+
+Every subproblem that produces numerical conclusions registers a robustness obligation automatically. Execution standard: perturbation targets (problem parameters, data-fitted values, objective/weighting choice, aperture/boundary rules, discretization) × per-parameter magnitudes (±0.1%/±1%/±10% by parameter nature) × judgment (does the conclusion direction flip? what is the magnitude of change?), reported as a table (参数/扰动/结果变化/对结论影响). The run-state gate refuses terminal states without a PASSED robustness obligation unless scope.robustnessExempt is set with a reason (pure proofs only).
 
 ## 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.
 
+INDEPENDENTLY_VERIFIED (v2) means a blind verifier subagent confirmed it (claim + data + problem text only — never the solver's private reasoning); record the verifier label and brief hash (subagent-dispatch.md).
+
 ## Obligation patterns
 
 - Numeric value: independent recomputation, residual/error bound, domain, and boundary check.

package/skills/math-modeling-agent/references/interaction-protocol.md

@@ -0,0 +1,64 @@
+# Interaction Protocol (v2)
+
+Three interaction layers. Execution details stay autonomous; every
+model-shaping decision is visible and user-owned.
+
+## L1 decision points (MUST ask via the question tool)
+
+| Point | Trigger | Question | Default |
+|---|---|---|---|
+| D0 问题重述 | intake complete | confirm the full problem restatement (all sub-questions, constraints, deliverables) | accept |
+| D1 路由 | TRIAGE | task type (prediction/optimization/explanation/proof/…) + assurance mode (Fast/Standard/High-Assurance) | auto-routing result |
+| D2 假设确认 | **each subproblem starts** | the assumptions registered for THIS subproblem (numbered list: statement + source + risk); user confirms or edits | accept all |
+| D2' 新假设插问 | mid-subproblem discovery that changes model structure | the new assumption + its effect | record-and-continue |
+| D3 方向选择 | CANDIDATES_READY | candidate matrix (mechanism/assumptions/cost/verification/expected gain); user picks or authorizes auto | baseline |
+| D4 结果裁决 | VERIFY done | verdict (PASS/FAIL/INCONCLUSIVE) + evidence digest; user chooses accept/REVISE/switch direction/end | verdict-implied |
+
+Rules:
+- D0/D1: once per task. D2/D3: once per subproblem. D2': only when a discovery changes model structure. D4: once per attempt round.
+- Every L1 record is appended to `ledger.scope.interactions` as
+  `{id, decisionPoint, question, options, userAnswer, timestamp, effectOnModel}`
+  or, for explicit auto authorization,
+  `{auto: true, decisionPoint, reason}`.
+- Run the gate before every transition: `run-state.mjs gate <dir> --to <status> --reason "<...>"`.
+  The gate refuses SCOPE_FROZEN without D1, ATTEMPT-from-CANDIDATES_READY without D3,
+  terminals-from-VERIFY without D4, and REVISE/RESEARCH whose reason fails to
+  reference a `decisionStack` entry id. The CLI `transition` command enforces
+  the same gate (escape hatch `--skip-gate true` is for mechanism testing only).
+
+## L2 display points (MUST show, never ask)
+
+- After every attempt round: the 8-section runlog digest (see report-contract.md).
+- Before every transition: one status line: `[状态] FROM → TO：一句话原因`.
+- When starting any command estimated > 60 s: say what, how long, and what
+  continues in parallel (see tool-policy.md).
+
+## L3 interruption
+
+- The user may interrupt at ANY time ("停/换方向/改假设/结束").
+- On interrupt: stop the current execution chain immediately, then return to
+  the nearest decision point on the stack and ask again.
+- An interrupt never leaves the run directory inconsistent: run-state writes
+  are atomic and lock-guarded; in-flight background jobs are killed or awaited
+  before any transition is recorded.
+
+## Decision stack and backtracking
+
+- Every L1 decision also appends to `ledger.scope.decisionStack`:
+  `{id (e.g. D3-SP1), point, choice, at, reason}`.
+- REVISE/RESEARCH reasons MUST reference the stack entry being revisited
+  (e.g. "回退到 D3-SP1：M2-area 违反 0.07% 边长约束，改 M1-cheb").
+- A wrong direction returns to its fork point: FORK records the fork entry in
+  the stack; each failed branch leaves a wall memo before the next branch runs.
+- Assumption revisions keep history: `revisionHistory: [{at, reason, changedTo}]`,
+  and every downstream claim/obligation that depended on the old assumption is
+  marked `stale: true` with the revising assumption id (see claims-evidence.md).
+
+## Rolling documents
+
+- Problem restatement: written once at intake (problem-brief.md); only
+  referenced afterwards; a restatement edit re-opens scope freeze.
+- Problem analysis: written per subproblem and appended on every discovery;
+  ledger.subproblems[].analysisLog = `[{at, entry, trigger}]`.
+- Assumptions: registered per subproblem, revised incrementally; never assume
+  the full problem's assumptions are known up front.

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

@@ -10,18 +10,23 @@ Ask one question at a time. Read the problem and attachments first. Ask only que
 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
+## Problem Brief fields (16, collect all applicable)
 
-Collect only applicable fields:
+1. 问题背景与实际问题；2. 目标；3. 子问题（显式+隐含）；4. 输入数据（来源/质量/单位/时间/分组）；5. 数据质量问题；
+6. 决策/状态变量；7. 参数；8. 目标函数/评价指标；9. 约束（等式/不等式/整数/非负/逻辑/初始/边界）；
+10. 假设及依据；11. 任务类型（预测/优化/解释/证明/机制/决策）；12. 误差/精度要求；
+13. 验证标准；14. 最终交付物；15. 风险与失败模式；16. 不适用字段（标注原因）。
 
-- 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.
+## Per-subproblem grilling (v2)
+
+- Grill **one subproblem at a time**. Never demand assumptions for Q2 while Q1 is unsolved.
+- For each subproblem: ask one question at a time, highest-impact first;
+  every answer is recorded as the D2 interaction for that subproblem
+  (see interaction-protocol.md).
+- Mid-subproblem discoveries that change model structure trigger D2':
+  register the new assumption, show it in the chat, ask only if it is model-shaping.
+- The 16 Problem Brief fields are filled once at intake for the whole problem;
+  subproblem-level analysis and assumptions roll forward per attempt.
 
 ## Rules
 
@@ -29,5 +34,6 @@ Collect only applicable fields:
 - 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.
+- Assumptions are revisable: record revisionHistory and mark dependent claims stale.
 - 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/report-contract.md

@@ -24,6 +24,42 @@ Do not copy full prior solutions or private reasoning.
 
 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
+## Chat display — the runlog digest (MUST output, v2)
 
-After each round show only attempt number, direction, tool execution status, obligations passed/failed, most important failure, artifact path, and next action.
+The following is shown DIRECTLY IN THE CHAT, not only on disk.
+
+### Intake digest (once, at intake completion)
+
+【问题重述】full restatement: all sub-questions, constraints, deliverables
+【问题分析】input profile, geometric/physical structure, subproblem DAG, key difficulties
+【模型假设】the assumptions known at intake (numbered: statement + source + risk + sensitivity plan)
+
+### Per-round digest (after EVERY attempt round)
+
+```text
+## Attempt N 摘要
+问题重述：<1-2 sentences, current subproblem>
+问题分析：<2-4 sentences, this round's inputs/insights/delta vs last round>
+模型假设：<沿用 X 条 + 新增 Y 条 + 修订 Z 条；修订注明原因；重中之中，不得省略>
+模型建立与求解：<core equations + method + key numbers>
+验证：<obligations ✓/✗ + evidence levels + most important failure>
+鲁棒性：<this round's sensitivity results, or "未覆盖，计划在 attempt M">
+评价与改进：<candidate comparison / limitations / next improvement>
+参考文献：<new citations or "无新增">
+```
+
+Rules:
+- The restatement is frozen after intake; analysis and assumptions ROLL FORWARD
+  per subproblem and per round (they change, and the digest shows the delta).
+- Private chain-of-thought is never shown; only auditable content.
+- The digest is a hard requirement of the round contract: a round whose digest
+  is missing does not count as a completed round.
+
+## Cleanup checklist (before ANY terminal transition)
+
+1. attempts/<n>/code holds only final reproducible scripts with header comments.
+2. Exploratory/buggy code is moved to _drafts/ or failed/code-drafts/ — never deleted.
+3. No debug prints or machine-specific hardcoded paths.
+4. figures → plots/, tables → data/, deliverable at run root.
+5. reproducibility.json matches the final scripts.
+6. run-state validate passes; every obligation has a terminal status.

package/skills/math-modeling-agent/references/run-directory.md

@@ -0,0 +1,62 @@
+# Run Directory Contract (v2)
+
+The run directory is the ONLY place work artifacts live. It must stay clean at
+every moment, not only at the end.
+
+## Layout
+
+```text
+math-modeling-runs/<task-id>/
+├── run.json  ledger.json  events.jsonl        # run-state files (only run-state.mjs writes them)
+├── problem-brief.md  inputs.json              # frozen restatement + input manifest
+├── attempts/<n>/
+│   ├── report.md                              # 13-section contract + 8-section digest
+│   ├── code/                                  # final reproducible scripts ONLY (clean)
+│   ├── data/                                  # results: json/csv/npy/xlsx
+│   ├── plots/                                 # figures
+│   └── _drafts/                               # this attempt's exploratory code (kept, isolated)
+├── failed/
+│   ├── directions/<id>/                       # direction-level failures: wall memo + code + why
+│   ├── code-drafts/<attempt>-<name>/          # implementation-level failures: buggy/timed-out/deprecated
+│   └── issues.md                              # failure ledger index (see below)
+├── research/                                  # literature (only when research happened)
+├── walls/                                     # breakthrough memos (legacy path kept)
+├── result.xlsx                                # the deliverable (when the problem asks for one)
+├── reproducibility.json                       # final command list + env + hashes
+└── final-report.md                            # terminal report
+```
+
+## Failure classification (failure ledger)
+
+Every problem in ANY stage is recorded in `failed/issues.md` with:
+
+```text
+#<seq> | 环节(DATA/TOOL/IMPLEMENTATION/MODEL/VALIDATION/EVIDENCE/RESEARCH_GAP) | 发现时间/attempt
+症状：…
+根因：…
+处置：修了/绕过/放弃(→wall memo id)
+影响：哪些 claim/obligation 被污染，下游如何重验
+```
+
+Direction-level failures additionally get `failed/directions/<id>/wall.md`
+(target, paths tried, exact wall, wall type, breakthrough condition, restart
+checklist) and their code snapshot. Implementation-level failures get
+`failed/code-drafts/<attempt>-<name>/` with a README stating the failure.
+
+## Cleanup gate (MUST run before ANY terminal transition)
+
+1. attempts/<n>/code contains only the final reproducible scripts; each starts
+   with a header comment: purpose, inputs, outputs, reproduction command.
+   Exploratory/buggy versions move to `_drafts/` or `failed/code-drafts/` — never deleted.
+2. No debug prints, unused variables, or hardcoded machine-specific paths
+   (the data-root constant is the only allowed absolute path).
+3. Figures in `plots/`, tables in `data/`; the deliverable at the run root.
+4. reproducibility.json is complete and matches the final scripts.
+5. `run-state.mjs validate <dir>` passes and every obligation has a terminal status.
+6. The cleanup itself is noted in the terminal transition reason.
+
+## Tidiness invariants
+
+- Code is refactored as soon as it stabilizes within an attempt (not only at the end).
+- Every script file maps 1:1 to an attempt artifact or a final deliverable.
+- Nothing outside the run directory is written by the modeling work.

package/skills/math-modeling-agent/references/subagent-dispatch.md

@@ -0,0 +1,47 @@
+# Subagent Dispatch Protocol
+
+The coordinator (main agent) owns the ledger and the decision stack; subagents
+produce reports and evidence. Never let a subagent mutate run-state directly.
+
+## Three dispatch classes
+
+| Class | Role (lineage) | When | Count |
+|---|---|---|---|
+| explorer | parallel candidate exploration (legacy Modeler) | CANDIDATES_READY, >= 2 independent directions | 1 per direction |
+| verifier | blind re-verification (legacy Analyzer/Correction) | before terminal: key numeric/feasibility claims | Standard: 1 per task; High-Assurance: 1 per claim |
+| auditor | artifact-only audit (math-modeling-audit skill) | before SOLVED | High-Assurance: mandatory; else optional |
+
+## Brief template (self-contained; subagents see no parent context)
+
+```text
+任务目标：<one claim or one direction, exactly>
+输入：<file paths + hashes, run dir is read-only>
+已知事实：<data profile / geometry facts / problem restatement excerpt>
+允许工具：<explicit list; private raw data never leaves the workspace>
+验证要求：<which obligations this subagent must produce evidence for>
+输出格式：
+  结论（一句话，可证伪）
+  方法
+  执行记录（命令 + 关键输出 + 退出码）
+  证据（证据 ID、等级、局限）
+  失败点与反例（若有）
+  建议（下一步或放弃理由）
+边界：<不准做什么，例如"不得修改 run 文件、不得检索题解">
+```
+
+## Adjudication rules
+
+- The coordinator reads every report against its brief; a report without
+  reproducible commands or evidence IDs is not accepted.
+- Two conflicting reports → a second blind round with both reports as input.
+- Blind verification means: the verifier receives the claim, the data, and the
+  problem text — never the solver's private reasoning. Its agreement upgrades
+  the claim to INDEPENDENTLY_VERIFIED; its disagreement opens a critical issue.
+- Every dispatch is recorded in the ledger (candidates / issues) with the
+  subagent label, brief hash, and verdict.
+
+## Failure bookkeeping
+
+- A failed or abandoned direction writes a wall memo first
+  (`failed/directions/<id>/wall.md` per run-directory.md), then the branch is
+  closed. Nothing is deleted; every wrong path stays inspectable.

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

@@ -4,6 +4,24 @@
 
 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.
 
+## Long-running commands (stall governance, v2)
+
+- Estimate BEFORE starting: anything expected > 60 s MUST run in the background
+  (run_in_background), and the chat gets one line immediately: what runs, the
+  estimate, and what independent work continues in parallel. Never idle-wait.
+- Tasks running > 3 minutes get a proactive progress check (job_output) with a
+  one-line progress report to the chat.
+- Expensive computations are benchmarked on a small subset first (e.g. 20-node
+  trial) to calibrate the full-run estimate.
+- On job completion, report the outcome within the same round.
+
+## Tool selection visibility (v2)
+
+At the start of every phase, say ONE line about the tool choice and why:
+e.g. "本阶段用 Python+OSQP 做约束优化；Wolfram 对本题非必需，跳过；Lean 不适用".
+The problem never silently depends on a single tool: every phase names its
+backend, its fallback, and the degradation path when the backend fails.
+
 ## 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.

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

@@ -13,6 +13,37 @@ TRIAGE → SCOPE_FROZEN → INPUT_PROFILED → CLAIMS_REGISTERED → CANDIDATES_
 VERIFY may move to REVISE, RESEARCH, FORK, an independent audit, or one terminal status:
 SOLVED, PARTIAL, CONDITIONAL, INCONCLUSIVE, REFUTED, INFEASIBLE, UNIDENTIFIABLE, BLOCKED, CANCELLED.
 
+## Interaction gates (v2)
+
+Before EVERY transition run `run-state.mjs gate <dir> --to <status> --reason "..."`
+and report one status line in the chat: `[状态] FROM → TO：一句话原因`.
+The gate enforces the L1 interaction records (interaction-protocol.md) and the
+robustness gate: terminal states require a PASSED robustness-kind obligation
+(parameter perturbation × magnitude × conclusion-flip judgment) unless
+scope.robustnessExempt is set with a reason.
+
+## Backtracking
+
+- REVISE/RESEARCH reasons MUST reference a decisionStack entry id; the round
+  returns to that decision point and tries the next option.
+- FORK records its fork point; each failed branch writes a wall memo
+  (run-directory.md) before the next branch starts. A wrong direction always
+  returns to the fork point, never mid-branch.
+- Every stage problem (DATA/TOOL/IMPLEMENTATION/MODEL/VALIDATION/EVIDENCE/
+  RESEARCH_GAP) is recorded in failed/issues.md.
+
+## Dispatch (see subagent-dispatch.md)
+
+- >= 2 independent directions → explorer subagents in parallel, coordinator adjudicates.
+- Before terminal: blind verifier subagent for key claims (Standard: 1 per task).
+- High-Assurance: auditor subagent (math-modeling-audit) before SOLVED.
+
+## Cleanup gate
+
+Before ANY terminal transition, run the cleanup checklist in run-directory.md
+(clean code/, _drafts/, failed/ classification, reproducibility.json,
+validate). Note the cleanup in the transition reason.
+
 ## Round contract
 
 Each round has one objective and records:

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

@@ -17,16 +17,35 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": 1
+      "const": 2
     },
     "taskId": {
       "type": "string"
     },
     "scope": {
-      "type": "object"
+      "type": "object",
+      "properties": {
+        "independentAuditPassed": { "type": "boolean" },
+        "interactions": {
+          "type": "array",
+          "description": "L1 decision-point records: {id, decisionPoint: D1|D2|D3|D4, question, options, userAnswer, timestamp, effectOnModel} or {auto: true, decisionPoint, reason}",
+          "items": { "type": "object" }
+        },
+        "decisionStack": {
+          "type": "array",
+          "description": "Decision-point stack for backtracking: {id (e.g. D3-SP1), point, choice, at, reason}. REVISE/RESEARCH reasons must reference an entry id.",
+          "items": { "type": "object" }
+        },
+        "robustnessExempt": {
+          "type": "boolean",
+          "description": "True only for tasks with no perturbable parameters (pure proofs); terminal states otherwise require a PASSED robustness-kind obligation."
+        }
+      }
     },
     "assumptions": {
-      "type": "array"
+      "type": "array",
+      "description": "Per-subproblem incremental assumptions: {id, statement, scope: [SPx]|global, source, status: active|revised|superseded, risk, sensitivityPlan, revisionHistory: [{at, reason, changedTo}]}",
+      "items": { "type": "object" }
     },
     "claims": {
       "type": "array"
@@ -35,7 +54,9 @@
       "type": "array"
     },
     "subproblems": {
-      "type": "array"
+      "type": "array",
+      "description": "Subproblem DAG nodes: {id, task, inputs, dependencies, acceptance, status, analysisLog: [{at, entry, trigger}]} — analysisLog is the rolling analysis ledger.",
+      "items": { "type": "object" }
     },
     "candidates": {
       "type": "array"

package/skills/math-modeling-agent/scripts/python-environment.mjs

@@ -35,11 +35,12 @@ async function atomicWriteJson(path, value, { renamePath = rename, removePath =
   }
 }
 
-export function defaultSpawnOptions({ cwd, stdoutDescriptor } = {}) {
+export function defaultSpawnOptions({ cwd, stdoutDescriptor, timeout } = {}) {
   return {
     cwd,
     shell: false,
     stdio: ['ignore', stdoutDescriptor ?? 2, 2],
+    timeout,
   }
 }
 
@@ -50,7 +51,10 @@ async function defaultRun(command, args, options = {}) {
     const result = spawnSync(command, args, defaultSpawnOptions({
       cwd: options.cwd,
       stdoutDescriptor: descriptor,
+      timeout: options.timeout,
     }))
+    if (result.error) throw result.error
+    if (result.status === null) throw new Error(`${options.label ?? command} timed out after ${options.timeout} ms — network-bound installs can be slow; check the pip mirror configuration and re-run`)
     return result.status ?? 1
   } finally {
     if (descriptor !== undefined) closeSync(descriptor)
@@ -322,6 +326,8 @@ export async function createPythonEnvironment(input) {
     const finalPythonPath = environmentPython(environmentDir, platform, resolvePath)
     try {
       let adapter
+      const installLogPath = ensureContained(runDir, resolvePath(runDir, 'python-environment-install.log'), platform)
+      const installOptions = { cwd: runDir, stdoutFile: installLogPath, timeout: 20 * 60 * 1000, label: 'package install' }
       if (uv) {
         adapter = 'uv'
         const createArgs = ['venv', '--seed', environmentDir]
@@ -329,8 +335,9 @@ export async function createPythonEnvironment(input) {
         assertSuccess(await runCommand(uv.executable, createArgs, { cwd: runDir }), 'uv venv')
         if (packages.length) {
           const installArgs = ['pip', 'install', '--python', finalPythonPath, ...packages]
-          commands.push({ command: uv.executable, args: installArgs })
-          assertSuccess(await runCommand(uv.executable, installArgs, { cwd: runDir }), 'uv pip install')
+          commands.push({ command: uv.executable, args: installArgs, stdoutFile: installLogPath })
+          process.stderr.write(`python-environment: uv installing ${packages.length} package(s); network-bound, may take minutes; log: ${installLogPath}\n`)
+          assertSuccess(await runCommand(uv.executable, installArgs, installOptions), 'uv pip install')
         }
       } else {
         adapter = 'venv'
@@ -339,8 +346,9 @@ export async function createPythonEnvironment(input) {
         assertSuccess(await runCommand(python.executable, createArgs, { cwd: runDir }), 'python venv')
         if (packages.length) {
           const installArgs = ['-m', 'pip', 'install', ...packages]
-          commands.push({ command: finalPythonPath, args: installArgs })
-          assertSuccess(await runCommand(finalPythonPath, installArgs, { cwd: runDir }), 'pip install')
+          commands.push({ command: finalPythonPath, args: installArgs, stdoutFile: installLogPath })
+          process.stderr.write(`python-environment: pip installing ${packages.length} package(s); network-bound, may take minutes; log: ${installLogPath}\n`)
+          assertSuccess(await runCommand(finalPythonPath, installArgs, installOptions), 'pip install')
         }
       }
       await mkdir(environmentDir, { recursive: true })

package/skills/math-modeling-agent/scripts/run-state.mjs

@@ -4,7 +4,9 @@ import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { isDeepStrictEqual } from 'node:util'
 
-export const SCHEMA_VERSION = 1
+export const SCHEMA_VERSION = 2
+export const SUPPORTED_SCHEMA_VERSIONS = [1, 2]
+export const INTERACTION_DECISIONS = Object.freeze({ D1: 'routing', D2: 'assumptions', D3: 'direction', D4: 'verdict' })
 export const MODE_DEFAULTS = Object.freeze({
   fast: Object.freeze({ attempts: 2, researchQueries: 0, computeSeconds: 60 }),
   standard: Object.freeze({ attempts: 12, researchQueries: 12, computeSeconds: 1800 }),
@@ -282,7 +284,7 @@ function deeplyEqual(left, right) { return isDeepStrictEqual(left, right) }
 function validateRunShape(run, diagnostics, prefix = 'run') {
   addDiagnostic(diagnostics, exactKeys(run, RUN_KEYS), `${prefix} must contain exactly the contracted fields`)
   if (!isObject(run)) return
-  addDiagnostic(diagnostics, run.schemaVersion === SCHEMA_VERSION, `${prefix}.schemaVersion must equal ${SCHEMA_VERSION}`)
+  addDiagnostic(diagnostics, SUPPORTED_SCHEMA_VERSIONS.includes(run.schemaVersion), `${prefix}.schemaVersion must be one of ${SUPPORTED_SCHEMA_VERSIONS.join(',')}`)
   addDiagnostic(diagnostics, typeof run.taskId === 'string' && TASK_ID.test(run.taskId), `${prefix}.taskId must be kebab-case`)
   addDiagnostic(diagnostics, Object.hasOwn(MODE_DEFAULTS, run.mode), `${prefix}.mode is invalid`)
   addDiagnostic(diagnostics, STATUSES.includes(run.status), `${prefix}.status is invalid`)
@@ -297,7 +299,7 @@ function validateRunShape(run, diagnostics, prefix = 'run') {
 function validateLedgerShape(ledger, diagnostics) {
   addDiagnostic(diagnostics, exactKeys(ledger, LEDGER_KEYS), 'ledger must contain exactly the contracted fields')
   if (!isObject(ledger)) return
-  addDiagnostic(diagnostics, ledger.schemaVersion === SCHEMA_VERSION, `ledger.schemaVersion must equal ${SCHEMA_VERSION}`)
+  addDiagnostic(diagnostics, SUPPORTED_SCHEMA_VERSIONS.includes(ledger.schemaVersion), `ledger.schemaVersion must be one of ${SUPPORTED_SCHEMA_VERSIONS.join(',')}`)
   addDiagnostic(diagnostics, typeof ledger.taskId === 'string' && TASK_ID.test(ledger.taskId), 'ledger.taskId must be kebab-case')
   addDiagnostic(diagnostics, isObject(ledger.scope), 'ledger.scope must be an object')
   for (const key of ['assumptions', 'claims', 'obligations', 'subproblems', 'candidates', 'issues']) addDiagnostic(diagnostics, Array.isArray(ledger[key]), `ledger.${key} must be an array`)
@@ -312,7 +314,7 @@ function validateEventShape(event, diagnostics, index) {
     ? ['schemaVersion', 'sequence', 'type', 'taskId', 'timestamp', 'snapshot']
     : ['schemaVersion', 'sequence', 'type', 'taskId', 'from', 'to', 'reason', 'evidenceIds', 'issueIds', 'timestamp', 'snapshot']
   addDiagnostic(diagnostics, exactKeys(event, expectedKeys), `${prefix} must contain exactly the contracted fields`)
-  addDiagnostic(diagnostics, event.schemaVersion === SCHEMA_VERSION, `${prefix}.schemaVersion must equal ${SCHEMA_VERSION}`)
+  addDiagnostic(diagnostics, SUPPORTED_SCHEMA_VERSIONS.includes(event.schemaVersion), `${prefix}.schemaVersion must be one of ${SUPPORTED_SCHEMA_VERSIONS.join(',')}`)
   addDiagnostic(diagnostics, event.sequence === index, `${prefix}.sequence must equal ${index}`)
   addDiagnostic(diagnostics, typeof event.taskId === 'string' && TASK_ID.test(event.taskId), `${prefix}.taskId must be kebab-case`)
   addDiagnostic(diagnostics, event.type === expectedType, `${prefix}.type must be ${expectedType}`)
@@ -377,8 +379,8 @@ export async function initRun(root, { taskId, mode = 'standard', budget, budgets
       bestCandidateId: null, budget: effectiveBudget, createdAt: timestamp, updatedAt: timestamp,
     }
     const ledger = {
-      schemaVersion: SCHEMA_VERSION, taskId, scope: { independentAuditPassed: false }, assumptions: [], claims: [],
-      obligations: [], subproblems: [], candidates: [], issues: [],
+      schemaVersion: SCHEMA_VERSION, taskId, scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false },
+      assumptions: [], claims: [], obligations: [], subproblems: [], candidates: [], issues: [],
     }
     const event = { schemaVersion: SCHEMA_VERSION, sequence: 0, type: 'RUN_INITIALIZED', taskId, timestamp, snapshot: clone(run) }
     const p = paths(root)
@@ -409,6 +411,61 @@ export async function initRun(root, { taskId, mode = 'standard', budget, budgets
   }, runtime)
 }
 
+/** The v2 interaction contract: decision records, decision-stack backtracking, and the robustness gate. */
+function hasDecisionRecord(scope, decisionPoint) {
+  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
+    entry && (entry.decisionPoint === decisionPoint || entry.auto === true))
+}
+function decisionStackIds(scope) {
+  return Array.isArray(scope?.decisionStack)
+    ? scope.decisionStack.filter(entry => entry && typeof entry.id === 'string').map(entry => entry.id)
+    : []
+}
+/** D2 records carry the subproblem id(s) they cover: {decisionPoint:'D2', scope:['SP1'], ...} */
+function hasSubproblemD2(scope, subproblem) {
+  if (!subproblem || !Array.isArray(scope?.interactions)) return true
+  return scope.interactions.some(entry => entry && entry.decisionPoint === 'D2' &&
+    (Array.isArray(entry.scope) ? entry.scope.includes(subproblem) : entry.subproblem === subproblem))
+}
+function interactionContractViolations(run, ledger, to, reason, subproblem) {
+  if (ledger.schemaVersion !== SCHEMA_VERSION) return []
+  const scope = ledger.scope ?? {}
+  const violations = []
+  const transitional = to !== undefined
+  const earlyStop = ['BLOCKED', 'CANCELLED'].includes(run.status)
+  if ((transitional && to === 'SCOPE_FROZEN') || (!transitional && run.status !== 'TRIAGE' && !earlyStop)) {
+    if (!hasDecisionRecord(scope, 'D0')) violations.push('D0 restatement interaction record missing (ledger.scope.interactions)')
+    if (!hasDecisionRecord(scope, 'D1')) violations.push('D1 routing interaction record missing (ledger.scope.interactions)')
+  }
+  const enteringAttemptFromCandidates = transitional ? (to === 'ATTEMPT' && run.status === 'CANDIDATES_READY') : (run.currentAttempt >= 1)
+  if (enteringAttemptFromCandidates) {
+    if (!hasDecisionRecord(scope, 'D3')) violations.push('D3 direction-selection interaction record missing')
+    if (transitional && !hasSubproblemD2(scope, subproblem)) violations.push(`D2 assumption interaction record missing for subproblem ${subproblem} (run the gate with --subproblem <id>)`)
+  }
+  const enteringTerminalFromVerify = transitional
+    ? (FINAL_STATES.includes(to) && run.status === 'VERIFY')
+    : (FINAL_STATES.includes(run.status) && !['BLOCKED', 'CANCELLED'].includes(run.status))
+  if (enteringTerminalFromVerify && !hasDecisionRecord(scope, 'D4')) violations.push('D4 verdict interaction record missing')
+  if (transitional && (to === 'REVISE' || to === 'RESEARCH')) {
+    const ids = decisionStackIds(scope)
+    if (ids.length > 0 && !ids.some(id => typeof reason === 'string' && reason.includes(id))) {
+      violations.push(`REVISE/RESEARCH reason must reference a decisionStack entry id (available: ${ids.join(', ')})`)
+    }
+  }
+  const terminalAndExempt = transitional
+    ? (FINAL_STATES.includes(to) && !['BLOCKED', 'CANCELLED'].includes(to))
+    : (FINAL_STATES.includes(run.status) && !['BLOCKED', 'CANCELLED'].includes(run.status))
+  if (terminalAndExempt && scope.robustnessExempt !== true) {
+    const passed = Array.isArray(ledger.obligations) && ledger.obligations.some(o => o && o.kind === 'robustness' && o.status === 'PASS')
+    if (!passed) violations.push('terminal state requires a PASSED robustness-kind obligation (or scope.robustnessExempt: true)')
+  }
+  return violations
+}
+function enforceInteractionContract(run, ledger, to, reason) {
+  const violations = interactionContractViolations(run, ledger, to, reason)
+  if (violations.length > 0) throw new Error(`interaction contract violated: ${violations.join('; ')}`)
+}
+
 function enforceSolvedGate(run, ledger) {
   if (ledger.claims.length < 1) throw new Error('SOLVED requires at least one claim')
   if (ledger.obligations.some(item => item.required !== false && item.status !== 'PASS')) throw new Error('required obligations remain open')
@@ -473,12 +530,13 @@ async function readEvents(path) {
 
 async function validateRunUnlocked(root, expectedTaskId) {
   const diagnostics = []
+  const warnings = []
   let run, ledger, events
   const p = paths(root)
   try { run = await readJson(p.run) } catch (error) { diagnostics.push(`run unreadable: ${error.message}`) }
   try { ledger = await readJson(p.ledger) } catch (error) { diagnostics.push(`ledger unreadable: ${error.message}`) }
   try { events = await readEvents(p.events) } catch (error) { diagnostics.push(error.message) }
-  if (!run || !ledger || !events) return { valid: false, diagnostics }
+  if (!run || !ledger || !events) return { valid: false, diagnostics, warnings }
   validateRunShape(run, diagnostics)
   validateLedgerShape(ledger, diagnostics)
   validateJournal(events, diagnostics)
@@ -486,13 +544,45 @@ async function validateRunUnlocked(root, expectedTaskId) {
   const last = events.at(-1)
   if (last && run.eventSequence !== last.sequence) diagnostics.push('state/journal sequence mismatch')
   if (last && JSON.stringify(run) !== JSON.stringify(last.snapshot)) diagnostics.push('state/journal snapshot mismatch')
-  return { valid: diagnostics.length === 0, diagnostics, run: clone(run) }
+  if (ledger.schemaVersion !== SCHEMA_VERSION) warnings.push(`legacy run (ledger schema v${ledger.schemaVersion}): interaction contract not enforced`)
+  else {
+    for (const violation of interactionContractViolations(run, ledger, undefined, undefined)) {
+      warnings.push(`interaction contract: ${violation}`)
+    }
+    if (run.currentAttempt >= 1) {
+      const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
+      try {
+        const reportText = await readFile(reportPath, 'utf8')
+        for (const section of ['问题重述', '问题分析', '模型假设', '模型建立与求解', '验证', '鲁棒性', '评价与改进', '参考文献']) {
+          if (!reportText.includes(section)) warnings.push(`attempt ${run.currentAttempt} report.md missing runlog digest section: ${section}`)
+        }
+      } catch {
+        warnings.push(`attempt ${run.currentAttempt} report.md unreadable (runlog digest required)`)
+      }
+    }
+  }
+  return { valid: diagnostics.length === 0, diagnostics, warnings, run: clone(run) }
 }
 
 export async function validateRun(root, expectedTaskId, runtime = {}) {
   return withLock(root, MUTATION_LOCK_FILE, 'validate', () => validateRunUnlocked(root, expectedTaskId), runtime)
 }
 
+/**
+ * Check the v2 interaction contract for a PROSPECTIVE transition without
+ * mutating anything. The agent workflow must call this before `transition`;
+ * the CLI `transition` command enforces it internally unless --skip-gate.
+ */
+export async function gateTransition(root, { to, reason, subproblem }, runtime = {}) {
+  return withLock(root, MUTATION_LOCK_FILE, 'gate', async () => {
+    const p = paths(root)
+    const run = await readJson(p.run)
+    const ledger = await readJson(p.ledger)
+    const violations = interactionContractViolations(run, ledger, to, reason, subproblem)
+    return { allowed: violations.length === 0, violations, status: run.status }
+  }, runtime)
+}
+
 export async function recoverRun(root, runtime = {}) {
   return withLock(root, MUTATION_LOCK_FILE, 'recover', async () => {
     const p = paths(root)
@@ -533,7 +623,21 @@ async function cli(argv) {
   const root = resolve(rootArg)
   const options = parseOptions(rest)
   if (command === 'init') return initRun(root, { taskId: options['task-id'], mode: options.mode ?? 'standard' })
-  if (command === 'transition') return transitionRun(root, { to: options.to, reason: options.reason, evidenceIds: options.evidence ? options.evidence.split(',').filter(Boolean) : [], issueIds: options.issues ? options.issues.split(',').filter(Boolean) : [], patch: options.candidate ? { bestCandidateId: options.candidate } : undefined })
+  if (command === 'gate') {
+    const result = await gateTransition(root, { to: options.to, reason: options.reason, subproblem: options.subproblem })
+    if (!result.allowed) process.exitCode = 1
+    return result
+  }
+  if (command === 'transition') {
+    if (options['skip-gate'] !== 'true') {
+      const gate = await gateTransition(root, { to: options.to, reason: options.reason, subproblem: options.subproblem })
+      if (!gate.allowed) {
+        process.exitCode = 1
+        return { error: `interaction contract violated: ${gate.violations.join('; ')}`, gate }
+      }
+    }
+    return transitionRun(root, { to: options.to, reason: options.reason, evidenceIds: options.evidence ? options.evidence.split(',').filter(Boolean) : [], issueIds: options.issues ? options.issues.split(',').filter(Boolean) : [], patch: options.candidate ? { bestCandidateId: options.candidate } : undefined })
+  }
   if (command === 'validate') {
     const result = await validateRun(root, options['task-id'])
     if (!result.valid) process.exitCode = 1
@@ -541,7 +645,7 @@ async function cli(argv) {
   }
   if (command === 'recover') return recoverRun(root)
   if (command === 'status') return statusRun(root)
-  throw new Error('usage: run-state.mjs <init|transition|validate|recover|status> <run-directory> [options]')
+  throw new Error('usage: run-state.mjs <init|transition|gate|validate|recover|status> <run-directory> [options]')
 }
 const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 if (invoked) cli(process.argv.slice(2)).then(result => process.stdout.write(`${JSON.stringify(result)}\n`)).catch(error => { process.stdout.write(`${JSON.stringify({ error: error.message })}\n`); process.exitCode = 1 })