dsh-logicprobe 0.5.2 → 0.5.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Amethyst Luna
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Amethyst Luna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/engine.js

@@ -266,6 +266,82 @@ export function validateModel(input) {
                     bad(path + '.failEvent', 'must be a string');
             });
     }
+    if (root.narrative !== undefined) {
+        const narrativePath = 'narrative';
+        if (typeof root.narrative !== 'object' || root.narrative === null || Array.isArray(root.narrative)) {
+            bad(narrativePath, 'must be an object');
+        }
+        else {
+            const narrative = root.narrative;
+            const stateIds = new Set(Array.isArray(root.states) ? root.states.map((state) => state.id) : []);
+            const eventIds = new Set(Array.isArray(root.transitions) ? root.transitions.map((transition) => transition.event) : []);
+            const fromEventGroups = new Set(Array.isArray(root.transitions) ? root.transitions.map((transition) => transition.from + '|' + transition.event) : []);
+            if (typeof narrative.states !== 'object' || narrative.states === null || Array.isArray(narrative.states)) {
+                bad(narrativePath + '.states', 'must be an object mapping state id -> natural-language description');
+            }
+            else {
+                for (const [id, description] of Object.entries(narrative.states)) {
+                    if (!stateIds.has(id))
+                        bad(narrativePath + '.states', 'references unknown state ' + id);
+                    if (typeof description !== 'string' || description.length === 0)
+                        bad(narrativePath + '.states.' + id, 'must be a non-empty string');
+                }
+                for (const id of stateIds) {
+                    if (typeof narrative.states[id] !== 'string')
+                        bad(narrativePath + '.states', 'missing description for state ' + id);
+                }
+            }
+            if (typeof narrative.events !== 'object' || narrative.events === null || Array.isArray(narrative.events)) {
+                bad(narrativePath + '.events', 'must be an object mapping event id -> natural-language description');
+            }
+            else {
+                for (const [id, description] of Object.entries(narrative.events)) {
+                    if (!eventIds.has(id))
+                        bad(narrativePath + '.events', 'references unknown event ' + id);
+                    if (typeof description !== 'string' || description.length === 0)
+                        bad(narrativePath + '.events.' + id, 'must be a non-empty string');
+                }
+                for (const id of eventIds) {
+                    if (typeof narrative.events[id] !== 'string')
+                        bad(narrativePath + '.events', 'missing description for event ' + id);
+                }
+            }
+            if (!Array.isArray(narrative.scenarios)) {
+                bad(narrativePath + '.scenarios', 'must be an array of { from, event, scenario }');
+            }
+            else {
+                const seen = new Set();
+                narrative.scenarios.forEach((entry, index) => {
+                    const scenarioPath = narrativePath + '.scenarios[' + index + ']';
+                    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+                        bad(scenarioPath, 'must be an object');
+                        return;
+                    }
+                    const scenario = entry;
+                    if (typeof scenario.from !== 'string' || scenario.from.length === 0)
+                        bad(scenarioPath + '.from', 'must be a non-empty string');
+                    else if (!stateIds.has(scenario.from))
+                        bad(scenarioPath + '.from', 'unknown state ' + scenario.from);
+                    if (typeof scenario.event !== 'string' || scenario.event.length === 0)
+                        bad(scenarioPath + '.event', 'must be a non-empty string');
+                    else if (!eventIds.has(scenario.event))
+                        bad(scenarioPath + '.event', 'unknown event ' + scenario.event);
+                    if (typeof scenario.scenario !== 'string' || scenario.scenario.length === 0)
+                        bad(scenarioPath + '.scenario', 'must be a non-empty string');
+                    const key = String(scenario.from) + '|' + String(scenario.event);
+                    if (seen.has(key))
+                        bad(scenarioPath, 'duplicate scenario for (' + scenario.from + ', ' + scenario.event + ')');
+                    seen.add(key);
+                });
+                for (const key of fromEventGroups) {
+                    if (!seen.has(key)) {
+                        const sep = key.indexOf('|');
+                        bad(narrativePath + '.scenarios', 'missing scenario for (' + key.slice(0, sep) + ', ' + key.slice(sep + 1) + ')');
+                    }
+                }
+            }
+        }
+    }
     // Guard/update variable references were validated structurally; re-walk for references.
     if (Array.isArray(root.transitions)) {
         for (const entry of root.transitions) {
@@ -1617,6 +1693,7 @@ export function runVerification(input, options = {}) {
             truncated: exploration.truncated,
         },
         checks,
+        ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
         ...(comparison === undefined ? {} : { comparison }),
     };
 }

