dsh-math-modeling-agent 0.1.1 → 0.2.0

package/docs/superpowers/specs/2026-08-22-math-modeling-dsh-plugin-design.md

@@ -1,889 +0,0 @@
-# MathModelingAgent DSH Plugin Design
-
-- **Date:** 2026-08-22
-- **Status:** Approved conversation design, pending written-spec review
-- **Workspace:** `D:\code repository\math\MathModelingAgent-dsh-plugin`
-- **Branch:** `rewrite/dsh-plugin`
-
-## 1. Purpose
-
-Rebuild MathModelingAgent as a clean, installable DeepSeek Harness bundle for evidence-driven mathematical modeling, computation, research, verification, and resumable problem-solving.
-
-The released product must let another person install one DSH bundle and immediately describe a problem in natural language. Python is the default computational verifier when available. Lean and Wolfram are optional verification adapters. Missing external tools reduce evidence strength but must not prevent the plugin from loading or from producing an honest partial result.
-
-The old Python CLI is not a runtime dependency. Only its durable ideas are retained:
-
-- extract and decompose multi-part problems;
-- inspect attachments before modeling;
-- carry verified upstream results into dependent subproblems;
-- iterate Model → Execute → Verify → Critique → Revise;
-- emit a visible report for every attempt;
-- retain failures and resume from checkpoints.
-
-## 2. Product principles
-
-1. **Evidence before status.** No claim is accepted because a model says “Excellent” or a tool exits successfully.
-2. **One natural-language entry.** Users do not select internal phases, tools, or adapters.
-3. **Deep modules.** A small public interface hides grilling, research, tool discovery, state, recovery, and escalation.
-4. **Progressive rigor.** Fast, Standard, and High-Assurance paths prevent simple problems from being over-processed.
-5. **Resumable iteration.** Attempts continue while they produce auditable information gain; exhaustion produces a resumable scientific status, never an empty failure.
-6. **Minimal implementation.** No directory, file, dependency, script, or Skill exists without one durable responsibility.
-7. **Portable distribution.** No developer-specific path, private Skill, persona, API provider, or operating-system assumption enters the package.
-8. **Local-first computation.** User data stays local to the current workspace unless the user explicitly requests an external operation.
-9. **Model agnostic product.** GPT-5.6 Luna Max is the requested implementation/review worker, but the released bundle does not lock users to any model.
-
-## 3. Scope
-
-### 3.1 Included
-
-- mathematical modeling intake and structured grilling;
-- document, attachment, and data profiling;
-- problem typing and subproblem dependency mapping;
-- assumptions, claims, verification obligations, and evidence tracking;
-- candidate model generation and comparison;
-- Python-based computation and testing in an isolated task environment;
-- optional Lean and Wolfram verification;
-- literature and method research;
-- multi-direction breakthrough escalation;
-- per-attempt reports, failure ledger, checkpoints, and recovery;
-- independent auditing of an existing solution or run;
-- MCM/ICM Final Judging Panel scoring with evidence-linked caps and fixed output;
-- bilingual natural-language triggering and a concise bilingual README.
-
-### 3.2 Explicitly excluded
-
-- the legacy Gemini client and prompt loop;
-- a standalone Python agent runtime;
-- mandatory Python, Lean, Wolfram, LaTeX, or commercial solver installation;
-- automatic installation of Lean or Wolfram;
-- install-time scripts or arbitrary code execution;
-- Claude-style `.dsh-plugin/plugin.json`, `commands/`, `agents/`, `hooks/`, or `.mcp.json` conventions;
-- hidden chain-of-thought logging;
-- guarantees that every open mathematical or real-world problem can be solved;
-- model-scored acceptance or innovation-for-innovation’s-sake.
-
-## 4. Official DSH packaging
-
-The package is a DSH **bundle**, not a Claude-style directory plugin.
-
-### 4.1 Root manifest
-
-`package.json` declares the bundle patch:
-
-```json
-{
-  "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"],
-  "license": "MIT",
-  "repository": "https://github.com/yohanchen1/MathModelingAgent",
-  "keywords": ["dsh", "mathematical-modeling", "verification", "lean", "wolfram", "python"],
-  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
-}
-```
-
-There is no build step, `prepare` script, custom Cordis runtime, or npm runtime dependency.
-
-### 4.2 Bundle patch
-
-`cordis.patch.yml` mounts the official filesystem Skill provider over the package-relative immutable Skill root:
-
-```yaml
-- 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/', process.getBuiltinModule('node:url').pathToFileURL(process.getBuiltinModule('node:module').createRequire(baseUrl + 'noop.js').resolve('dsh-math-modeling-agent/package.json')).href))"
-        watch: false
-```
-
-Using `bundledSkillDir` gives packaged Skills bundled precedence, allowing project and user Skills to override them deliberately. The Loader evaluates `!!js` against the root include context, where `baseUrl` is the **profile** directory (not the bundle directory), so the package is resolved through the profile's own `node_modules` via `createRequire` — this removes every absolute-path assumption and works for npm, github, pnpm, and `file:` installs alike.
-
-### 4.3 Installation
-
-GitHub release target:
-
-```bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.1.1
-```
-
-Stable npm release target:
-
-```bash
-dsh plugin --profile web add dsh-math-modeling-agent
-```
-
-Verification and startup:
-
-```bash
-dsh --profile web --dump-config
-dsh web
-```
-
-A running DSH host must be restarted after bundle composition changes. Edits beneath an already mounted watched Skill root are a separate mechanism and do not make bundle installation hot-loadable.
-
-## 5. Public Module shape
-
-Only two user/model-visible Skills are shipped.
-
-### 5.1 `math-modeling-agent`
-
-**Durable job:** solve or resume a mathematical modeling problem from intake through evidence-backed conclusion.
-
-**Trigger examples:**
-
-- “帮我建立并验证这个数学模型。”
-- “解决这道数学建模题，并保存每轮尝试。”
-- “Continue this modeling run from its checkpoint.”
-- “Research alternative methods because this model is stuck.”
-
-**Input interface:** problem text or attachments; optional target, constraints, assurance preference, budget, or existing run directory.
-
-**Output interface:** current status, supported claims, unresolved obligations, concise attempt summary, artifact path, and next action or final report.
-
-**Hidden implementation stages:** triage, math-grill, profiling, decomposition, candidate generation, execution, internal verification, research, breakthrough escalation, reporting, and recovery.
-
-### 5.2 `math-modeling-audit`
-
-**Durable job:** independently audit an existing solution, derivation, code artifact, model, MathModelingAgent run, or MCM/ICM competition paper.
-
-**Trigger examples:**
-
-- “独立核验这份数学建模报告。”
-- “Find counterexamples to these claims.”
-- “检查这个最优性结论和数据划分。”
-- “按 MCM/ICM 终审 100 分框架给这篇论文打分。”
-
-**Input interface:** artifact, run, or paper path; optional problem statement, competition year/problem code, focus claims, and assurance level.
-
-**Output interface:** per-claim `PASS / FAIL / INCONCLUSIVE`, evidence level, counterexamples, reproduction commands, residual risk, and—when MCM/ICM judging intent is detected—the fixed final-panel score report defined in Section 25.
-
-**Trust seam:** it does not silently repair the audited result. High-Assurance runs invoke it in a fresh subagent/context using artifacts rather than the solver’s narrative.
-
-**Specialized judging mode:** MCM/ICM scoring remains an internal mode of this Skill, not a third public Skill. Its large rubric is loaded only for competition-paper judging, so generic mathematical audits keep a small interface and prompt footprint.
-
-### 5.3 Why no other public Skills
-
-Math-grill, research, and breakthrough are internal policies, not external seams. Publishing them separately would leak stage selection to callers, duplicate state/report contracts, conflict with generic research/grilling Skills, and reduce locality.
-
-## 6. Execution modes
-
-### 6.1 Fast
-
-For explicit, low-risk arithmetic, algebra, unit conversion, or directly checkable symbolic tasks.
-
-- zero to two clarification questions;
-- one primary solution;
-- substitution, inverse operation, domain, or dimensional check;
-- no research campaign unless verification fails.
-
-Default safety budget: two attempts, one minute of external computation, no literature queries unless needed to resolve a factual premise.
-
-### 6.2 Standard
-
-For ordinary modeling, prediction, classification, optimization, estimation, simulation, and decision problems.
-
-- dynamic math-grill;
-- input manifest and data profiling;
-- baseline plus materially different candidates;
-- isolated Python execution when available;
-- concise claim/evidence ledger;
-- sensitivity, baseline, leakage, and reproducibility checks appropriate to the type.
-
-Default safety budget: twelve evidence-bearing attempts, twelve research queries, and thirty minutes of external computation. Budget exhaustion preserves state and yields `INCONCLUSIVE` or `BLOCKED`; the run can resume with a larger budget.
-
-### 6.3 High-Assurance
-
-For publication, causal claims, global optimality, formal proof, safety, guarantees, or high-stakes decisions.
-
-- complete claim and evidence ledgers;
-- independent audit in a fresh context;
-- adversarial cases and negative controls;
-- citation verification and data leakage audit;
-- formal or symbolic verification when applicable;
-- reproducibility manifest.
-
-Default safety budget: twenty-four evidence-bearing attempts, thirty research queries, and two hours of external computation. The same resumable budget rule applies.
-
-The mode is inferred from claim strength and use context. The user can override it.
-
-## 7. State machine
-
-```text
-TRIAGE
-  → SCOPE_FROZEN
-  → INPUT_PROFILED
-  → CLAIMS_REGISTERED
-  → CANDIDATES_READY
-  → ATTEMPT
-  → EXECUTE
-  → VERIFY
-      ├─ REVISE → ATTEMPT
-      ├─ RESEARCH → CANDIDATES_READY
-      ├─ FORK → ATTEMPT
-      ├─ independent audit → SOLVED
-      └─ terminal scientific status
-```
-
-Hard invariants:
-
-1. `ATTEMPT` cannot transition directly to `SOLVED`.
-2. Every transition cites one or more evidence or issue IDs.
-3. Failed execution cannot verify an execution-dependent claim.
-4. A changed problem, input hash, objective, assumption, constraint, or required precision invalidates affected downstream claims.
-5. Upstream artifact changes mark dependent subproblems stale.
-6. Parser, provider, or verifier failure retains the last valid candidate and raw output.
-7. Structural validation never evaluates mathematical truth.
-
-## 8. Final scientific statuses
-
-- `SOLVED`: all required obligations pass, critical adversarial checks pass, and the deliverable meets the frozen scope.
-- `PARTIAL`: a useful verified subset exists, but one or more requested conclusions remain unresolved.
-- `CONDITIONAL`: conclusions are valid only under explicitly listed unresolved assumptions.
-- `INCONCLUSIVE`: current evidence cannot distinguish plausible outcomes or budgets ended before resolution.
-- `REFUTED`: a requested proposition or candidate has a valid counterexample or contradiction.
-- `INFEASIBLE`: the constraint system is inconsistent under the frozen scope.
-- `UNIDENTIFIABLE`: available observations cannot identify the requested parameter or structure.
-- `BLOCKED`: progress requires a specific missing input, permission, tool, domain judgment, theory, or resource.
-- `CANCELLED`: the user intentionally stops the run.
-
-`BLOCKED` is not an empty error. It includes the best candidate, verified subset, blocker evidence, minimum unblock input, wall memo, and resume command.
-
-## 9. Math-grill protocol
-
-The grill first types the problem, then asks only questions that can alter the model or verification obligations.
-
-Problem types include symbolic calculation, theorem/proposition, deterministic numerical computation, feasibility, optimization, statistical estimation, prediction, causal inference, stochastic/risk model, inverse problem, mechanism/system model, decision analysis, exploratory analysis, and literature evidence synthesis.
-
-The minimum routing questions are:
-
-1. What output is required: number, proof, model, prediction, optimum, or decision?
-2. Does data exist, and what is its source?
-3. Is the user claiming proof, global optimality, causality, safety, or only a useful approximation?
-4. What error, confidence, or risk is acceptable?
-5. Is the result for practice, competition, publication, production, or a high-stakes decision?
-
-After routing, the grill selectively establishes:
-
-- background and practical objective;
-- subproblems and dependencies;
-- data, labels, units, and quality;
-- variables, parameters, target, and constraints;
-- assumptions and their sources;
-- evaluation and acceptance criteria;
-- requested output format.
-
-Rules:
-
-- ask one question at a time;
-- infer facts from readable inputs before asking;
-- mark irrelevant fields “not applicable” with a reason;
-- record “自行判断” choices as explicit modeling assumptions;
-- ask highest-impact uncertainty first;
-- freeze scope before candidate evaluation.
-
-## 10. Input manifest and subproblem graph
-
-Before modeling, every accessible input receives:
-
-- stable artifact ID and cryptographic hash;
-- path, type, size, encoding, and source;
-- successful/failed readability status;
-- PDF page or image provenance when extracted;
-- table sheets, dimensions, columns, inferred types, units, missingness, duplicates, ranges, and anomalies;
-- possible target leakage, group structure, time structure, and label provenance.
-
-Supported planning targets include text/Markdown, PDF, images, CSV, Excel, JSON, and Parquet. Support is capability-based: missing readers are reported rather than silently ignored.
-
-Multi-part tasks produce a dependency DAG. A downstream node references exact upstream claim and artifact IDs, not copied prose. If an upstream result changes, downstream outputs become stale and must be revalidated or explicitly remain provisional.
-
-## 11. Claims, assumptions, obligations, and evidence
-
-### 11.1 Claim record
-
-Each material claim stores:
-
-- ID and exact wording;
-- type, scope, and quantifiers;
-- assumptions and risk;
-- required verification obligations;
-- linked evidence and counterchecks;
-- status and limitations.
-
-### 11.2 Assumption record
-
-Each assumption stores:
-
-- statement and scope;
-- source category: problem, data, theory, verified literature, domain instruction, or modeling simplification;
-- risk and sensitivity plan;
-- validation status;
-- downstream claims affected.
-
-### 11.3 Evidence record
-
-Each evidence item stores:
-
-- ID, method, tool, timestamp, and coverage claim IDs;
-- input and output artifact hashes;
-- command, workdir, environment, exit code, stdout/stderr artifact paths;
-- result, tolerance, limitations, and evidence level.
-
-Evidence levels are distinct:
-
-- `DERIVED`;
-- `EXECUTED`;
-- `VERIFIED`;
-- `INDEPENDENTLY_VERIFIED`;
-- `EXTERNALLY_VALIDATED`;
-- `NOT_CHECKED`.
-
-Evidence strength may not be weaker than claim strength. If an obligation cannot be met, the claim is weakened or receives a non-SOLVED status.
-
-## 12. Verification obligations
-
-Representative mappings:
-
-- numeric value → independent recomputation, residual/error bound, domain and boundary checks;
-- feasibility → every constraint, slack/residual, original scale, justified tolerance;
-- global optimum → convexity/KKT/duality, certified bounds, exhaustive or exact algorithm; otherwise “local” or “best found”;
-- uniqueness → proof or explicit non-uniqueness disclaimer;
-- prediction/generalization → untouched test or external validation, leakage-safe split, baseline, uncertainty, calibration, and drift limits;
-- causal effect → estimand, identification assumptions, temporal order, confounding and sensitivity analysis;
-- robustness → parameter, seed, data, specification, and scenario perturbations;
-- theorem → readable proof 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, dependency lock, seeds, tolerances, commands, and clean rerun record.
-
-## 13. Candidate portfolio and progress
-
-A candidate has a stable ID, parent/fork lineage, assumptions, expected information gain, targeted obligations, stop conditions, and status:
-
-- `ACTIVE`;
-- `PATCH`;
-- `FORKED`;
-- `SUPERSEDED`;
-- `ABANDONED`;
-- `VERIFIED`.
-
-A round is progress only if it closes an obligation, adds reproducible evidence, refutes a candidate, tightens a bound or uncertainty interval, removes a blocker, or correctly weakens an unsupported claim.
-
-Rewording, same-parameter reruns, training-only improvement, tool exit success, unverified search titles, or longer prose do not count.
-
-Two consecutive no-progress rounds trigger a stagnation review. A third requires a material fork, user decision, or resumable terminal status. New directions must identify their substantive difference and expected information gain.
-
-The newest candidate is not assumed best. The run retains a Pareto view over verification coverage, critical issues, empirical performance, robustness, complexity, interpretability, cost, and reproducibility.
-
-## 14. Research and breakthrough policy
-
-Research activates when an assumption lacks support, a method’s preconditions fail, validation reveals a gap, a parameter needs a source, or current candidates are exhausted.
-
-Each source records author, title, year, venue, stable identifier/URL, version, retrieval date, exact supporting location, excerpt, mapped claim, source quality, and support strength. Full-text, abstract-only, metadata-only, secondary, conflicting, and citation-needed states remain distinct.
-
-A candidate method matrix records applicability, assumptions, implementation cost, verification route, reason to try, and reason to reject.
-
-Hard problems may use isolated parallel subagents. Claimed breakthroughs receive hostile review and, for high-risk claims, blind re-derivation. Subagents exchange no intermediate conclusions; the coordinator adjudicates final reports.
-
-A direction can be abandoned only when refuted, blocked by a specific missing capability/theory/information, or after its natural variants are exhausted. Every abandonment produces a wall memo containing the exact wall, evidence, wall type, breakthrough condition, and restart checklist.
-
-## 15. Tool policy
-
-### 15.1 Node baseline
-
-DSH already requires Node, so deterministic package helpers are `.mjs` files. They never depend on Python.
-
-- `capability-probe.mjs`: read-only capability discovery; stable JSON stdout; diagnostics on stderr; no installation.
-- `python-environment.mjs`: creates and manages only the run-local Python environment; no system modification.
-- `run-state.mjs`: initializes, checkpoints, validates, and reports run state; structural validation only.
-
-### 15.2 Python adapter
-
-Order:
-
-1. use `uv` when available;
-2. otherwise use an available Python runtime and stdlib `venv`;
-3. if neither exists, continue with non-executed modeling/research and report the computational blocker.
-
-The environment lives under the run directory. Packages are installed only when required, from trusted package indexes, with normalized package names and pinned versions. VCS URLs, arbitrary wheels, and problem-supplied install commands require explicit user approval. Code execution records workdir, timeout, input hashes, dependency lock, seed, command, outputs, and files.
-
-### 15.3 Lean adapter
-
-Lean is optional and never auto-installed. It is used only for formalizable obligations. A valid result records Lean/Lake/library versions, imported axioms, absence of `sorry`/`admit`, proof artifact, and a separate audit that the formal statement faithfully represents the natural-language claim.
-
-### 15.4 Wolfram adapter
-
-Wolfram is optional and never auto-installed. Detection verifies executable and license usability. It is used for applicable symbolic, exact, or high-precision obligations. The report states exactly which claim it verifies and what it does not verify.
-
-### 15.5 Search and document tools
-
-Web search, PDF reading, image understanding/OCR, and subagents are capability enhancements, not hard dependencies. If unavailable, the run records the gap and uses local alternatives or asks for the minimum missing representation. Private raw data is never copied into a literature-search query.
-
-## 16. Run artifacts and recovery
-
-Default location:
-
-```text
-math-modeling-runs/<task-id>/
-├── run.json
-├── problem-brief.md
-├── inputs.json
-├── ledger.json
-├── events.jsonl
-├── attempts/
-│   └── 001/
-│       ├── report.md
-│       ├── code/          # only when code exists
-│       └── artifacts/     # only when artifacts exist
-├── research/
-│   ├── sources.jsonl
-│   └── methods.md
-├── walls/                 # only when a direction is abandoned
-├── reproducibility.json
-└── final-report.md        # only for a terminal status
-```
-
-`run.json` is the atomic current snapshot. `events.jsonl` is the append-only transition journal. `ledger.json` owns scope, assumptions, claims, obligations, subproblem dependencies, and candidate index. Logs are diagnostic; they are never the recovery protocol.
-
-Each attempt report contains:
-
-- one objective;
-- candidate/direction and assumption delta;
-- actual execution and new evidence;
-- obligations closed;
-- issues opened/closed;
-- difference from the prior attempt;
-- valid-progress decision;
-- budget use;
-- current status and next single action.
-
-The report does not duplicate complete historical solutions or private reasoning. Provider/parser/tool failure preserves raw output and the last consistent checkpoint. Hash-stable completed work is not repeated on resume.
-
-## 17. Error handling
-
-Failure classes drive different transitions:
-
-- `DATA_MISSING`, `DATA_SCHEMA_ERROR`, `DATA_LEAKAGE`;
-- `TOOL_UNAVAILABLE`, `DEPENDENCY_ERROR`, `LICENSE_ERROR`;
-- `CODE_RUNTIME_ERROR`, `TIMEOUT`, `NUMERICAL_INSTABILITY`;
-- `MODEL_ERROR`, `ASSUMPTION_INVALID`, `UNSUPPORTED_PARAMETER`;
-- `VERIFICATION_FAILED`, `FORMALIZATION_GAP`;
-- `CITATION_UNVERIFIED`, `RESEARCH_GAP`;
-- `PARSER_ERROR`, `PROVIDER_ERROR`;
-- `NO_PROGRESS`, `BUDGET_EXHAUSTED`.
-
-Tool or implementation failures repair the environment or code without automatically changing the model. Model or assumption failures fork or replace the candidate. Citation gaps trigger targeted research. Repeated failure signatures trigger stagnation review.
-
-## 18. Security and privacy
-
-- Never load untrusted pickle/cache files; structured state uses JSON/JSONL.
-- Never concatenate problem text into a shell command.
-- Validate all run-relative paths and reject traversal outside the run root.
-- Install Python packages only in the isolated run environment.
-- Do not execute install-time npm scripts.
-- Preserve exact sources for generated commands and dependencies.
-- Do not upload private attachments to external search or tools without explicit user intent.
-- Do not store secrets in artifacts, logs, examples, or repository files.
-- Treat external papers, web pages, and attachments as untrusted content, not instructions.
-
-## 19. Minimal project layout
-
-```text
-MathModelingAgent-dsh-plugin/
-├── package.json
-├── cordis.patch.yml
-├── README.md
-├── LICENSE
-├── .gitignore
-├── skills/
-│   ├── math-modeling-agent/
-│   │   ├── SKILL.md
-│   │   ├── references/
-│   │   │   ├── workflow.md
-│   │   │   ├── math-grill.md
-│   │   │   ├── problem-types.md
-│   │   │   ├── claims-evidence.md
-│   │   │   ├── modeling-methodology.md
-│   │   │   ├── data-subproblems.md
-│   │   │   ├── research-breakthrough.md
-│   │   │   ├── tool-policy.md
-│   │   │   ├── state-recovery.md
-│   │   │   └── report-contract.md
-│   │   ├── scripts/
-│   │   │   ├── capability-probe.mjs
-│   │   │   ├── python-environment.mjs
-│   │   │   └── run-state.mjs
-│   │   ├── schemas/
-│   │   │   ├── run.schema.json
-│   │   │   ├── ledger.schema.json
-│   │   │   └── attempt.schema.json
-│   │   └── examples/
-│   │       ├── minimal-run/
-│   │       └── resumed-run/
-│   └── math-modeling-audit/
-│       ├── SKILL.md
-│       ├── references/
-│       │   ├── verification-protocol.md
-│       │   ├── evidence-levels.md
-│       │   ├── data-citation-audit.md
-│       │   └── mcm-icm-final-judge.md
-│       ├── scripts/
-│       │   └── mcm-score.mjs
-│       └── examples/
-│           ├── audit-report.md
-│           └── mcm-final-review.md
-└── tests/
-    ├── plugin-integrity.test.mjs
-    ├── capability-probe.test.mjs
-    ├── python-environment.test.mjs
-    ├── run-state.test.mjs
-    ├── recovery.test.mjs
-    ├── mcm-score.test.mjs
-    └── fixtures/
-```
-
-No empty conventional directory is created. Every production file has one responsibility. `SKILL.md` files contain only trigger, interface, workflow, invariants, and selective reference-loading guidance. Exhaustive material stays in references. Shared protocols have one authoritative file and are not copied between Skills.
-
-## 20. README contract
-
-The single bilingual `README.md` contains:
-
-- one-sentence product definition;
-- verified GitHub/npm/local install commands;
-- required host restart and `--dump-config` verification;
-- three natural-language examples, including one MCM/ICM paper-scoring request;
-- Fast/Standard/High-Assurance explanation;
-- Python recommended, Lean/Wolfram optional;
-- evidence and final-status semantics;
-- artifact and resume behavior;
-- privacy/security rules;
-- known limits and uninstall command;
-- contributor verification commands.
-
-It does not document the legacy CLI, Gemini keys, Conda, old logs, or internal stage selection.
-
-## 21. Verification and release gates
-
-### 21.1 Deterministic tests
-
-Use Node’s built-in `node:test`; add no test framework dependency.
-
-Required coverage:
-
-1. package manifest and patch integrity;
-2. frontmatter parsing and local-reference existence;
-3. exact two-Skill catalog;
-4. state-transition legality and atomic recovery;
-5. malformed/corrupted state rejection;
-6. parser/provider/tool failure retaining the best candidate;
-7. no executable artifact preventing execution-dependent `SOLVED`;
-8. Python missing, Python+venv, and uv paths;
-9. Lean/Wolfram absent degradation;
-10. path traversal and command-injection rejection;
-11. package tarball includes all referenced resources;
-12. append-only events and resume idempotence;
-13. MCM/ICM category subtotals sum to exactly 100;
-14. multiple award caps apply the strictest cap;
-15. a disqualification-risk flag suppresses ordinary award scoring.
-
-### 21.2 DSH smoke tests
-
-With a temporary `DSH_HOME`:
-
-- install local checkout into a temporary profile;
-- inspect `--dump-config`;
-- confirm both Skills appear and load;
-- remove the bundle and confirm the layer disappears.
-
-### 21.3 Cross-platform matrix
-
-Baseline CI runs on Windows, Linux, and macOS without Python, Lean, or Wolfram requirements. Python integration is a separate matrix. Lean and Wolfram tests are optional integration jobs and never gate baseline installation.
-
-### 21.4 Scientific acceptance cases
-
-- a simple equation takes the Fast path and verifies by substitution;
-- a prediction fixture detects preprocessing leakage;
-- a non-convex optimizer cannot claim global optimality without a certificate;
-- a fabricated citation remains unverified;
-- a Lean proof with `sorry` fails audit;
-- a failed verifier cannot discard a previous valid candidate;
-- an upstream subproblem revision marks downstream results stale;
-- three no-progress attempts yield a resumable non-SOLVED status;
-- a solved run traces every required claim to an artifact;
-- an MCM/ICM paper with an unvalidated core model is capped at 84 even when its raw score is higher;
-- an MCM/ICM paper with a disqualification risk stops normal scoring and emits a dedicated risk finding.
-
-### 21.5 Release process
-
-1. keep legacy `main` untouched while developing `rewrite/dsh-plugin`;
-2. tag the legacy commit as `legacy-v3.1` before replacing the public default branch;
-3. verify local install, tarball install, then pinned GitHub install;
-4. publish `v0.1.0` only after clean-machine smoke tests;
-5. publish npm package after GitHub release verification;
-6. change the default branch only with explicit owner approval.
-
-## 22. Migration from the legacy project
-
-The old workspace remains read-only. No legacy Python, requirements, cache, logs, problem data, generated plots, or provider-specific prompt text is copied.
-
-Concepts are rewritten against the new contracts:
-
-- PDF extraction → capability-based input manifest;
-- Excel profiler → format-independent profiling protocol;
-- sequential context concatenation → verified artifact dependency DAG;
-- Modeler/Analyzer loop → claim/evidence state machine with independent audit;
-- score-based stagnation → evidence/issue/progress delta;
-- thinking logs → concise attempt reports and event journal;
-- cache → hash- and version-aware artifact reuse;
-- hard iteration cap → safety budget plus resumable status;
-- `None` failure → best-candidate retention and blocker report.
-
-## 23. Success criteria
-
-The redesign is complete only when:
-
-1. a third party installs it with one documented DSH command;
-2. the package loads without Python, Lean, Wolfram, private Skills, or developer paths;
-3. natural-language requests trigger exactly one appropriate public Skill;
-4. math-grill asks one applicable high-impact question at a time;
-5. every attempt emits a concise human report and machine-valid state;
-6. Python work occurs in an isolated, reproducible run environment;
-7. Lean/Wolfram are optional and their coverage is explicit;
-8. research sources are claim-linked and verifiable;
-9. no status is upgraded from tool success or model confidence alone;
-10. interrupted runs resume without repeating hash-stable completed work;
-11. no redundant production file, dependency, or public interface remains;
-12. MCM/ICM judging follows the supplied 100-point rubric, evidence citation rules, cap logic, and fourteen-section output without inventing missing evidence;
-13. all baseline tests and DSH installation smoke tests pass on a clean environment.
-
-## 24. Primary references
-
-- DeepSeek Harness, “Package and install a plugin”: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md
-- DeepSeek Harness, “Skills”: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/skills.md
-- DeepSeek Harness CLI README: https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.zh.md
-- Local verified DSH version during design: `0.1.1-rc.2`
-
-## 25. MCM/ICM Final Judging Panel mode
-
-### 25.1 Role and boundary
-
-When the user asks to score or final-review an MCM/ICM paper, `math-modeling-audit` loads `references/mcm-icm-final-judge.md` and acts as a hostile Final Judging Panel rather than a writing coach.
-
-The 100-point framework is explicitly a simulated final-panel rubric, not a COMAP official quantitative scorecard. The reviewer must not reward complexity, fashionable algorithms, polished prose, or self-declared robustness without evidence. It distinguishes:
-
-- a plausible-looking model from a validated model;
-- a computed number from a credible modeling result;
-- method description from completion of the requested task;
-- presentation quality from modeling quality;
-- formal verification of a statement from fidelity to the real problem.
-
-This mode never feeds its score back into the solver acceptance loop. A paper score is an external evaluation product, not a mathematical verification certificate.
-
-### 25.2 Required inputs and review coverage
-
-The mode attempts to obtain:
-
-1. the complete paper with stable page numbers;
-2. the original problem statement and every subtask;
-3. competition year and problem code;
-4. that year’s official COMAP page, anonymity, submission, citation, and AI-use/disclosure rules;
-5. appendices, code, and data when available.
-
-Missing material is recorded in a review-coverage statement. The reviewer writes “论文未提供证据” or “当前材料无法核验” and never reconstructs absent arguments, parameters, results, citations, or rules on the authors’ behalf.
-
-Before scoring, the paper is indexed by page, section, equation, table, figure, and key result. Every nontrivial deduction cites the most precise available location. Official annual rules are searched from COMAP or another primary source; if unavailable, compliance remains unverified rather than guessed.
-
-### 25.3 Stage 1: veto and award-cap pressure test
-
-The reviewer classifies each item as `通过 / 警告 / 严重问题 / 一票否决风险`:
-
-1. every explicit subproblem is answered;
-2. no omitted, off-target, or proxy-substituted task;
-3. no critical mathematical formula error;
-4. no dimensional, unit, or order-of-magnitude error;
-5. no key result violating model constraints;
-6. no contradiction among summary, body, tables, or figures;
-7. conclusions follow from model and computed results;
-8. critical parameters have sources or defensible estimation;
-9. critical model and algorithm are reproducible;
-10. no data leakage, future leakage, or train/test mixing;
-11. references and data sources are real and traceable;
-12. external methods, algorithms, and data are cited;
-13. the paper complies with the applicable year’s COMAP rules;
-14. core results receive credibility validation;
-15. model structure matches the real mechanism or discusses the mismatch.
-
-Caps are evidence-linked and cumulative; the strictest applicable cap wins:
-
-- any core subtask missing → Outstanding and Finalist are normally unavailable;
-- conclusion-changing mathematical error in the main model → score cap 69;
-- core prediction, optimization, or decision model completely unvalidated → score cap 84;
-- critical unsupported parameters with high result sensitivity → score cap 79;
-- critical results not reproducible from paper/code/data → score cap 79;
-- clear data leakage or answer-information training → score cap 69;
-- main conclusions conflict with figures or calculations → score cap 74;
-- method-heavy paper with almost no quantitative result → score cap 59;
-- suspected fabricated data/reference, plagiarism, or serious rule violation → stop ordinary scoring and emit `Disqualification Risk`.
-
-Every cap trigger records the page/section/formula/table/figure or states that the paper supplied no traceable evidence.
-
-### 25.4 Stage 2: exact 100-point rubric
-
-The reference preserves the user-supplied checks beneath every subcriterion. The deterministic maxima are:
-
-| Category | Subcriteria | Points |
-|---|---|---:|
-| 1. Problem understanding, decomposition, summary | Summary 4; understanding/decomposition 3; assumptions/definitions/boundaries 3 | 10 |
-| 2. Data, evidence, parameters | source credibility 3; preprocessing 2; representativeness/bias/leakage 2; parameter calibration 3; data-parameter-model consistency 2 | 12 |
-| 3. Model formulation | mechanism mapping 5; valuable innovation 4; variables/objective/constraints/equations 4; internal consistency 3; complexity/explainability 3; multi-subproblem unity 3 | 22 |
-| 4. Mathematical solution, algorithms, reproducibility | derivation 4; algorithms/numerics 4; reproducibility 3; complexity/convergence/optimality 3; sanity checks 2 | 16 |
-| 5. Results, validation, robustness, credibility | task completion 4; numerical correctness/consistency 4; baselines 3; sensitivity 4; robustness/uncertainty 4; independent validation 3; failure/boundary cases 2 | 24 |
-| 6. Conclusions, practical meaning, transfer | model-grounded conclusions 3; actionable recommendations 2; concrete limitations 2; transferability 1 | 8 |
-| 7. Writing, figures, professional presentation | structure 2; figure quality 2; language 1; notation/formulas 1; citations 1; page efficiency 1 | 8 |
-| **Total** | | **100** |
-
-Every subscore includes concrete evidence. A missing evidence trail is itself a scoring finding.
-
-### 25.5 Mandatory paper autopsies
-
-The final review additionally performs all of the following.
-
-#### Model-by-model autopsy
-
-Every major model `M1, M2, ...` is reviewed separately for problem addressed, input, output, equations, parameters, assumptions, selection rationale, mechanism fit, mathematical correctness, interpretability, solver, result, validation, sensitivity, robustness, simpler alternatives, marginal value, score out of ten, and verdict:
-
-- retain;
-- simplify;
-- restructure;
-- untrustworthy.
-
-The reviewer then decides whether the paper forms a unified modeling system or a model collage.
-
-#### Key-result audit
-
-Every conclusion-critical result `R1, R2, ...` enters a table containing value, source location, unit, model, inputs, computation path, reproducibility, order-of-magnitude reasonableness, validation, importance, and `PASS / WARNING / FAIL`.
-
-The review explicitly identifies the most credible result, most fragile result, most manually parameterized result, result most exposed to data failure, and result whose failure would collapse the paper. It checks precision illusion, constraint satisfaction, missed alternatives, ±5%/±10%/±20% input perturbations, and whether reality-facing decisions are justified.
-
-#### Data and parameter audit
-
-Key datasets are mapped as data name → source → time → sample size → unit → consuming model. Key parameters are mapped as parameter → value → source → support → sensitivity → risk. Unsupported or highly sensitive parameters are named as the paper’s Achilles’ heels.
-
-#### Sensitivity, robustness, and validation audit
-
-The reviewer distinguishes what was actually tested from formalistic analysis. It checks whether sensitivity targets the true critical parameters, uses realistic ranges, quantifies output changes and thresholds, detects rank reversal or failure, and covers data, parameter, random, structural, scenario, and worst-case uncertainty.
-
-#### Mathematical and computational spot checks
-
-When the material permits, the reviewer checks at least:
-
-- three core formulas;
-- three core numerical results;
-- one key algorithm;
-- one key figure;
-- one final conclusion.
-
-Python, Wolfram, Lean, or another independent calculation may be used according to the ordinary evidence policy. Inability to recompute is reported, not hidden.
-
-#### Problem-type module
-
-Exactly the applicable specialized checklist is activated:
-
-- MCM A: continuous equations, initial/boundary conditions, dimensions, discretization, grid convergence, stability, parameter estimation, physical meaning;
-- MCM B: graph/combinatorial structure, dynamic/integer programming, correctness, complexity, optimality, scalability;
-- MCM C: data quality, leakage, splits, features, multicollinearity, overfitting, baselines, metrics, calibration, uncertainty, interpretation;
-- ICM D: network construction, node/edge semantics, weights, network metrics, objective/constraints, optimization, scale, perturbation stability;
-- ICM E: system boundary, timescale, lifecycle, environmental-economic-social tradeoffs, weights, scenarios, uncertainty, long-run and unintended consequences;
-- ICM F: correlation/causality, behavior, stakeholders, fairness, cost, incentives, implementation, scenarios, unintended and heterogeneous effects.
-
-### 25.6 Award judgment
-
-Raw-score reference bands are:
-
-- 93–100: Outstanding Candidate;
-- 87–92: Finalist;
-- 78–86: Meritorious;
-- 68–77: Honorable Mention;
-- 55–67: Successful Participant;
-- below 55: Unsuccessful Risk.
-
-The score is advisory, not mechanical. Outstanding additionally requires complete task coverage, no major mathematical/logical error, credible validation of core results, non-formalistic sensitivity/robustness evidence, sourced key parameters, a strong Summary Sheet, non-template modeling, a complete model-result-conclusion chain, reproducibility, and at least one memorable contribution. A high raw score without these gates is capped at Finalist or below.
-
-Award probabilities are explicit reviewer judgments tied to evidence and review coverage; they are not statistical frequencies.
-
-### 25.7 Fixed fourteen-section output
-
-The MCM/ICM mode emits exactly these top-level sections, in order:
-
-1. 一、60 秒终审印象
-2. 二、一票否决与奖项封顶检查
-3. 三、总体评价与最终得分
-4. 四、100 分分项评分
-5. 五、题目要求覆盖矩阵
-6. 六、模型逐个尸检
-7. 七、建模结果专项审计
-8. 八、数据与参数审计
-9. 九、灵敏度、稳健性与验证专项评价
-10. 十、数学与计算正确性抽查
-11. 十一、图表与写作评审
-12. 十二、Outstanding Winner 差距分析
-13. 十三、修改优先级
-14. 十四、评委最终裁决
-
-The detailed fields and wording supplied by the user are preserved in `mcm-icm-final-judge.md`; implementation may normalize Markdown spacing but may not weaken, omit, or replace required questions.
-
-### 25.8 Deterministic score module
-
-`scripts/mcm-score.mjs` performs arithmetic and policy validation only. It never reads the paper, assigns judgment, invents evidence, or decides whether a trigger is true.
-
-Its input is versioned JSON containing:
-
-- every subcriterion score;
-- evidence references for each scored finding;
-- award-cap triggers with cap and evidence;
-- core-task-completion flags;
-- Outstanding gate flags;
-- optional disqualification-risk record.
-
-Its output contains:
-
-- validated category subtotals;
-- raw score out of 100;
-- applied cap list;
-- strictest cap;
-- capped score;
-- raw band and capped band;
-- nonnumeric award ceiling, including the core-task rule that removes Outstanding/Finalist eligibility;
-- Outstanding-gate result;
-- disqualification state;
-- deterministic diagnostics and exit code.
-
-Rules:
-
-- reject missing, duplicate, negative, or over-maximum subscores;
-- reject a rubric whose maxima do not total 100;
-- require evidence text for every cap;
-- apply the minimum numeric cap when multiple caps trigger;
-- suppress ordinary score/award output when disqualification risk is active;
-- keep raw and capped score separate;
-- never adjust scores for encouragement.
-
-### 25.9 Acceptance tests for the judging mode
-
-The mode is acceptable only when:
-
-1. generic audits do not load the large MCM/ICM rubric;
-2. MCM/ICM intent loads the rubric without adding a third public Skill;
-3. all fourteen output sections are present and ordered;
-4. all seven category totals and subcriteria equal 100 exactly;
-5. each scored item and cap has a traceable paper location or an explicit no-evidence statement;
-6. missing annual rules remain unverified;
-7. the strictest cap is deterministic;
-8. disqualification risk stops normal scoring;
-9. at least three formulas, three results, one algorithm, one figure, and one conclusion are checked when available;
-10. the report can state Meritorious or lower without politeness inflation;
-11. technical complexity never substitutes for evidence strength;
-12. the full rubric reference contains no dead local path or unimplemented dependency.