dsh-math-modeling-agent 0.2.5 → 0.2.7

package/README.md

@@ -108,7 +108,7 @@ D3 方向/D4 裁决），`run-state.mjs gate` 在每次状态转移前强制校
 安装：
 
 ```bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.2.5
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.2.7
 dsh --profile web --dump-config   # 检查组合层（应看到 dsh-math-modeling-agent-skills 行）
 dsh web                          # 重启以加载插件
 ```
@@ -118,10 +118,11 @@ dsh web                          # 重启以加载插件
 不要用 `npm install` 代替，那会装到错误位置。如本机镜像源同步滞后，可显式走官方源：
 `dsh plugin --profile web add dsh-math-modeling-agent --registry=https://registry.npmjs.org/`）
 
-开始建模——直接描述任务即可。每个会改变模型结构的决策都会在对话中交互确认
-（任务路由、各子问题假设、候选方向、每轮裁决），每轮在对话直接输出 runlog 式摘要
-（问题重述/分析/假设/建模求解/验证/鲁棒性/评价改进/参考文献），失败尝试按类归档到独立目录，
-终态前强制鲁棒性敏感度分析：
+开始建模——直接描述任务即可。每个环节都是人与 LLM 的深度信息交换：LLM 给出带依据链的
+完整分析（题面原句/数据证据/文献/显式判断标记），你纠正、补充背景或提供自己的参考文献，
+LLM 更新并展示差异。建模前必须先做文献调研（AI 检索原理与方法文献，你可增删），每个候选
+方向都有文献出处；每轮在对话直接输出 runlog 式摘要（问题重述/分析/假设/建模求解/验证/鲁棒性/
+评价改进/参考文献），失败尝试按类归档，终态前强制鲁棒性敏感度分析：
 
 ```text
 建立这个数学建模问题的模型，先分析题目和数据。

package/package.json

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

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

@@ -15,7 +15,7 @@ Move one mathematical problem from scoped intake to an evidence-backed conclusio
 
 Accept problem text, attachments, or an existing run directory.
 
-Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is interactive — D0 restatement / D1 routing once per task, D2 assumptions and D3 direction per subproblem, D2' on mid-subproblem discoveries, D4 verdict per round. Show the runlog digest in the chat after every round (references/report-contract.md); announce one status line before every transition; the user may interrupt at any time.
+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.
 
@@ -26,13 +26,14 @@ Return a concise current status, supported claims, unresolved obligations, attem
 3. Create or validate run state with `scripts/run-state.mjs` and follow `references/state-recovery.md`. Gate EVERY transition: `run-state.mjs gate <dir> --to <status> --reason "..."`.
 4. Profile inputs and build the subproblem DAG using `references/data-subproblems.md`.
 5. Register assumptions (per subproblem), claims, and verification obligations from `references/claims-evidence.md`; ask D2 for the subproblem being started.
-6. Build a baseline and materially different candidates using `references/modeling-methodology.md`; ask D3 (candidate matrix).
-7. Probe tools with `scripts/capability-probe.mjs`; create a run-local Python environment with `scripts/python-environment.mjs` only when computation is required. Announce the tool choice and fallback for the phase (references/tool-policy.md).
-8. Execute, verify, critique, and revise according to `references/workflow.md` and `references/tool-policy.md`; ask D4 after each VERIFY.
-9. Dispatch subagents for parallel exploration, blind verification, and audits per `references/subagent-dispatch.md`.
-10. Escalate evidence gaps or stalled directions through `references/research-breakthrough.md`; write wall memos and the failure ledger per `references/run-directory.md`.
-11. Write only incremental attempt and terminal reports defined by `references/report-contract.md`; output the per-round runlog digest in the chat.
-12. Before any terminal transition, run the cleanup gate (references/run-directory.md) and the robustness gate (a PASSED robustness-kind obligation, or scope.robustnessExempt with reason).
+6. **Literature research (mandatory, before candidates)**: transition CLAIMS_REGISTERED → RESEARCH, search principles and methods by direction (never contest solutions), write `research/sources.jsonl`, attach a literature column to the candidate matrix, then ask D-R (user endorses/rejects/adds references) and move to CANDIDATES_READY.
+7. Build a baseline and materially different candidates using `references/modeling-methodology.md`; ask D3 (candidate matrix).
+8. Probe tools with `scripts/capability-probe.mjs`; create a run-local Python environment with `scripts/python-environment.mjs` only when computation is required. Announce the tool choice and fallback for the phase (references/tool-policy.md).
+9. Execute, verify, critique, and revise according to `references/workflow.md` and `references/tool-policy.md`; ask D4 after each VERIFY.
+10. Dispatch subagents for parallel exploration, blind verification, and audits per `references/subagent-dispatch.md`.
+11. Escalate evidence gaps or stalled directions through `references/research-breakthrough.md`; write wall memos and the failure ledger per `references/run-directory.md`.
+12. Write only incremental attempt and terminal reports defined by `references/report-contract.md`; output the per-round runlog digest in the chat.
+13. Before any terminal transition, run the cleanup gate (references/run-directory.md) and the robustness gate (a PASSED robustness-kind obligation, or scope.robustnessExempt with reason).
 
 ## Invariants
 

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

@@ -8,6 +8,8 @@ Store claim ID, exact wording, type, scope/quantifiers, assumptions, risk, verif
 
 Store id, statement, scope (subproblem ids or global), source category, risk, sensitivity plan, validation status, affected claims, status (active/revised/superseded), and revisionHistory [{at, reason, changedTo}]. Allowed source categories are problem, data, theory, verified literature, domain instruction, and modeling simplification.
 
+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)

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

@@ -3,28 +3,101 @@
 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 | confirm the full problem restatement (all sub-questions, constraints, deliverables) | accept |
+| 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 |
-| D2 假设确认 | **each subproblem starts** | the assumptions registered for THIS subproblem (numbered list: statement + source + risk); user confirms or edits | accept all |
+| D-R 文献研究 | CLAIMS_REGISTERED (before CANDIDATES_READY) | the literature list by direction (AI-found); user endorses / rejects / adds their own | accept list |
+| D2 假设确认 | **each subproblem starts** | the assumptions for THIS subproblem, each with statement + basis chain (problem quote / data evidence / literature / LLM-judgment marker) + risk + challengeable point | accept all |
 | D2' 新假设插问 | mid-subproblem discovery that changes model structure | the new assumption + its effect | record-and-continue |
-| D3 方向选择 | CANDIDATES_READY | candidate matrix (mechanism/assumptions/cost/verification/expected gain); user picks or authorizes auto | baseline |
-| D4 结果裁决 | VERIFY done | verdict (PASS/FAIL/INCONCLUSIVE) + evidence digest; user chooses accept/REVISE/switch direction/end | verdict-implied |
+| 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. **三问数学本质判定**：each sub-question 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.
+
+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
 
-Rules:
-- D0/D1: once per task. D2/D3: once per subproblem. D2': only when a discovery changes model structure. D4: once per attempt round.
+- 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 D1, ATTEMPT-from-CANDIDATES_READY without D3,
-  terminals-from-VERIFY without D4, and REVISE/RESEARCH whose reason fails to
-  reference a `decisionStack` entry id. The CLI `transition` command enforces
-  the same gate (escape hatch `--skip-gate true` is for mechanism testing only).
+  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.
 
 ## L2 display points (MUST show, never ask)
 
@@ -46,8 +119,8 @@ Rules:
 
 - Every L1 decision also appends to `ledger.scope.decisionStack`:
   `{id (e.g. D3-SP1), point, choice, at, reason}`.
-- REVISE/RESEARCH reasons MUST reference the stack entry being revisited
-  (e.g. "回退到 D3-SP1：M2-area 违反 0.07% 边长约束，改 M1-cheb").
+- 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}]`,

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