package/lib/tool.js

@@ -11,7 +11,7 @@ export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify';
  */
 export const logicProbeVerifyTool = defineTool({
     name: LOGICPROBE_VERIFY_TOOL_NAME,
-    description: 'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, event-before-state, leads-to, sequence, and atomicity; variables support monotonic inc/dec. Returns a report with S1-S7 structural checks and A1-A7 adversarial probes including shortest counterexample paths. If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
+    description: 'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?, narrative?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, event-before-state, leads-to, sequence, and atomicity; variables support monotonic inc/dec. The optional narrative block carries natural-language descriptions of states (narrative.states), events (narrative.events), and (state, event) scenarios (narrative.scenarios: [{from, event, scenario}]); when present it must fully cover the model and is echoed in the report. Returns a report with S1-S8 structural checks and A1-A11 adversarial probes including shortest counterexample paths. If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
     parameters: {
         model: {
             type: 'json',

package/lib/types/engine.d.ts

@@ -33,6 +33,20 @@ export interface TransitionSpec {
     guard?: GuardNode;
     updates?: UpdateSpec[];
 }
+export interface TransitionScenarioSpec {
+    from: string;
+    event: string;
+    /** Natural language: what this (state, event) combination represents in the real scenario. */
+    scenario: string;
+}
+export interface ModelNarrative {
+    /** Natural-language meaning of each state id. */
+    states?: Record<string, string>;
+    /** Natural-language meaning of each event id. */
+    events?: Record<string, string>;
+    /** Natural-language scenario for each distinct (from, event) combination. */
+    scenarios?: TransitionScenarioSpec[];
+}
 export interface VariableSpec {
     name: string;
     kind: 'integer' | 'boolean';
@@ -99,6 +113,8 @@ export interface LogicModelV1 {
     boundaryChecks?: BoundaryCheckSpec[];
     resourcePairs?: ResourcePairSpec[];
     idempotentEvents?: string[];
+    /** Natural-language descriptions of states, events, and (state, event) scenarios. */
+    narrative?: ModelNarrative;
 }
 export interface VerificationOptions {
     maxStates?: number;
@@ -129,6 +145,8 @@ export interface VerificationReport {
     ok: boolean;
     schemaVersion: 1;
     modelHash: string;
+    /** Echo of the model's natural-language narrative, when present. */
+    narrative?: ModelNarrative;
     summary: {
         states: number;
         transitions: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-logicprobe",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Design document & plan claim verification — enumerate claims, verify against codebase facts, then escalate to state-machine verification (S1-S8/A1-A11) and data-model verification (DS/DA/DD) for behavioral claims. Supports before/after regression, idempotency/monotonic/sequence/leads-to/atomicity constraints, and concurrency risk mining. Ships a native DeepSeek Harness (dsh) bundle that injects the claim-verification gate into the first model step.",
   "type": "module",
   "main": "lib/index.js",
@@ -21,46 +21,58 @@
   ],
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.1-rc.1"
+      "dsh": ">=0.1.0-rc.7"
     },
     "category": "skill",
     "displayName": "逻辑探针",
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": "^0.1.0-rc.7 || ^0.1.1-rc.1",
+      "dshReleases": {
+        "0.1.0-rc.7": "compatible",
+        "0.1.0-rc.8": "compatible",
+        "0.1.1-rc.1": "compatible",
+        "0.1.1-rc.2": "compatible"
+      },
+      "profiles": [
+        "headless"
+      ]
     }
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "bump": "node scripts/bump-version.mjs",
     "test:engine": "npm run build && node tests/engine/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/apply-smoke.mjs",
     "test:full": "npm run build && node tests/full-suite.mjs"
   },
-  "dependencies": {},
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-cordis-host-runner": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-cordis-host-runner": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6",
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6"
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2"
   },
   "author": {
     "name": "Amethyst Luna",
@@ -81,5 +93,8 @@
     "agentskills",
     "plugin",
     "dsh"
-  ]
+  ],
+  "engines": {
+    "node": ">=20"
+  }
 }

package/skills/logicprobe/SKILL.md

@@ -147,7 +147,7 @@ When the document under review is a refactoring plan (modifying existing state m
 
 1. **Extract the BEFORE model** from the existing codebase (not the plan — verify what the code actually does, not what the plan claims it does)
 2. **Extract the AFTER model** from the refactoring plan
-3. **Show both tables** to the user side by side and confirm the delta is intentional
+3. **Show both tables AND their model narratives** to the user side by side and confirm the delta is intentional
 4. **Run Phase 2a + 2b on the AFTER model** — same 14 checks as new design
 5. **Compare BEFORE vs AFTER**:
 
@@ -217,25 +217,76 @@ For every probe failure:
 
 ### Extraction Rule
 
-Before writing any verification code, output a transition table:
+Before writing any verification code, output the model in one of the rendering
+forms below. Default is Form A; switch forms when the machine is large or the
+display area is narrow — never let a table row wrap.
+
+**Form A — integrated transition table (default)**: formal symbols with their
+natural-language meaning inlined; the scenario each (state, event) combination
+represents is the last column:
 
 ```text
-State       | Event/Condition            | Next State    | Guard?
-------------|----------------------------|---------------|-------
-INIT        | power_ready                | IDLE          | -
-IDLE        | start_cmd                  | STARTING      | -
-IDLE        | error_detected             | ERROR         | -
-STARTING    | ack_received               | ACTIVE        | -
-STARTING    | timeout                    | ERROR         | retry==0
-STARTING    | timeout                    | FATAL         | retry>=1
-ACTIVE      | done                       | IDLE          | -
-ERROR       | cooldown_elapsed           | RECOVERING    | -
-RECOVERING  | reinit_complete            | IDLE          | -
+状态（含义）             | 事件（含义）          | 下一状态（含义）      | Guard?  | 场景（状态+事件）
+------------------------|-----------------------|----------------------|---------|--------------------
+INIT（上电待就绪）       | power_ready（电源就绪）| IDLE（空闲待命）     | -       | 就绪后进入待命
+IDLE（空闲待命）         | start_cmd（启动命令） | STARTING（启动中）   | -       | 收到命令开始启动
+STARTING（启动中）       | ack_received（收到ACK）| ACTIVE（运行中）    | -       | 启动成功进入运行
+STARTING（启动中）       | timeout（等待超时）   | ERROR（出错待恢复）  | retry==0 | 首次超时进入重试
+STARTING（启动中）       | timeout（等待超时）   | FATAL（不可恢复）    | retry>=1 | 重试耗尽转致命
+ERROR（出错待恢复）      | cooldown_elapsed（冷却结束）| RECOVERING（重初始化）| -     | 冷却结束开始恢复
 ```
 
-**CRITICAL**: Show this table to the user and ask for confirmation before generating the harness. The #1 failure mode of verification is extracting the wrong model. If the plan is ambiguous, flag it as a finding first — don't guess.
+Width discipline (Form A): keep parenthetical meanings short (state/event ≤ 6
+characters, scenario ≤ 10) and estimate every row's display width (CJK counts as
+2) to fit the available area. If any row would wrap, shorten the meanings; if it
+still will not fit, switch to Form C. A wrapped table row loses column alignment
+and is harder to read than no table at all.
+
+**Form B — sentence blocks (reading-accessible)**: one transition per block,
+scenario sentence first, fixed three-line frame. Use for detailed confirmation,
+users with reading difficulties, or machines with ≤ 10 transitions:
+
+```text
+第 1 步：就绪后进入待命
+    状态 INIT（上电待就绪）
+    发生 power_ready（电源就绪）
+    进入 IDLE（空闲待命）
+```
+
+**Form C — grouped by source state (large machines / narrow panes)**: one
+section per state, each rendered as its own small 3-column table
+（事件（含义）| 下一状态（含义）| 场景）; no cross-group column alignment to track:
+
+```text
+DEGRADED_LOADING（降级加载）
+  事件（含义）          | 下一状态（含义）      | 场景
+  first_data（首帧数据）| OK_READY（正常就绪）  | 收到首帧转就绪
+  fault（故障）         | FAULT（故障锁存）     | 故障锁存
+  power_off（下电）     | POWER_OFF（下电）     | 下电
+```
 
-**Exception**: If the runtime reports `logicprobe interaction=auto`, do NOT call `ask_user_question`. Instead: (a) cite evidence for every extracted state/transition/guard, (b) round-trip the filled model back into a transition table and compare it with the extraction table, and (c) mark the report `UNCONFIRMED`.
+Each group table is narrow (3 columns, roughly ≤ 60 display columns with short
+meanings). If one group's table would still wrap, fall back to a one-line-per-event
+bullet list for that group only.
+
+Reading rule: every row/block is one sentence — "在【状态（含义）】下发生【事件（含义）】
+→ 进入【下一状态（含义）】，即【实际场景】"。Meanings repeat on purpose: each entry is
+self-contained. The machine-readable model keeps the same information in its
+`narrative` block (`narrative.states`, `narrative.events`, `narrative.scenarios`).
+
+**CRITICAL**: Show the chosen form to the user and ask for confirmation before
+generating the harness. Because the natural language is inlined, any entry that
+reads wrong to the user — a state/event meaning that is off, or a scenario that
+does not match reality — means the model is wrong even if the symbols are
+consistent. The #1 failure mode of verification is extracting the wrong model. If
+the plan is ambiguous, flag it as a finding first — don't guess.
+
+**Exception**: If the runtime reports `logicprobe interaction=auto`, do NOT call
+`ask_user_question`. Instead: (a) cite evidence for every cell/entry — each
+state/event meaning and each scenario must trace to a source sentence, (b)
+round-trip the filled model (including its `narrative` block) back into the SAME
+rendering form and compare it with the extraction, and (c) mark the report
+`UNCONFIRMED`.
 
 ### Code-Level Behavioral Suggestion
 

package/skills/logicprobe/references/dsh-model-schema.md

@@ -33,6 +33,65 @@ The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The eng
 | `boundaryChecks` | no | `{ variable, values: number[] }` for A5 |
 | `resourcePairs` | no | `{ resource, acquireEvent, releaseEvent, failEvent? }` for A4/A6 |
 | `idempotentEvents` | no | Events that must be replay-safe; verified by A8 |
+| `narrative` | no | Natural-language descriptions of states, events, and (state, event) scenarios — echoed in the report |
+
+## Model narrative (natural-language context)
+
+The model may carry a `narrative` block explaining, in natural language, what
+every symbol means in the real scenario. It is what gets shown to the user when
+the extracted model is presented for confirmation, and the report echoes it back
+so findings can be read against real scenarios instead of bare ids.
+
+```json
+"narrative": {
+  "states": {
+    "NEW": "订单已创建，等待支付",
+    "PAID": "已支付，等待发货",
+    "SHIPPED": "已发货，等待签收",
+    "DONE": "已完成（终态）",
+    "CANCELLED": "已取消（终态）"
+  },
+  "events": {
+    "pay": "买家完成支付",
+    "ship": "仓库发货",
+    "deliver": "买家签收",
+    "cancel": "取消订单"
+  },
+  "scenarios": [
+    { "from": "NEW", "event": "pay", "scenario": "下单后支付成功，订单进入待发货" },
+    { "from": "PAID", "event": "ship", "scenario": "已支付订单发货，进入运输中" },
+    { "from": "SHIPPED", "event": "deliver", "scenario": "签收完成，订单结束" },
+    { "from": "NEW", "event": "cancel", "scenario": "未支付订单被取消" },
+    { "from": "PAID", "event": "cancel", "scenario": "已支付订单取消并退款" }
+  ]
+}
+```
+
+**Completeness contract**: when `narrative` is present, all three parts are
+required and must fully cover the model — every declared state needs a
+`narrative.states` entry, every event used in `transitions` needs a
+`narrative.events` entry, and every distinct `(from, event)` group needs a
+`narrative.scenarios` entry. Keys must reference declared ids; unknown
+references, missing coverage, and duplicate scenario keys are model validation
+errors. The report's `narrative` field echoes the block unchanged.
+
+**Presenting the model**: when showing the extracted model for confirmation, render
+the natural language INLINE in the model presentation, not as a separate block.
+Three rendering forms (all derive from the same `narrative` data):
+
+- **Form A — integrated transition table (default)**: one row per transition with
+  state/event meanings in parentheses and the scenario as the last column. Keep
+  meanings short (state/event ≤ 6 characters, scenario ≤ 10) and estimate row
+  width (CJK counts as 2) so rows fit the display area — a wrapped row loses
+  column alignment and readability collapses.
+- **Form B — sentence blocks (reading-accessible)**: scenario sentence first, then
+  a fixed three-line frame (状态…/发生…/进入…). Use for detailed confirmation,
+  users with reading difficulties, or ≤ 10 transitions.
+- **Form C — grouped by source state (large machines / narrow panes)**: one
+  section per state, each rendered as its own small 3-column table
+  （`event（含义）| NEXT（含义）| 场景`）; no cross-group column alignment to
+  track. Use for ≥ 15 transitions or narrow display areas; if a group table would
+  still wrap, fall back to a one-line-per-event bullet list for that group.
 
 ## Guards
 

package/skills/logicprobe/references/logic-verification-guide.md

@@ -45,16 +45,48 @@ Extract every claim that uses absolute language:
 | "cannot ..." | "cannot deadlock" | No absorbing cycle exists |
 | "all paths ..." | "all paths lead to ERROR on failure" | Every failure event reaches ERROR (not FATAL, not stuck) |
 
+### Step 4.5: Write the Natural Language and Pick a Rendering Form
+
+Do NOT keep the natural-language explanations in a separate block — integrate them
+into the model presentation so every entry reads like a sentence in the real
+scenario. Write meanings for every state, every event, and every distinct
+(state, event) combination (carry them in the model's `narrative` block:
+`narrative.states`, `narrative.events`, `narrative.scenarios`; the report
+echoes them back). Then render one of three forms:
+
+**Form A — integrated transition table (default)**: `STATE（含义）` /
+`event（含义）` / `NEXT（含义）` columns plus a final scenario column, so each
+row is one self-contained sentence. Width discipline: keep meanings short
+(state/event ≤ 6 characters, scenario ≤ 10) and estimate row width (CJK counts
+as 2) to fit the display area — a wrapped row loses column alignment and
+readability collapses. If a row would wrap, shorten meanings; if it still will
+not fit, use Form C.
+
+**Form B — sentence blocks (reading-accessible)**: one transition per block,
+scenario sentence first, then a fixed three-line frame (状态…/发生…/进入…). Use
+for detailed confirmation, users with reading difficulties, or ≤ 10 transitions.
+
+**Form C — grouped by source state (large machines / narrow panes)**: one
+section per state, each rendered as its own small 3-column table
+（`event（含义）| NEXT（含义）| 场景`）; no cross-group column alignment to track.
+Use for ≥ 15 transitions or when the display area is too narrow for Form A. If one
+group's table would still wrap, fall back to a one-line-per-event bullet list for
+that group only.
+
 ### Step 5: Confirm with User
 
-Show the extracted transition table BEFORE writing the harness. Ask:
+Show the rendered model (the chosen form, symbols + inlined natural language)
+BEFORE writing the harness. Ask:
 
 1. Are all states captured?
 2. Are all transitions and guards correct?
 3. Are there undocumented transitions not in the plan?
 4. Is the initial state correct?
+5. Does every entry read correctly — state/event meanings and the (state, event)
+   scenario all match the real situation?
 
-Only proceed after confirmation. A wrong model produces wrong counter-examples, which wastes more time than no verification at all.
+Only proceed after confirmation. A wrong model produces wrong counter-examples,
+which wastes more time than no verification at all.
 
 ## Probe Design Patterns
 
@@ -348,7 +380,7 @@ The BEFORE model comes from **code, not the plan**. The plan may describe the cu
 1. Read the relevant source files (state machine dispatch, state enum, handler functions)
 2. Extract the ACTUAL transition logic from code, not from the plan's description of "current behavior"
 3. Extract the AFTER model from the plan as usual
-4. Display both tables side by side
+4. Display both tables AND their model narratives side by side
 
 ### Comparison Methodology
 
@@ -389,7 +421,7 @@ Manual verification is reliable for state machines with **≤ 10 states and ≤
 
 ### Prerequisites
 
-- Transition table has been extracted and confirmed with the user
+- Transition table and model narrative have been extracted and confirmed with the user
 - You have the full table in context (from Phase 2 extraction step)
 - **Harness validation** (Python mode only): After filling in `verification-harness.py`, translate the Python `STATES` dict BACK into a transition table and compare it against the confirmed extraction table. If they differ, fix the harness. This catches typo and whitespace errors in manual dict construction.
 

package/src/engine.ts

@@ -46,6 +46,22 @@ export interface TransitionSpec {
   updates?: UpdateSpec[]
 }
 
+export interface TransitionScenarioSpec {
+  from: string
+  event: string
+  /** Natural language: what this (state, event) combination represents in the real scenario. */
+  scenario: string
+}
+
+export interface ModelNarrative {
+  /** Natural-language meaning of each state id. */
+  states?: Record<string, string>
+  /** Natural-language meaning of each event id. */
+  events?: Record<string, string>
+  /** Natural-language scenario for each distinct (from, event) combination. */
+  scenarios?: TransitionScenarioSpec[]
+}
+
 export interface VariableSpec {
   name: string
   kind: 'integer' | 'boolean'
@@ -86,6 +102,8 @@ export interface LogicModelV1 {
   boundaryChecks?: BoundaryCheckSpec[]
   resourcePairs?: ResourcePairSpec[]
   idempotentEvents?: string[]
+  /** Natural-language descriptions of states, events, and (state, event) scenarios. */
+  narrative?: ModelNarrative
 }
 
 export interface VerificationOptions {
@@ -121,6 +139,8 @@ export interface VerificationReport {
   ok: boolean
   schemaVersion: 1
   modelHash: string
+  /** Echo of the model's natural-language narrative, when present. */
+  narrative?: ModelNarrative
   summary: {
     states: number
     transitions: number
@@ -347,6 +367,66 @@ export function validateModel(input: unknown): { ok: true; model: LogicModelV1 }
       if (pair.failEvent !== undefined && typeof pair.failEvent !== 'string') bad(path + '.failEvent', 'must be a string')
     })
   }
+  if (root.narrative !== undefined) {
+    const narrativePath = 'narrative'
+    if (typeof root.narrative !== 'object' || root.narrative === null || Array.isArray(root.narrative)) {
+      bad(narrativePath, 'must be an object')
+    } else {
+      const narrative = root.narrative as Record<string, unknown>
+      const stateIds = new Set<string>(Array.isArray(root.states) ? (root.states as StateSpec[]).map((state) => state.id) : [])
+      const eventIds = new Set<string>(Array.isArray(root.transitions) ? (root.transitions as TransitionSpec[]).map((transition) => transition.event) : [])
+      const fromEventGroups = new Set<string>(Array.isArray(root.transitions) ? (root.transitions as TransitionSpec[]).map((transition) => transition.from + '|' + transition.event) : [])
+      if (typeof narrative.states !== 'object' || narrative.states === null || Array.isArray(narrative.states)) {
+        bad(narrativePath + '.states', 'must be an object mapping state id -> natural-language description')
+      } else {
+        for (const [id, description] of Object.entries(narrative.states as Record<string, unknown>)) {
+          if (!stateIds.has(id)) bad(narrativePath + '.states', 'references unknown state ' + id)
+          if (typeof description !== 'string' || description.length === 0) bad(narrativePath + '.states.' + id, 'must be a non-empty string')
+        }
+        for (const id of stateIds) {
+          if (typeof (narrative.states as Record<string, unknown>)[id] !== 'string') bad(narrativePath + '.states', 'missing description for state ' + id)
+        }
+      }
+      if (typeof narrative.events !== 'object' || narrative.events === null || Array.isArray(narrative.events)) {
+        bad(narrativePath + '.events', 'must be an object mapping event id -> natural-language description')
+      } else {
+        for (const [id, description] of Object.entries(narrative.events as Record<string, unknown>)) {
+          if (!eventIds.has(id)) bad(narrativePath + '.events', 'references unknown event ' + id)
+          if (typeof description !== 'string' || description.length === 0) bad(narrativePath + '.events.' + id, 'must be a non-empty string')
+        }
+        for (const id of eventIds) {
+          if (typeof (narrative.events as Record<string, unknown>)[id] !== 'string') bad(narrativePath + '.events', 'missing description for event ' + id)
+        }
+      }
+      if (!Array.isArray(narrative.scenarios)) {
+        bad(narrativePath + '.scenarios', 'must be an array of { from, event, scenario }')
+      } else {
+        const seen = new Set<string>()
+        narrative.scenarios.forEach((entry, index) => {
+          const scenarioPath = narrativePath + '.scenarios[' + index + ']'
+          if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            bad(scenarioPath, 'must be an object')
+            return
+          }
+          const scenario = entry as Record<string, unknown>
+          if (typeof scenario.from !== 'string' || scenario.from.length === 0) bad(scenarioPath + '.from', 'must be a non-empty string')
+          else if (!stateIds.has(scenario.from)) bad(scenarioPath + '.from', 'unknown state ' + scenario.from)
+          if (typeof scenario.event !== 'string' || scenario.event.length === 0) bad(scenarioPath + '.event', 'must be a non-empty string')
+          else if (!eventIds.has(scenario.event)) bad(scenarioPath + '.event', 'unknown event ' + scenario.event)
+          if (typeof scenario.scenario !== 'string' || scenario.scenario.length === 0) bad(scenarioPath + '.scenario', 'must be a non-empty string')
+          const key = String(scenario.from) + '|' + String(scenario.event)
+          if (seen.has(key)) bad(scenarioPath, 'duplicate scenario for (' + scenario.from + ', ' + scenario.event + ')')
+          seen.add(key)
+        })
+        for (const key of fromEventGroups) {
+          if (!seen.has(key)) {
+            const sep = key.indexOf('|')
+            bad(narrativePath + '.scenarios', 'missing scenario for (' + key.slice(0, sep) + ', ' + key.slice(sep + 1) + ')')
+          }
+        }
+      }
+    }
+  }
   // Guard/update variable references were validated structurally; re-walk for references.
   if (Array.isArray(root.transitions)) {
     for (const entry of root.transitions as TransitionSpec[]) {
@@ -1692,6 +1772,7 @@ export function runVerification(input: unknown, options: VerificationOptions = {
       truncated: exploration.truncated,
     },
     checks,
+    ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
     ...(comparison === undefined ? {} : { comparison }),
   }
 }

package/src/tool.ts

@@ -14,7 +14,7 @@ export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify'
 export const logicProbeVerifyTool = defineTool({
   name: LOGICPROBE_VERIFY_TOOL_NAME,
   description:
-    'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, event-before-state, leads-to, sequence, and atomicity; variables support monotonic inc/dec. Returns a report with S1-S7 structural checks and A1-A7 adversarial probes including shortest counterexample paths. If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
+    'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?, narrative?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range, event-before-state, leads-to, sequence, and atomicity; variables support monotonic inc/dec. The optional narrative block carries natural-language descriptions of states (narrative.states), events (narrative.events), and (state, event) scenarios (narrative.scenarios: [{from, event, scenario}]); when present it must fully cover the model and is echoed in the report. Returns a report with S1-S8 structural checks and A1-A11 adversarial probes including shortest counterexample paths. If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
   parameters: {
     model: {
       type: 'json',