dsh-math-modeling-agent 0.2.6 → 0.2.8

package/README.md

@@ -108,7 +108,7 @@ D3 方向/D4 裁决），`run-state.mjs gate` 在每次状态转移前强制校
 安装：
 
 ```bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.2.6
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.2.8
 dsh --profile web --dump-config   # 检查组合层（应看到 dsh-math-modeling-agent-skills 行）
 dsh web                          # 重启以加载插件
 ```

package/package.json

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

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

@@ -46,7 +46,8 @@ until the user says "可以了". Mathematical modeling is a deep activity;
 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. **三问数学本质判定**：each sub-question classified (fitting/optimization/
+5. **各子问题数学本质判定**：every sub-question of the problem — however
+   many there are (one or ten) — is classified (fitting/optimization/
    geometric optics/simulation/…), with why.
 6. **待澄清问题**：open questions inviting the user to add background,
    correct a reading, or supply their own references — never a yes/no list.
@@ -68,6 +69,16 @@ After the user answers, problem-brief.md is updated and the delta is shown.
 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
@@ -81,7 +92,26 @@ After the user answers, problem-brief.md is updated and the delta is shown.
   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 (escape hatch `--skip-gate true` is for mechanism testing only).
+  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)
 

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

@@ -24,21 +24,67 @@ 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 display — the runlog digest (MUST output, v2)
+## Chat display — the runlog digest (MUST output, v2.7)
 
 The following is shown DIRECTLY IN THE CHAT, not only on disk.
 
+### Readability standard — write for a human reader, never a bullet list
+
+Every section is an EXPOSITION, not a summary: state WHY the step is taken,
+HOW the reasoning runs (derivation, mechanism, first-principles chain), WHAT
+came out (numbers with units), and HOW it is checked. A reader who knows
+nothing about the problem must be able to follow each section without
+guessing.
+
+Style: step-by-step numbered exposition with plain direct language (this is
+a working document, not a final paper — no paper-style formal phrasing
+required), but with MORE detail than a paper would carry: every parameter
+choice gets its reason, every formula is followed by a plain-language
+explanation of each symbol, every step ends with a transition line
+("这一步保证了…，为下一步…做好准备"), and every conclusion states what it
+would take to be wrong. Minimum expectations per section:
+
+- 问题重述：restate the question in your own words, explaining every
+  parameter's meaning and where it comes from in the problem text.
+- 问题分析：walk the physical/geometric mechanism step by step (e.g. why the
+  nodes move radially, how the focal geometry pins the paraboloid), each
+  step justified by problem text, data, or derivation.
+- 模型假设：for EVERY assumption give the reason it is justified
+  (original wording / data statistic / derivation / literature) and what
+  happens if it fails.
+- 模型建立与求解：write the derivation in full (equations, variable
+  definitions, units, how the equation is solved, numerical method and why
+  it was chosen), not just the final formula.
+- 验证：explain the verification LOGIC for each obligation (what would
+  falsify it, what tolerance is used and why), then the outcome.
+- 鲁棒性：for each perturbation say what was varied, why that parameter,
+  and what would count as a conclusion flip.
+- 评价与改进 / 参考文献：state the comparison criterion and map each
+  reference to the exact method it supports.
+
 ### Intake digest (once, at intake completion) — the six-section deep restatement
 
-【题目要点摘录】problem's own numbers and constraints, quoted
-【背景解读】engineering/physical mechanism
-【数据语义】every attachment column by column (meaning/units/coordinate system/magnitudes)
-【隐含信息与歧义清单】numbered; each = LLM reading + basis + risk (the user corrects entries here)
-【三问数学本质判定】fitting/optimization/geometric optics/… + why
+【题目要点摘录】the problem's own numbers and constraints, quoted, each explained
+【背景解读】engineering/physical mechanism, walked through
+【数据语义】every attachment column by column (meaning/units/coordinate system/magnitudes), with observed statistics
+【隐含信息与歧义清单】numbered; each = LLM reading + derivation/basis + risk (the user corrects entries here)
+【各子问题数学本质判定】every sub-question (any count) classified + why
 【待澄清问题】open questions inviting user background/corrections/references
 
 After the D0 exchange, show the delta applied to problem-brief.md.
 