@@ -28,12 +28,21 @@ Ask one question at a time. Read the problem and attachments first. Ask only que
 - The 16 Problem Brief fields are filled once at intake for the whole problem;
   subproblem-level analysis and assumptions roll forward per attempt.
 
-## Rules
+## Exchange depth per field
 
+- **用户必须输入**：目标（1,2）、误差/精度要求（12）、验证标准（13）、最终交付物（14）——这些只能来自用户，LLM 不得替用户定。
+- **LLM 可推断但必须展示依据**：子问题（3）、决策变量（6）、参数（7）、目标函数（8）、约束（9）、假设（10）、任务类型（11）——每条附依据链（题面原句/数据证据/文献/显式 LLM 判断标记）。
+- **LLM 可纯推断但必须展示证据**：数据质量（5）——附画像统计；背景（1）、风险（15）、不适用字段（16）——附理由。
+
+## Deep-interaction rules
+
+- Every answer the LLM infers is PRESENTED with its basis before freezing; the user may challenge any item.
+- Open questions, not yes/no gates: after the LLM's analysis, ask "你有哪些补充、纠正或自己的资料？" — not merely "确认吗？".
+- High-impact exchanges loop until the user says "可以了".
 - Infer before asking.
 - Ask the highest-impact unknown first.
 - Mark irrelevant fields “not applicable” with a reason.
