dsh-math-modeling-agent 0.3.1 → 0.5.0

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

@@ -1,56 +1,70 @@
----
-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.
-
-Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is a DEEP three-beat exchange — LLM presents a complete analysis with its evidence chain, the user responds with substance (corrections, background, their own references), the LLM updates the artifact and shows the delta. Decision points: D0 six-section restatement / D1 routing once per task, D-R literature research before any candidate is built, 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`; ask D1 (task type + assurance mode).
-2. Literature research FIRST: transition TRIAGE → RESEARCH, search principles and methods by direction (never contest solutions), write `research/sources.jsonl` + methods matrix, ask D-R (user endorses/rejects/adds).
-3. Show the D0 deep restatement — six sections plus the question-dependency relation — and ask D0; gate SCOPE_FROZEN (requires D0+D1+D-R).
-4. Panorama analysis + data profile (INPUT_PROFILED) with user interaction; global assumptions G-class confirmed via D2-G before CLAIMS_REGISTERED.
-5. Register claims and obligations; build the candidate matrix with literature column (CANDIDATES_READY) and ask D3.
-6. For EACH subproblem: subproblem analysis (reference the panorama, do not re-derive), S-class assumptions via D2-SPi, then ATTEMPT → EXECUTE → VERIFY → subproblem robustness (plan→interact→run) → D4 verdict → REVISE or move to the next subproblem.
-7. Live documents: any discovery that shows an earlier phase was incomplete patches that phase incrementally (revision + stale), never re-running unaffected completed work.
-8. Backtracking depth follows the failure root cause (attempt/verify/direction/assumption/analysis/restatement/research), recorded in failed/issues.md.
-9. Probe tools with `scripts/capability-probe.mjs`; create a run-local Python environment with `scripts/python-environment.mjs` when computation is required; announce the tool choice and fallback.
-10. Dispatch subagents for parallel exploration, blind verification, and audits per `references/subagent-dispatch.md`.
-11. Escalate evidence gaps through `references/research-breakthrough.md`; write wall memos and the failure ledger per `references/run-directory.md`.
-12. Write incremental attempt and terminal reports per `references/report-contract.md`; output the per-round runlog digest in the chat.
-13. Before any terminal transition: cleanup gate, ALL required robustness obligations PASS (or robustnessExempt), every subproblem DONE with dependencies satisfied, D4 for the current attempt, report.md present.
-
-## 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; 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
-
-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.
+---
+name: math-modeling-agent
+description: 当用户要求分析数学建模题、读取题目附件、建立预测/优化/估计/仿真模型、比较建模方向、执行数值验证、进行鲁棒性分析或继续已有建模项目时使用。
+whenToUse: 用于开放式数学建模、预测、优化、估计、仿真、机制分析、决策和多小问竞赛题；已有成果的独立审计改用 math-modeling-audit，不在此处静默改写被审计成果。
+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.
+
+Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is a DEEP three-beat exchange — LLM presents a complete analysis with its evidence chain, the user responds with substance (corrections, background, their own references), the LLM updates the artifact and shows the delta. Decision points: D0 six-section restatement / D1 routing once per task, D-R literature research before any candidate is built, 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. The legacy Modeler → Analyzer → Correction behavior mapping is recorded in `references/original-project-parity.md`.
+
+## Default workflow
+
+1. Route the task to Fast, Standard, or High-Assurance using `references/problem-types.md`; ask D1 (task type + assurance mode).
+2. Literature research FIRST: transition TRIAGE → RESEARCH, search principles and methods by direction (never contest solutions), write `research/sources.jsonl` + methods matrix, ask D-R (user endorses/rejects/adds).
+3. Show the D0 deep restatement — six sections plus the question-dependency relation — and ask D0; gate SCOPE_FROZEN (requires D0+D1+D-R).
+4. Panorama analysis + data profile (INPUT_PROFILED) with user interaction; global assumptions G-class confirmed via D2-G before CLAIMS_REGISTERED.
+5. Register claims and obligations; build the candidate matrix with literature column (CANDIDATES_READY) and ask D3.
+6. For EACH subproblem: subproblem analysis (reference the panorama, do not re-derive), S-class assumptions via D2-SPi, then ATTEMPT → EXECUTE → VERIFY → subproblem robustness (plan→interact→run) → D4 verdict → REVISE or move to the next subproblem.
+7. Live documents: any discovery that shows an earlier phase was incomplete patches that phase incrementally (revision + stale), never re-running unaffected completed work.
+8. Backtracking depth follows the failure root cause (attempt/verify/direction/assumption/analysis/restatement/research), recorded in failed/issues.md.
+9. Probe tools with `scripts/capability-probe.mjs`; create a run-local Python environment with `scripts/python-environment.mjs` when computation is required; announce the tool choice and fallback.
+10. Dispatch subagents for parallel exploration, blind verification, and audits per `references/subagent-dispatch.md`.
+11. Escalate evidence gaps through `references/research-breakthrough.md`; write wall memos and the failure ledger per `references/run-directory.md`.
+12. Write incremental attempt and terminal reports per references/report-contract.md; output the per-round runlog digest in the chat.
+13. Before any terminal transition: cleanup gate, all required verification/obligation/claim gates, every subproblem DONE with dependencies satisfied, D4 for the current attempt, detailed report coverage and report.md present.
+14. Use inputs/raw and inputs/manifest.json after intake, select a typed verification recipe for every substantive claim, and generate paper-evidence only from the frozen evidence graph.
+
+## 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; 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).
+
+## Computation tool extension
+
+When a computation is required, first call the bundled backend probe:
+`python scripts/computation/probe_backends.py`
+(or the `.ps1` entrypoint when Python is unavailable). Choose only a backend
+reported callable; record the primary route and fallback. Use
+`scripts/computation/backend_inventory.py` with a run-local `--state-file`
+when a persistent capability snapshot is needed. For reproducible/file or
+high-assurance work, initialize and validate
+`scripts/computation/computation_record.py`. These scripts discover and record
+external backends; they are not mathematical engines and their successful
+execution is not proof.
+
+## 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/references/claims-evidence.md

@@ -1,41 +1,53 @@
-# 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 (v2)
-
-Store id, statement, scope ('global' for whole-problem assumptions, or a subproblem id list), 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.
-
-Two classes: G-class (global, confirmed once in the panorama layer via D2-G) and S-class (per subproblem, confirmed via D2-SPi). Claims carry an `assumptions` field listing the assumption ids they depend on; when an assumption is revised, dependent claims are marked stale and must carry post-revision evidence before a terminal state (validate warns otherwise).
-
-Every assumption additionally carries a `basis` field — the evidence chain behind it: `problem-quote` (exact original wording), `data` (evidence id + statistic), `literature` (source id + excerpt location), or `llm-judgment` (explicitly flagged as the LLM's own inference, challengeable in D2).
-
-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.
-- 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.
+# 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 (v2)
+
+Store id, statement, scope ('global' for whole-problem assumptions, or a subproblem id list), 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.
+
+Two classes: G-class (global, confirmed once in the panorama layer via D2-G) and S-class (per subproblem, confirmed via D2-SPi). Claims carry an `assumptions` field listing the assumption ids they depend on; when an assumption is revised, dependent claims are marked stale and must carry post-revision evidence before a terminal state (validate warns otherwise).
+
+Every assumption additionally carries a `basis` field — the evidence chain behind it: `problem-quote` (exact original wording), `data` (evidence id + statistic), `literature` (source id + excerpt location), or `llm-judgment` (explicitly flagged as the LLM's own inference, challengeable in D2).
+
+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.
+- 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.
+
+## v0.5 status and artifact rules
+
+Verification verdicts are PASS, FAIL, INCONCLUSIVE or NOT_RUN. Obligation statuses are OPEN, SATISFIED, BLOCKED, WAIVED or STALE. Claim verdicts are SUPPORTED, CONDITIONAL, INCONCLUSIVE, REFUTED or STALE. A verification PASS never directly sets a claim or run status.
+
+Evidence is a first-class artifact with coveredClaimIds, coveredObligationIds, artifactPath, inputHashes, outputHashes, command, workdir, environment, exitCode, methodFamily, codeHash, level and limitations. Reusing the same deterministic result, solver summary, derived artifact, code path or reprint is not independent evidence.
+
+When evidence or an upstream assumption changes, dependent claims, obligations and reports carry staleReason and staleSourceIds and must be reverified or explicitly downgraded.
+
+## Failure insight contract
+
+MODEL, ASSUMPTION, ANALYSIS, VALIDATION and EVIDENCE failures must preserve whatWasRuledOut, scientificInsight, affected claims/obligations, minimal reproduction, recovery route and evidence IDs. A failed direction is reusable scientific evidence only when its boundary and exclusion are explicit; private chain-of-thought is never stored.

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

@@ -1,163 +1,165 @@
-# Interaction Protocol (v2)
-
-Three interaction layers. Execution details stay autonomous; every
-model-shaping decision is visible and user-owned.
-
-## Deep-exchange protocol (v2.6)
-
-Every L1 decision point follows a three-beat exchange, never a one-way
-"here is my conclusion, confirm it":
-
-1. **LLM presents a complete analysis with its evidence chain.** Every claim
-   inside the analysis carries its basis: an exact quote from the problem
-   text, a data statistic, a literature source id, or an explicit
-   "LLM judgment" marker. A naked conclusion is not a presentation.
-2. **The user responds with substance**: confirmation, correction, background
-   knowledge, their own references, or their own judgment. A pure "ok" is
-   accepted, but the protocol must have OFFERED the space for substance —
-   the questions must be open, not yes/no gates.
-3. **The LLM updates the artifact and shows the delta.** The restatement,
-   analysis log, assumption list, or candidate matrix is edited and the chat
-   shows exactly which points changed because of the user's input.
-
-High-impact points (D0, D-R, D2) may loop beats 2-3 as many times as needed
-until the user says "可以了". Mathematical modeling is a deep activity;
-"skim and start solving" is a protocol violation.
-
-## L1 decision points (MUST ask via the question tool)
-
-| Point | Trigger | Question | Default |
-|---|---|---|---|
-| D0 问题重述 | intake complete | the six-section deep restatement below + open clarification questions | accept + no additions |
-| D1 路由 | TRIAGE | task type (prediction/optimization/explanation/proof/…) + assurance mode (Fast/Standard/High-Assurance) | auto-routing result |
-| D-R 文献研究 | CLAIMS_REGISTERED (before CANDIDATES_READY) | the literature list by direction (AI-found); user endorses / rejects / adds their own | accept list |
-| D2-G 全局假设确认 | CLAIMS_REGISTERED (全景层) | the GLOBAL assumptions that hold for the whole problem (geometry, data, physical mechanism, numerical basis) — each with basis chain + risk | accept all |
-| D2 子问题假设确认 | **each subproblem starts** | the assumptions for THIS subproblem only (S-class), each with statement + basis chain + risk | accept all |
-| D2' 新假设插问 | mid-subproblem discovery that changes model structure | the new assumption + its effect | record-and-continue |
-| D3 方向选择 | CANDIDATES_READY | candidate matrix with a literature column per direction; user picks or authorizes auto | baseline |
-| D4 结果裁决 | VERIFY done | verdict + evidence digest + key intermediate results (residual/constraint-violation distributions, figure paths) + failure details | verdict-implied |
-
-## D0 deep restatement — six sections (MANDATORY structure)
-
-1. **题目要点摘录**：the problem's own numbers and constraints, quoted.
-2. **背景解读**：the engineering/physical mechanism behind the problem.
-3. **数据语义**：every attachment, column by column — meaning, units,
-   coordinate system, magnitudes; unreadable artifacts are flagged with the
-   minimum representation needed.
-4. **隐含信息与歧义清单**：numbered; each entry = the LLM's reading + its
-   basis + the risk if the reading is wrong. This is the heart of the
-   exchange: the user corrects entries here.
-5. **各子问题数学本质判定**：every sub-question of the problem — however
-   many there are (one or ten) — is classified (fitting/optimization/
-   geometric optics/simulation/…), with why.
-5.5 **问间依赖关系**：which sub-questions depend on which (models, data,
-   verified claims reused downstream) — the整体感 guarantee: later questions
-   REFERENCE earlier verified results instead of re-deriving them.
-6. **待澄清问题**：open questions inviting the user to add background,
-   correct a reading, or supply their own references — never a yes/no list.
-
-After the user answers, problem-brief.md is updated and the delta is shown.
-
-## D-R literature research (pre-modeling, mandatory)
-
-1. The LLM searches by direction × method for principles and methods only —
-   engineering background, methodology papers, textbooks, official docs.
-   **Never** search for solutions/answers to the specific contest problem.
-2. Findings are written to research/sources.jsonl (author/title/year/venue/
-   URL/retrieval date/excerpt with section or theorem/table location/mapped
-   direction). Every candidate in the method matrix gets a literature column
-   referencing these source ids; a direction with no literature must be
-   explicitly marked "原创方向" with its derivation basis.
-3. The user is asked: endorse / reject / add their own references. User-added
-   references join sources.jsonl with the same fields.
-4. The D-R interaction record goes into ledger.scope.interactions; the gate
-   refuses CANDIDATES_READY without it.
-
-## Honest boundary of the gate
-
-The gate is a MECHANISM guarantee, not an anti-fraud guarantee: it proves a
-record exists, never that the record is true — every interaction record is
-written by the agent itself. Falsified records are therefore out of the
-gate's reach; the defense against them is the blind verifier subagent
-(subagent-dispatch.md), which re-derives key claims from data alone, and the
-artifact checks (research/sources.jsonl, attempts/N/report.md) that tie each
-record to real files on disk.
-
-## Rules
-
-- D0/D1/D-R: 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 D0+D1, CANDIDATES_READY without D-R,
-  ATTEMPT-from-CANDIDATES_READY without D3, terminals-from-VERIFY without D4,
-  and REVISE/RESEARCH (from VERIFY) whose reason fails to reference a
-  `decisionStack` entry id. The CLI `transition` command enforces the same
-  gate and has NO escape hatch. Every D4 record carries the attempt number it
-  adjudicates (`attempt: N`); the terminal gate requires the D4 for the
-  CURRENT attempt. ATTEMPT from CANDIDATES_READY requires `--subproblem <id>`.
-  Terminal gates additionally require `scope.cleanupPassed: true` and the
-  current attempt's report.md on disk. Mechanism-level tests and unattended
-  batch runs may declare `scope.contractExempt: true` — production modeling
-  must never set it.
-
-## Phase pace — interactive beats between phases (v2.8)
-
-The exposition is delivered PHASE BY PHASE, never as a firehose. The phase
-sequence is: restatement → analysis → assumptions → modeling → solving →
-verification → robustness → evaluation. Between every two phases there MUST
-be a user interaction point: the completed phase is presented, one line asks
-whether to proceed to the next phase, and the user may interrupt, ask for a
-deeper explanation of any step of the just-finished phase, or contribute
-knowledge. Sensitivity/robustness NEVER follows solving automatically — it
-only starts after the verification phase, the user's go-ahead, and its own
-D-interaction. Within a phase with ≥3 major steps, offer the user one
-interruption opportunity after the first step.
-
-## 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 (from VERIFY) 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).
-
-## Live documents (every phase can be refined later)
-
-Every phase artifact is LIVE: problem-brief.md (restatement), analysisLog,
-assumptions, sources.jsonl, methods.md, attempt reports. While solving,
-anything discovered that shows an earlier phase was incomplete is patched
-INCREMENTALLY — revision record + downstream stale marking — without
-re-running completed unaffected work. This is the "解题中不断完善" rule.
-
-## 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.
+# Interaction Protocol (v2)
+
+Three interaction layers. Execution details stay autonomous; every
+model-shaping decision is visible and user-owned.
+
+## Deep-exchange protocol (v2.6)
+
+Every L1 decision point follows a three-beat exchange, never a one-way
+"here is my conclusion, confirm it":
+
+1. **LLM presents a complete analysis with its evidence chain.** Every claim
+   inside the analysis carries its basis: an exact quote from the problem
+   text, a data statistic, a literature source id, or an explicit
+   "LLM judgment" marker. A naked conclusion is not a presentation.
+2. **The user responds with substance**: confirmation, correction, background
+   knowledge, their own references, or their own judgment. A pure "ok" is
+   accepted, but the protocol must have OFFERED the space for substance —
+   the questions must be open, not yes/no gates.
+3. **The LLM updates the artifact and shows the delta.** The restatement,
+   analysis log, assumption list, or candidate matrix is edited and the chat
+   shows exactly which points changed because of the user's input.
+
+High-impact points (D0, D-R, D2) may loop beats 2-3 as many times as needed
+until the user says "可以了". Mathematical modeling is a deep activity;
+"skim and start solving" is a protocol violation.
+
+## L1 decision points (MUST ask via the question tool)
+
+| Point | Trigger | Question | Default |
+|---|---|---|---|
+| D0 问题重述 | intake complete | the six-section deep restatement below + open clarification questions | accept + no additions |
+| D1 路由 | TRIAGE | task type (prediction/optimization/explanation/proof/…) + assurance mode (Fast/Standard/High-Assurance) | auto-routing result |
+| D-R 文献研究 | CLAIMS_REGISTERED (before CANDIDATES_READY) | the literature list by direction (AI-found); user endorses / rejects / adds their own | accept list |
+| D2-G 全局假设确认 | CLAIMS_REGISTERED (全景层) | the GLOBAL assumptions that hold for the whole problem (geometry, data, physical mechanism, numerical basis) — each with basis chain + risk | accept all |
+| D2 子问题假设确认 | **each subproblem starts** | the assumptions for THIS subproblem only (S-class), each with statement + basis chain + risk | accept all |
+| D2' 新假设插问 | mid-subproblem discovery that changes model structure | the new assumption + its effect | record-and-continue |
+| D3 方向选择 | CANDIDATES_READY | candidate matrix with a literature column per direction; user picks or authorizes auto | baseline |
+| D4 结果裁决 | VERIFY done | verdict + evidence digest + key intermediate results (residual/constraint-violation distributions, figure paths) + failure details | verdict-implied |
+
+## D0 deep restatement — six sections (MANDATORY structure)
+
+1. **题目要点摘录**：the problem's own numbers and constraints, quoted.
+2. **背景解读**：the engineering/physical mechanism behind the problem.
+3. **数据语义**：every attachment, column by column — meaning, units,
+   coordinate system, magnitudes; unreadable artifacts are flagged with the
+   minimum representation needed.
+4. **隐含信息与歧义清单**：numbered; each entry = the LLM's reading + its
+   basis + the risk if the reading is wrong. This is the heart of the
+   exchange: the user corrects entries here.
+5. **各子问题数学本质判定**：every sub-question of the problem — however
+   many there are (one or ten) — is classified (fitting/optimization/
+   geometric optics/simulation/…), with why.
+5.5 **问间依赖关系**：which sub-questions depend on which (models, data,
+   verified claims reused downstream) — the整体感 guarantee: later questions
+   REFERENCE earlier verified results instead of re-deriving them.
+6. **待澄清问题**：open questions inviting the user to add background,
+   correct a reading, or supply their own references — never a yes/no list.
+
+After the user answers, problem-brief.md is updated and the delta is shown.
+
+## D-R literature research (pre-modeling, mandatory)
+
+1. The LLM searches by direction × method for principles and methods only —
+   engineering background, methodology papers, textbooks, official docs.
+   **Never** search for solutions/answers to the specific contest problem.
+2. Findings are written to research/sources.jsonl (author/title/year/venue/
+   URL/retrieval date/excerpt with section or theorem/table location/mapped
+   direction). Every candidate in the method matrix gets a literature column
+   referencing these source ids; a direction with no literature must be
+   explicitly marked "原创方向" with its derivation basis.
+3. The user is asked: endorse / reject / add their own references. User-added
+   references join sources.jsonl with the same fields.
+4. The D-R interaction record goes into ledger.scope.interactions; the gate
+   refuses CANDIDATES_READY without it.
+
+## Honest boundary of the gate
+
+The gate is a MECHANISM guarantee, not an anti-fraud guarantee: it proves a
+record exists, never that the record is true — every interaction record is
+written by the agent itself. Falsified records are therefore out of the
+gate's reach; the defense against them is the blind verifier subagent
+(subagent-dispatch.md), which re-derives key claims from data alone, and the
+artifact checks (research/sources.jsonl, attempts/N/report.md) that tie each
+record to real files on disk.
+
+## Rules
+
+- D0/D1/D-R: 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 D0+D1, CANDIDATES_READY without D-R,
+  ATTEMPT-from-CANDIDATES_READY without D3, terminals-from-VERIFY without D4,
+  and REVISE/RESEARCH (from VERIFY) whose reason fails to reference a
+  `decisionStack` entry id. The CLI `transition` command enforces the same
+  gate and has NO escape hatch. Every D4 record carries the attempt number it
+  adjudicates (`attempt: N`); the terminal gate requires the D4 for the
+  CURRENT attempt. ATTEMPT from CANDIDATES_READY requires `--subproblem <id>`.
+  Terminal gates additionally require `scope.cleanupPassed: true` and the
+  current attempt's report.md on disk. Mechanism-level tests and unattended
+  batch runs may declare `scope.contractExempt: true` — production modeling
+  must never set it.
+
+In v0.5, report/evaluation/terminal transitions also read answer-coverage.json when the v3 ledger has registered requirements. Missing or stale mappings are hard blockers; partial mappings and explicit waivers are conditional-only. EVALUATE and CORRECTION_REQUIRED are non-final lifecycle states. An evaluation finding creates a correction lineage and never rewrites the parent run or silently upgrades a claim.
+
+## Phase pace — interactive beats between phases (v2.8)
+
+The exposition is delivered PHASE BY PHASE, never as a firehose. The phase
+sequence is: restatement → analysis → assumptions → modeling → solving →
+verification → robustness → evaluation. Between every two phases there MUST
+be a user interaction point: the completed phase is presented, one line asks
+whether to proceed to the next phase, and the user may interrupt, ask for a
+deeper explanation of any step of the just-finished phase, or contribute
+knowledge. Sensitivity/robustness NEVER follows solving automatically — it
+only starts after the verification phase, the user's go-ahead, and its own
+D-interaction. Within a phase with ≥3 major steps, offer the user one
+interruption opportunity after the first step.
+
+## 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 (from VERIFY) 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).
+
+## Live documents (every phase can be refined later)
+
+Every phase artifact is LIVE: problem-brief.md (restatement), analysisLog,
+assumptions, sources.jsonl, methods.md, attempt reports. While solving,
+anything discovered that shows an earlier phase was incomplete is patched
+INCREMENTALLY — revision record + downstream stale marking — without
+re-running completed unaffected work. This is the "解题中不断完善" rule.
+
+## 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/original-project-parity.md

@@ -0,0 +1,19 @@
+# Original GitHub workflow parity
+
+The DSH bundle is a faithful workflow migration of the original
+MathModelingAgent project, not a replacement of its useful behavior.
+
+| Original GitHub behavior | DSH realization |
+|---|---|
+| PDF/problem extraction in `code/agent.py` | intake D0 and the subproblem DAG |
+| Excel attachment profiling in `code/data_analyzer.py` | INPUT_PROFILED and the run input manifest |
+| sequential subproblem solving | dependency-ordered SPi loop |
+| Modeler → Analyzer → Correction loop in `code/prompts.py` | explorer/modeler → verifier/analyzer → corrector/revise |
+| per-round thinking and run logs | attempts/<n>/report.md, events.jsonl, and chat runlog digest |
+| acceptance/rejection and stagnation control | D4 verdict, progress test, REVISE/FORK, and resumable non-SOLVED states |
+| hash-based cache and resume | run-local artifacts, evidence links, and state recovery |
+
+The migration deliberately replaces private chain-of-thought storage with
+human-readable reasoning, evidence, and reproducible artifacts. The roles and
+loop semantics remain; only the execution substrate changes from the legacy
+Python CLI to DSH skills and state files.