+### Quality self-check (MUST run before every D4 verdict)
+
+Before presenting a D4 verdict, run the self-check on the current attempt's
+report and show the result in the chat: for each of the eight digest sections,
+confirm whether it answers all four questions — WHY (why this step), HOW
+(how the reasoning runs), WHAT (result with units), CHECK (how it is
+verified, or what would falsify it). Any section failing one of the four is
+flagged as incomplete and the round is NOT presented for verdict until fixed.
+The self-check is a human-facing declaration: the user decides whether the
+exposition is actually sufficient. This is the quality gate; the machine
+gates above only guarantee existence and structure.
+
 ### Per-round digest (after EVERY attempt round)
 
 ```text

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

@@ -366,7 +366,7 @@ function validateJournal(events, diagnostics) {
   })
 }
 
-export async function initRun(root, { taskId, mode = 'standard', budget, budgets }, runtime = {}) {
+export async function initRun(root, { taskId, mode = 'standard', budget, budgets, contract }, runtime = {}) {
   assertTaskId(taskId); assertMode(mode)
   const effectiveBudget = { ...MODE_DEFAULTS[mode], ...(budget ?? budgets ?? {}) }
   const budgetDiagnostics = []
@@ -379,7 +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, interactions: [], decisionStack: [], robustnessExempt: false },
+      schemaVersion: SCHEMA_VERSION, taskId,
+      scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false, ...(contract === false ? { contractExempt: true } : {}) },
       assumptions: [], claims: [], obligations: [], subproblems: [], candidates: [], issues: [],
     }
     const event = { schemaVersion: SCHEMA_VERSION, sequence: 0, type: 'RUN_INITIALIZED', taskId, timestamp, snapshot: clone(run) }
@@ -412,9 +413,14 @@ export async function initRun(root, { taskId, mode = 'standard', budget, budgets
 }
 
 /** The v2 interaction contract: decision records, decision-stack backtracking, and the robustness gate. */
-function hasDecisionRecord(scope, decisionPoint) {
+function hasDecisionRecord(scope, decisionPoint, { allowAuto = true } = {}) {
   return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
-    entry && (entry.decisionPoint === decisionPoint || entry.auto === true))
+    entry && (entry.decisionPoint === decisionPoint || (allowAuto && entry.auto === true)))
+}
+/** D4 verdict records carry the attempt number they adjudicate: {decisionPoint:'D4', attempt: 2, ...} */
+function hasD4ForAttempt(scope, attempt) {
+  return Array.isArray(scope?.interactions) && scope.interactions.some(entry =>
+    entry && (entry.auto === true || (entry.decisionPoint === 'D4' && entry.attempt === attempt)))
 }
 function decisionStackIds(scope) {
   return Array.isArray(scope?.decisionStack)
@@ -430,6 +436,7 @@ function hasSubproblemD2(scope, subproblem) {
 function interactionContractViolations(run, ledger, to, reason, subproblem) {
   if (ledger.schemaVersion !== SCHEMA_VERSION) return []
   const scope = ledger.scope ?? {}
+  if (scope.contractExempt === true) return []
   const violations = []
   const transitional = to !== undefined
   const earlyStop = ['BLOCKED', 'CANCELLED'].includes(run.status)
@@ -439,16 +446,17 @@ function interactionContractViolations(run, ledger, to, reason, subproblem) {
   }
   const afterCandidates = ['CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'REVISE', 'FORK', ...FINAL_STATES]
   const candidatesGate = transitional ? (to === 'CANDIDATES_READY') : (afterCandidates.includes(run.status) && !earlyStop)
-  if (candidatesGate && !hasDecisionRecord(scope, 'D-R')) violations.push('D-R literature-research interaction record missing (pre-modeling literature survey is mandatory)')
+  if (candidatesGate && !hasDecisionRecord(scope, 'D-R', { allowAuto: false })) violations.push('D-R literature-research interaction record missing (pre-modeling literature survey is mandatory; auto-authorization is not accepted)')
   const enteringAttemptFromCandidates = transitional ? (to === 'ATTEMPT' && run.status === 'CANDIDATES_READY') : (run.currentAttempt >= 1)
   if (enteringAttemptFromCandidates) {
+    if (transitional && !subproblem) violations.push('ATTEMPT from CANDIDATES_READY requires --subproblem <id>')
     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>)`)
+    if (transitional && subproblem && !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 (enteringTerminalFromVerify && !hasD4ForAttempt(scope, run.currentAttempt)) violations.push(`D4 verdict interaction record for attempt ${run.currentAttempt} missing`)
   if (transitional && (to === 'REVISE' || (to === 'RESEARCH' && run.status === 'VERIFY'))) {
     const ids = decisionStackIds(scope)
     if (ids.length > 0 && !ids.some(id => typeof reason === 'string' && reason.includes(id))) {
@@ -458,9 +466,12 @@ function interactionContractViolations(run, ledger, to, reason, subproblem) {
   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)')
+  if (terminalAndExempt) {
+    if (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)')
+    }
+    if (scope.cleanupPassed !== true) violations.push('terminal state requires scope.cleanupPassed: true (run the cleanup checklist in run-directory.md)')
   }
   return violations
 }
@@ -550,7 +561,7 @@ async function validateRunUnlocked(root, expectedTaskId) {
   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}`)
+      diagnostics.push(`interaction contract: ${violation}`)
     }
     if (run.currentAttempt >= 1) {
       const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
@@ -574,7 +585,7 @@ export async function validateRun(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.
+ * the CLI `transition` command enforces it internally and has NO escape hatch.
  */
 export async function gateTransition(root, { to, reason, subproblem }, runtime = {}) {
   return withLock(root, MUTATION_LOCK_FILE, 'gate', async () => {
@@ -582,6 +593,23 @@ export async function gateTransition(root, { to, reason, subproblem }, runtime =
     const run = await readJson(p.run)
     const ledger = await readJson(p.ledger)
     const violations = interactionContractViolations(run, ledger, to, reason, subproblem)
+    const exempt = ledger.scope?.contractExempt === true
+    if (to === 'CANDIDATES_READY' && !exempt) {
+      const sourcesPath = join(root, 'research', 'sources.jsonl')
+      try {
+        if (!(await readFile(sourcesPath, 'utf8')).trim()) violations.push('research/sources.jsonl is empty (pre-modeling literature survey artifacts are mandatory)')
+      } catch {
+        violations.push('research/sources.jsonl missing (pre-modeling literature survey artifacts are mandatory)')
+      }
+    }
+    if (FINAL_STATES.includes(to) && !['BLOCKED', 'CANCELLED'].includes(to) && !exempt) {
+      const reportPath = join(root, 'attempts', String(run.currentAttempt), 'report.md')
+      try {
+        await readFile(reportPath, 'utf8')
+      } catch {
+        violations.push(`attempts/${run.currentAttempt}/report.md missing (write the runlog report before a terminal transition)`)
+      }
+    }
     return { allowed: violations.length === 0, violations, status: run.status }
   }, runtime)
 }
@@ -632,12 +660,10 @@ async function cli(argv) {
     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 }
-      }
+    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 })
   }