-- Turn “自行判断” into an explicit modeling assumption with risk and sensitivity plan.
+- Turn “自行判断” into an explicit modeling assumption with risk and sensitivity plan, listed in D2 for later challenge.
 - Assumptions are revisable: record revisionHistory and mark dependent claims stale.
 - Do not freeze scope while a missing answer can change the problem type or claim strength.
 - Do not force a proof problem to invent data or an exploratory analysis to invent an objective function.

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

@@ -28,11 +28,16 @@ State the frozen question, final scientific status, answer/recommendation, verif
 
 The following is shown DIRECTLY IN THE CHAT, not only on disk.
 
-### Intake digest (once, at intake completion)
+### Intake digest (once, at intake completion) — the six-section deep restatement
 
-【问题重述】full restatement: all sub-questions, constraints, deliverables
-【问题分析】input profile, geometric/physical structure, subproblem DAG, key difficulties
-【模型假设】the assumptions known at intake (numbered: statement + source + risk + sensitivity plan)
+【题目要点摘录】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
+【待澄清问题】open questions inviting user background/corrections/references
+
+After the D0 exchange, show the delta applied to problem-brief.md.
 
 ### Per-round digest (after EVERY attempt round)
 

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

@@ -8,7 +8,7 @@ Record author, title, year, venue, DOI/stable URL, version, retrieval date, exac
 
 ## Method matrix
 
-For each candidate method record applicability, assumptions, data needs, implementation cost, verification route, reason to try, and reason to reject.
+For each candidate method record applicability, assumptions, data needs, implementation cost, verification route, reason to try, and reason to reject — plus a mandatory `literature: [sourceId]` column. Every direction must be traceable to at least one source (engineering background, methodology paper, textbook, official documentation); a literature-free direction is marked "原创方向" with its derivation basis written out. This matrix is built during the pre-modeling RESEARCH hop (D-R exchange, interaction-protocol.md), not after solving.
 
 ## Isolated campaign
 

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

@@ -13,6 +13,17 @@ TRIAGE → SCOPE_FROZEN → INPUT_PROFILED → CLAIMS_REGISTERED → CANDIDATES_
 VERIFY may move to REVISE, RESEARCH, FORK, an independent audit, or one terminal status:
 SOLVED, PARTIAL, CONDITIONAL, INCONCLUSIVE, REFUTED, INFEASIBLE, UNIDENTIFIABLE, BLOCKED, CANCELLED.
 
+## Pre-modeling literature research (v2.6, mandatory)
+
+CLAIMS_REGISTERED → RESEARCH → CANDIDATES_READY. Before any candidate is
+built, run the D-R exchange (interaction-protocol.md): search principles and
+methods by direction, write research/sources.jsonl, attach a literature column
+to the candidate matrix. Every direction must be traceable to at least one
+source — engineering background, methodology paper, textbook, or official
+documentation; a literature-free direction must be explicitly marked
+"原创方向" with its derivation basis. Never search for solutions to the
+specific contest problem.
+
 ## Interaction gates (v2)
 
 Before EVERY transition run `run-state.mjs gate <dir> --to <status> --reason "..."`

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

@@ -28,7 +28,7 @@
         "independentAuditPassed": { "type": "boolean" },
         "interactions": {
           "type": "array",
-          "description": "L1 decision-point records: {id, decisionPoint: D1|D2|D3|D4, question, options, userAnswer, timestamp, effectOnModel} or {auto: true, decisionPoint, reason}",
+          "description": "L1 decision-point records: {id, decisionPoint: D0|D1|D-R|D2|D3|D4, question, options, userAnswer, timestamp, effectOnModel} or {auto: true, decisionPoint, reason}; D-R is the pre-modeling literature-research exchange",
           "items": { "type": "object" }
         },
         "decisionStack": {
@@ -55,7 +55,7 @@
     },
     "subproblems": {
       "type": "array",
-      "description": "Subproblem DAG nodes: {id, task, inputs, dependencies, acceptance, status, analysisLog: [{at, entry, trigger}]} — analysisLog is the rolling analysis ledger.",
+      "description": "Subproblem DAG nodes: {id, task, inputs, dependencies, acceptance, status, analysisLog: [{at, entry, trigger}]} — analysisLog is the rolling analysis ledger, updated after every deep-exchange beat.",
       "items": { "type": "object" }
     },
     "candidates": {

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

@@ -326,24 +326,34 @@ export async function createPythonEnvironment(input) {
     const finalPythonPath = environmentPython(environmentDir, platform, resolvePath)
     try {
       let adapter
+      let fallbackReason = null
       const installLogPath = ensureContained(runDir, resolvePath(runDir, 'python-environment-install.log'), platform)
       const installOptions = { cwd: runDir, stdoutFile: installLogPath, timeout: 20 * 60 * 1000, label: 'package install' }
       if (uv) {
-        adapter = 'uv'
-        const createArgs = ['venv', '--seed', environmentDir]
-        commands.push({ command: uv.executable, args: createArgs })
-        assertSuccess(await runCommand(uv.executable, createArgs, { cwd: runDir }), 'uv venv')
-        if (packages.length) {
-          const installArgs = ['pip', 'install', '--python', finalPythonPath, ...packages]
-          commands.push({ command: uv.executable, args: installArgs, stdoutFile: installLogPath })
-          process.stderr.write(`python-environment: uv installing ${packages.length} package(s); network-bound, may take minutes; log: ${installLogPath}\n`)
-          assertSuccess(await runCommand(uv.executable, installArgs, installOptions), 'uv pip install')
+        try {
+          adapter = 'uv'
+          const createArgs = ['venv', '--seed', environmentDir]
+          commands.push({ command: uv.executable, args: createArgs })
+          assertSuccess(await runCommand(uv.executable, createArgs, { cwd: runDir }), 'uv venv')
+          if (packages.length) {
+            const installArgs = ['pip', 'install', '--python', finalPythonPath, ...packages]
+            commands.push({ command: uv.executable, args: installArgs, stdoutFile: installLogPath })
+            process.stderr.write(`python-environment: uv installing ${packages.length} package(s); network-bound, may take minutes; log: ${installLogPath}\n`)
+            assertSuccess(await runCommand(uv.executable, installArgs, installOptions), 'uv pip install')
+          }
+        } catch (error) {
+          fallbackReason = error.message
+          adapter = null
+          process.stderr.write(`python-environment: uv failed (${fallbackReason}); falling back to the user's pip (which honors the system pip index configuration)\n`)
         }
-      } else {
+      }
+      if (!adapter && python) {
         adapter = 'venv'
-        const createArgs = pythonVenvArgs(python, environmentDir, platform)
-        commands.push({ command: python.executable, args: createArgs })
-        assertSuccess(await runCommand(python.executable, createArgs, { cwd: runDir }), 'python venv')
+        if (!await exists(finalPythonPath, fileStat)) {
+          const createArgs = pythonVenvArgs(python, environmentDir, platform)
+          commands.push({ command: python.executable, args: createArgs })
+          assertSuccess(await runCommand(python.executable, createArgs, { cwd: runDir }), 'python venv')
+        }
         if (packages.length) {
           const installArgs = ['-m', 'pip', 'install', ...packages]
           commands.push({ command: finalPythonPath, args: installArgs, stdoutFile: installLogPath })
@@ -351,6 +361,7 @@ export async function createPythonEnvironment(input) {
           assertSuccess(await runCommand(finalPythonPath, installArgs, installOptions), 'pip install')
         }
       }
+      if (!adapter) throw new Error(`package installation failed${fallbackReason ? `: ${fallbackReason}` : ''}`)
       await mkdir(environmentDir, { recursive: true })
       await freezeRequirements(runCommand, finalPythonPath, finalPythonPath, runDir, stagedLockPath, lockPath, commands)
       const manifest = {

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

@@ -21,7 +21,7 @@ const TRANSITIONS = Object.freeze({
   TRIAGE: ['SCOPE_FROZEN', ...STOP_TRANSITIONS],
   SCOPE_FROZEN: ['INPUT_PROFILED', ...STOP_TRANSITIONS],
   INPUT_PROFILED: ['CLAIMS_REGISTERED', ...STOP_TRANSITIONS],
-  CLAIMS_REGISTERED: ['CANDIDATES_READY', ...STOP_TRANSITIONS],
+  CLAIMS_REGISTERED: ['RESEARCH', 'CANDIDATES_READY', ...STOP_TRANSITIONS],
   CANDIDATES_READY: ['ATTEMPT', ...STOP_TRANSITIONS],
   ATTEMPT: ['EXECUTE', ...STOP_TRANSITIONS],
   EXECUTE: ['VERIFY', ...STOP_TRANSITIONS],
@@ -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)
@@ -437,16 +444,20 @@ function interactionContractViolations(run, ledger, to, reason, subproblem) {
     if (!hasDecisionRecord(scope, 'D0')) violations.push('D0 restatement interaction record missing (ledger.scope.interactions)')
     if (!hasDecisionRecord(scope, 'D1')) violations.push('D1 routing interaction record missing (ledger.scope.interactions)')
   }
+  const 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', { 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 (transitional && (to === 'REVISE' || to === 'RESEARCH')) {
+  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))) {
       violations.push(`REVISE/RESEARCH reason must reference a decisionStack entry id (available: ${ids.join(', ')})`)
@@ -455,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
 }
@@ -547,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')
@@ -571,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 () => {
@@ -579,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)
 }
@@ -629,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 })
   }