dsh-logicprobe 1.0.0 → 1.2.0

package/README.en-US.md

@@ -25,53 +25,9 @@ logicprobe checks a claim against the thing it describes. Facts go against the s
 
 The model is always shown as a transition table first, and **confirmed with the user before it runs**. Extraction errors are the dominant failure mode.
 
-## Installation
-
-### Claude Code install (recommended)
-
-Add the marketplace to **Claude Code**'s `~/.claude/settings.json`:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "logicprobe": {
-      "source": { "source": "github", "repo": "AmethystLuna/logicprobe" }
-    }
-  }
-}
-```
-
-Then install from the CLI:
-
-```bash
-claude plugin install logicprobe@logicprobe
-```
-
-### Claude Code manual install
-
-```bash
-git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/logicprobe
-```
-
-Then enable it in `~/.claude/settings.json`:
-
-```json
-{
-  "enabledPlugins": {
-    "logicprobe@dev": true
-  }
-}
-```
-
-## DeepSeek Harness (dsh)
-
-Native dsh support ships as a cordis plugin bundle at the repository root, declared by `dsh.bundle` in the root `package.json`.
+## Tools and Reports
 
-The bundle does three things:
-
-1. **Registers the skills.** They follow the Agent Skills open standard and are discovered as-is by dsh's `skill-filesystem` provider. No extra code.
-2. **Injects the gate text.** The first model step of every session receives the claim-verification gate (1% Rule / Red Flags / proactive suggestion). This is the dsh counterpart of the Claude `SessionStart` hook.
-3. **Registers the native tools and a context.** The tools live on `ctx.tools`. A policy-aware `logicprobe:mode` context lives on `ctx.systemPrompt`. A model-visible catalog entry is available through `cordis_inspect`.
+The two lists below (the native tools, and how to read their reports) do not depend on how you install: dsh uses the native tools, while Claude Code / Codex / Cursor / a terminal / CI use the same skills and the Python CLI engine (see "Usage").
 
 The tools:
 
@@ -102,45 +58,32 @@ Every report separates "the tool ran" from "the review passed":
 | `hashSpec` | The published specification `modelHash` follows — see [`hash-spec.md`](skills/logicprobe/references/hash-spec.md). |
 | `hashes` | Every hash the report carries, in one place (model, diagram/matrix, before/after). |
 | `metadataKeys` | Paths of the `_`-prefixed annotation keys the input carried. |
-| `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}` — a narrative may cover part of the model, and this is how much is still undocumented. |
+| `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}` — a narrative may cover part of the model, and this is how much is still undocumented. The gap is also a `NARRATIVE_PARTIAL` (info) finding, so a gate need not parse `nextSteps` text. |
 | `nextSteps` | What to do next, derived from the findings; never empty, and identical for two runs over the same input. |
 
 Reading `ok` turns a model with a deadlock into a pass; the verdict is the judgement. The non-DSH Python CLI follows the verdict with its exit code: `pass`/`pass_with_findings` → `0`, `fail` or a refusal → `2`.
 
-### The model carries its own archive record (`_`-prefixed keys)
-
-Any key starting with `_` — at any level: `_source`, `_verified`, `_extraction_caveats`, `states[0]._note` — is **annotation metadata**: the schema skips it, `modelHash` excludes it, and the report echoes it as `metadataKeys`. Provenance and verification snapshots can therefore live inside the model file instead of a sidecar that drifts away from it, without changing the model's hash identity. Every other key stays closed: a mistyped `sttes` is still an error. `verify model.json --hash-check <hex>` answers whether a recorded hash belongs to any published specification.
-
-Install (native bundle, recommended):
-
-```bash
-# from npm (package name: dsh-logicprobe)
-dsh plugin --profile web add dsh-logicprobe
-# or from GitHub source
-dsh plugin --profile web add "github:AmethystLuna/logicprobe"
-# when dsh is not installed globally
-npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-logicprobe
-```
-
-Restart the profile afterwards. `dsh --profile web --dump-config` must show the `id: logicprobe` row with `enabled: true`. More options (plain skill copy, project-level install) are in [`.dsh/INSTALL.md`](.dsh/INSTALL.md).
+**A tool prints the report body, not JSON.** The structured report is unchanged (`schema`/`verdict`/`hashes`/check ids/`code`/`evidence`/`path` all still there); only the text a model reads changed:
 
-pnpm 11 has a release-age gate. It holds back versions published less than a day ago (`minimumReleaseAge`, default 1440 minutes), and its default is non-strict, so a bare-name install **silently resolves to the previous version**. The profile then looks like the release never happened. To get the newest version within about 24 hours of a release, pin it:
+- a passing check appears in the `CHECKS` inventory line and does not expand a body — a passing check carries nothing to act on;
+- a fact reported by more than one check (for example `S5` and `A1` reporting the same `(state, event)` pairs) is listed under the check that reported it first, and the later check says it adds nothing instead of reprinting it;
+- findings that render identically inside one check collapse to one line with `(xN)`;
+- only `error` findings inline their `evidence`; warnings do not — evidence is machine data, not reading material.
 
-```bash
-dsh plugin --profile web add dsh-logicprobe@<version>
-```
+Pass `reportView: "full"` when you need the structured report itself (for example to hand it to `logicprobe_report_diff`, which matches on `check + code + evidence`; a body cannot stand in for the object). Hosts without dsh run the CLI, which prints the report JSON: the body is the dsh tools' presentation layer.
 
-pnpm records that version in a `minimumReleaseAgeExclude` entry in the profile's `pnpm-workspace.yaml`. That entry is pnpm's documented escape hatch.
+### The model carries its own archive record (`_`-prefixed keys)
 
-> Package name note: the npm package is `dsh-logicprobe`, with no scope. In the web profile's `package.json`, both the dependency key and the `dsh.profile.bundles` entry must use that name. On a mismatch the dsh loader cannot find `node_modules/dsh-logicprobe` and the boot fails.
+Any key starting with `_` — at any level: `_source`, `_verified`, `_extraction_caveats`, `states[0]._note` — is **annotation metadata**: the schema skips it, `modelHash` excludes it, and the report echoes it as `metadataKeys`. Provenance and verification snapshots can therefore live inside the model file instead of a sidecar that drifts away from it, without changing the model's hash identity. Every other key stays closed: a mistyped `sttes` is still an error. `verify model.json --hash-check <hex>` answers whether a recorded hash belongs to any published specification.
 
 ## UML Modelling and Review
 
-`logicprobe_uml` draws a LogicModelV1 as UML. It also reads a hand-drawn UML diagram back into a model, and it reviews the modelling itself. It has three actions:
+`logicprobe_uml` draws a LogicModelV1 as UML. It also reads a hand-drawn UML diagram back into a model, reviews the modelling itself, and prints the label and comment conventions the parser accepts. It has four actions:
 
 - **render**: model to diagram. Mermaid covers state, activity flowchart and sequence views. PlantUML covers state and sequence. Any construct the notation cannot express becomes a warning instead of a silent drop. PlantUML activity is refused, because that syntax cannot carry a graph with merges or cycles faithfully.
 - **parse**: diagram to model. It reads Mermaid and PlantUML state or activity diagrams, so a hand-drawn diagram can go straight into `logicprobe_verify`. Two inputs are refused because they cannot become a machine: a sequence diagram (a trace cannot reconstruct a machine), and any other Mermaid family (`classDiagram`, `erDiagram`, `gantt`, `mindmap`, …), which comes back as `errorCode: "UML_NOT_A_STATE_DIAGRAM"` naming the family.
 - **review**: audits the modelling. It reports structural defects and documentation gaps. The structural defects are unreachable states, dead ends, ambiguous branches, self-loops with no exit, and duplicate transitions. The documentation gaps are a missing narrative, unbounded variables, states a reader cannot map back to code, and label drift between diagram and narrative. It also runs the fidelity check: it parses the diagram back into a model and reports every structural difference.
+- **explain-labels**: prints the label spellings and ignored-line rules the parser applies (`directiveLines`, `acceptedLabelForms`, `renderedForm`, `ignoredLines`, `rules`), with no diagram needed. Reach for it when a hand-drawn diagram and a rendered one disagree; the CLI mirror is `uml-review --explain-labels`.
 
 **A structure diagram is the dangerous case, because it parses.** A PlantUML component, package, class or deployment diagram declares no diagram kind, so the parser meets its keywords line by line. The arrows look like transitions, so `parse` returns a by-product model — now together with an error finding `UML_NOT_A_STATE_DIAGRAM`, `discardedConstructs` (every declaration it could not represent, with line and text), `discardedEdges` (the arrows misread as transitions) and `verdict: "fail"`. Read that as: **this file has no model and this diagram was not reviewed.** Do not feed the by-product to `logicprobe_verify` and call the result an architecture review. Structural checks over a real dependency graph (allowed-edge matrices, cycles, isolated nodes) do not exist yet; the codes `UML020`+ are reserved for them.
 
@@ -184,7 +127,7 @@ The dependency matrix is the single source of truth:
 
 ## Usage
 
-The plugin injects a capability notification into the first model step. There is **one skill per domain** — four in total. `logicprobe` is the entry point: load it whenever you have any thought of checking whether something about the code is true, and its routing table hands a neighbouring domain on.
+The plugin injects a capability notification into the first model step. There is **one skill per domain**. `logicprobe` is the entry point: load it whenever you have any thought of checking whether something about the code is true, and its routing table hands a neighbouring domain on.
 
 | Skill | Domain | Typical trigger |
 |---|---|---|
@@ -198,20 +141,89 @@ Behavioural questions still follow the suggest-don't-escalate rule: offer an opt
 
 Outside dsh (Claude Code, Cursor, Codex, a terminal, CI) the install is the **repository** (marketplace or git), which carries `tools/python/logicprobe-engine.py`. Python 3.8+ standard library only. The dsh bundle (npm or profile install) does not include it. With a LogicModelV1 JSON at hand, run it directly:
 
-- `verify` runs S1-S8 / A1-A14 / D1-D4
+- `verify` runs S1-S8 / A1-A14 / D1-D4 (`--before-model`, `--baseline`, `--hash-spec`, `--hash-check`)
 - `compose` runs the C1 / C2 composition
 - `export` emits UPPAAL, TLA+, PRISM and SPIN input
-- `uml-render`, `uml-parse` and `uml-review` cover the UML front end
+- `uml-render`, `uml-parse` and `uml-review` cover the UML front end (`uml-review --explain-labels` prints the label and comment conventions the parser accepts)
+- `structure` and `granularity` audit dependency graphs and multi-level refinement (UML020-UML031)
+- `--help` is the authoritative subcommand list; this page does not copy it
 
-Its output is byte-identical to the dsh tools, cross-checked by `tests/python/run.mjs`. When the model exists only as extracted tables, fill in `tools/python/verification-harness.py`. Data-model checks use `tools/python/data-model-harness.py`. When Python is unavailable, for example on an air-gapped machine, the matching guide describes a manual verification mode.
+Every subcommand the engine implements produces a report byte-identical to the dsh tool, cross-checked by `tests/python/run.mjs`. When the model exists only as extracted tables, fill in `tools/python/verification-harness.py`. **Data-model verification has no mirror subcommand**: hosts without dsh use `tools/python/data-model-harness.py` or the manual mode in the matching guide, and the concurrency claim scan is the same story (it only routes). When Python is unavailable, for example on an air-gapped machine, the matching guide describes a manual verification mode.
 
 Sample models live under [`examples/`](examples/README.md): an order state machine before/after, an e-commerce data model, and a User field migration.
 
-## Codex CLI
+## Installation
 
-This plugin also supports OpenAI Codex CLI. Skills follow the Agent Skills standard and work identically on both platforms.
+### Claude Code (recommended)
 
-### Codex install
+Add the marketplace to **Claude Code**'s `~/.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "logicprobe": {
+      "source": { "source": "github", "repo": "AmethystLuna/logicprobe" }
+    }
+  }
+}
+```
+
+Then install from the CLI:
+
+```bash
+claude plugin install logicprobe@logicprobe
+```
+
+### Claude Code manual install
+
+```bash
+git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/logicprobe
+```
+
+Then enable it in `~/.claude/settings.json`:
+
+```json
+{
+  "enabledPlugins": {
+    "logicprobe@dev": true
+  }
+}
+```
+
+### DeepSeek Harness (dsh)
+
+Native dsh support ships as a cordis plugin bundle at the repository root, declared by `dsh.bundle` in the root `package.json`.
+
+The bundle does three things:
+
+1. **Registers the skills.** They follow the Agent Skills open standard and are discovered as-is by dsh's `skill-filesystem` provider. No extra code.
+2. **Injects the gate text.** The first model step of every session receives the claim-verification gate (proactive suggestion). This is the dsh counterpart of the Claude `SessionStart` hook.
+3. **Registers the native tools and a context.** The tools live on `ctx.tools`. A policy-aware `logicprobe:mode` context lives on `ctx.systemPrompt`. A model-visible catalog entry is available through `cordis_inspect`.
+
+```bash
+# from npm (package name: dsh-logicprobe)
+dsh plugin --profile web add dsh-logicprobe
+# or from GitHub source
+dsh plugin --profile web add "github:AmethystLuna/logicprobe"
+# when dsh is not installed globally
+npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-logicprobe
+```
+
+Restart the profile afterwards. `dsh --profile web --dump-config` must show the `id: logicprobe` row with `enabled: true`. More options (plain skill copy, project-level install) are in [`.dsh/INSTALL.md`](.dsh/INSTALL.md).
+
+pnpm 11 has a release-age gate. It holds back versions published less than a day ago (`minimumReleaseAge`, default 1440 minutes), and its default is non-strict, so a bare-name install **silently resolves to the previous version**. The profile then looks like the release never happened. To get the newest version within about 24 hours of a release, pin it:
+
+```bash
+dsh plugin --profile web add dsh-logicprobe@<version>
+```
+
+pnpm records that version in a `minimumReleaseAgeExclude` entry in the profile's `pnpm-workspace.yaml`. That entry is pnpm's documented escape hatch.
+
+> Package name note: the npm package is `dsh-logicprobe`, with no scope. In the web profile's `package.json`, both the dependency key and the `dsh.profile.bundles` entry must use that name. On a mismatch the dsh loader cannot find `node_modules/dsh-logicprobe` and the boot fails.
+
+### Codex CLI
+
+This plugin also supports OpenAI Codex CLI. Skills follow the Agent Skills standard and work identically on both platforms.
 
 ```bash
 # Add as a marketplace
@@ -229,12 +241,10 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.codex/plugins/logicp
 
 Skills are invoked with `$logicprobe`, or selected automatically by Codex from the task context.
 
-## Cursor
+### Cursor
 
 Cursor 2.5+ has built-in plugin support.
 
-### Cursor install
-
 ```bash
 # Clone to Cursor plugins directory
 git clone https://github.com/AmethystLuna/logicprobe.git ~/.cursor/plugins/logicprobe
@@ -242,12 +252,10 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.cursor/plugins/logic
 
 Or install from the Cursor plugin marketplace UI: `/add-plugin AmethystLuna/logicprobe`
 
-## Kimi CLI
+### Kimi CLI
 
 Kimi CLI discovers skills from `.claude/skills/` paths automatically. The `.kimi-plugin/plugin.json` manifest registers the plugin for Kimi's plugin manager.
 
-### Kimi install
-
 ```bash
 # Via Kimi plugin manager
 /plugins install https://github.com/AmethystLuna/logicprobe.git
@@ -258,7 +266,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.kimi/plugins/logicpr
 
 Skills are invoked with `/skill:logicprobe`.
 
-## OpenCode
+### OpenCode
 
 Skills are auto-discovered from `.claude/skills/` and `.codex/skills/` paths. Add this to your `opencode.json`:
 
@@ -270,7 +278,7 @@ Skills are auto-discovered from `.claude/skills/` and `.codex/skills/` paths. Ad
 
 Or install through `skop`, which consumes the Claude marketplace manifest. See `.opencode/INSTALL.md`.
 
-## ZCode (Z.AI)
+### ZCode (Z.AI)
 
 ZCode 3.0+ follows the Agent Skills standard. It has no plugin marketplace, so copy the skills yourself:
 

package/README.md

@@ -23,53 +23,9 @@ logicprobe 核验声称与实物是否一致。事实类对着源码查。行为
 
 模型永远先以转换表形式展示，**经用户确认后才运行**。模型提取错误是验证的头号失败模式。
 
-## 安装
-
-### Claude Code 安装（推荐）
-
-在 **Claude Code** 的 `~/.claude/settings.json` 中添加 marketplace：
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "logicprobe": {
-      "source": { "source": "github", "repo": "AmethystLuna/logicprobe" }
-    }
-  }
-}
-```
-
-然后通过 CLI 安装：
-
-```bash
-claude plugin install logicprobe@logicprobe
-```
-
-### Claude Code 手动安装
-
-```bash
-git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/logicprobe
-```
-
-然后在 `~/.claude/settings.json` 中启用：
-
-```json
-{
-  "enabledPlugins": {
-    "logicprobe@dev": true
-  }
-}
-```
-
-## DeepSeek Harness (dsh)
-
-原生 dsh 支持以 cordis 插件 bundle 的形式提供，位于**仓库根**，由根 `package.json` 的 `dsh.bundle` 声明。
+## 工具与报告
 
-这个 bundle 做三件事：
-
-1. **注册技能。** 技能遵循 Agent Skills 开放标准，由 dsh 的 `skill-filesystem` provider 原样发现，不需要额外代码。
-2. **注入门禁文本。** 每个会话的第一个模型步骤会收到 claim 验证门禁（1% Rule / Red Flags / 主动建议）。这是 Claude `SessionStart` hook 在 dsh 上的对应物。
-3. **注册原生工具与上下文。** 工具挂在 `ctx.tools` 上，另有一条策略感知上下文 `logicprobe:mode`（`ctx.systemPrompt`），以及模型可见目录条目（`cordis_inspect`）。
+下面两份清单（原生工具清单，以及怎么读它们的报告）与**安装方式无关**：dsh 走原生工具，Claude Code / Codex / Cursor / 终端 / CI 走同一套技能与 Python CLI 引擎（见「使用」）。
 
 工具清单：
 
@@ -100,45 +56,32 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/l
 | `hashSpec` | `modelHash` 依据的已发布规范（见 [`hash-spec.md`](skills/logicprobe/references/hash-spec.md)）。 |
 | `hashes` | 本次报告涉及的全部哈希集中一处（模型哈希、图/矩阵哈希、前后模型哈希）。 |
 | `metadataKeys` | 输入里带 `_` 前缀的注记键路径（仅当存在时出现）。 |
-| `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}`：narrative **允许部分覆盖**，这里报告还差多少。 |
+| `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}`：narrative **允许部分覆盖**，这里报告还差多少；缺口同时是一条 `NARRATIVE_PARTIAL`（info）发现，门禁不必去解析 `nextSteps` 文本。 |
 | `nextSteps` | 由发现推导的下一步，永不为空，同一输入两次运行逐字一致。 |
 
 只看 `ok` 会把「有死锁」的模型读成通过——判据是 `verdict`。非 DSH 的 Python CLI 退出码跟随 verdict：`pass`/`pass_with_findings` → `0`，`fail` 或拒绝 → `2`。
 
-### 模型自带的归档记录（`_` 前缀键）
-
-任何以 `_` 开头的键（任意层级，如 `_source`、`_verified`、`_extraction_caveats`、`states[0]._note`）都是**注记元数据**：schema 跳过、`modelHash` 排除、报告以 `metadataKeys` 回显。这样来源与验证快照可以跟模型放在同一个文件里，不必再维护一个会漂移的 sidecar，而模型的哈希身份不变。其余键仍然闭合——拼错的 `sttes` 依旧报错。用 `verify model.json --hash-check <hex>` 可回答某个历史哈希是否属于任何已发布规范。
-
-安装（原生 bundle，推荐）：
-
-```bash
-# 从 npm 安装（包名 dsh-logicprobe）
-dsh plugin --profile web add dsh-logicprobe
-# 或从 GitHub 源码安装
-dsh plugin --profile web add "github:AmethystLuna/logicprobe"
-# 未全局安装 dsh 时可用 npx
-npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-logicprobe
-```
-
-装完重启 profile。运行 `dsh --profile web --dump-config` 应看到 `id: logicprobe` 且 `enabled: true`。更多方式（纯技能拷贝、项目级等）见 [`.dsh/INSTALL.md`](.dsh/INSTALL.md)。
+**工具打印的是报告正文，不是 JSON。** 结构化报告本身没有变（`schema`/`verdict`/`hashes`/检查项 id/`code`/`evidence`/`path` 都在），变的只是给模型看的那份文本：
 
-pnpm 11 有一个发布年龄闸门。它挡住发布不满一天的新版本（`minimumReleaseAge`，默认 1440 分钟），而且默认是非严格模式，所以裸名安装会**静默装到上一个版本**，profile 看起来像这次发版没发生。发版后约 24 小时内要装最新版，请带上版本号：
+- 通过的检查只出现在 `CHECKS` 清单行里，不再展开正文（通过的检查没有可行动内容）；
+- 同一个事实被多个检查各报一遍时（例如 `S5` 与 `A1` 报同一批 `(state, event)` 对），只在先出现的检查里列出，后出现的检查写明「与上面重复」，不再重印；
+- 同一检查内逐字相同的发现折叠成一行并标注 `(xN)`；
+- 只有 `error` 级发现内联 `evidence`，`warning` 级不内联——那是机器字段，不是阅读材料。
 
-```bash
-dsh plugin --profile web add dsh-logicprobe@<version>
-```
+需要结构化报告本体时传 `reportView: "full"`（例如要把它交给 `logicprobe_report_diff`，它按 `check + code + evidence` 匹配身份，正文替代不了对象）。非 dsh 宿主走 CLI，它直接打印报告 JSON：那份正文是 dsh 工具的呈现层。
 
-pnpm 会把该版本写进 profile 的 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 条目。那是它官方的豁免方式。
+### 模型自带的归档记录（`_` 前缀键）
 
-> 注意包名。npm 包名是 `dsh-logicprobe`，没有 scope。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须都写 `dsh-logicprobe`。写错时 dsh 加载器找不到 `node_modules/dsh-logicprobe`，启动会失败。
+任何以 `_` 开头的键（任意层级，如 `_source`、`_verified`、`_extraction_caveats`、`states[0]._note`）都是**注记元数据**：schema 跳过、`modelHash` 排除、报告以 `metadataKeys` 回显。这样来源与验证快照可以跟模型放在同一个文件里，不必再维护一个会漂移的 sidecar，而模型的哈希身份不变。其余键仍然闭合——拼错的 `sttes` 依旧报错。用 `verify model.json --hash-check <hex>` 可回答某个历史哈希是否属于任何已发布规范。
 
 ## UML 建模与审查
 
-`logicprobe_uml` 把一份 LogicModelV1 画成 UML，也可以把手绘的 UML 读回模型，还可以审查建模本身。它有 3 个动作：
+`logicprobe_uml` 把一份 LogicModelV1 画成 UML，也可以把手绘的 UML 读回模型，还可以审查建模本身，或打印解析器接受的标签与注释口径。它有 4 个动作：
 
 - **render**：模型 → 图。Mermaid 支持状态图、活动流程图、时序图；PlantUML 支持状态图与时序图。notation 表达不了的构造会变成 warning，不会被悄悄丢掉。PlantUML 活动图直接拒绝，因为它的语法无法忠实承载带合流或环的图。
 - **parse**：图 → 模型。支持 Mermaid 与 PlantUML 的状态图、活动图，因此手绘的图也能送进 `logicprobe_verify` 验证。两类输入会被拒绝，因为它们无法变成状态机：时序图（迹无法重建机），以及**其它 Mermaid 图族**（`classDiagram`、`erDiagram`、`gantt`、`mindmap`…），返回 `errorCode: "UML_NOT_A_STATE_DIAGRAM"` 并点名该图族。
 - **review**：审查建模。它报告两类问题。结构缺陷包括不可达状态、死端、歧义分支、无出口自环、重复迁移。文档缺口包括缺 narrative、变量无界、状态无可读标注、图与 narrative 标签漂移。它还会做保真度检查：把图重新解析回模型，任何结构性差异都报出来。
+- **explain-labels**：打印解析器接受的标签写法与忽略行口径（`directiveLines`、`acceptedLabelForms`、`renderedForm`、`ignoredLines`、`rules`），不需要给图。手绘图与渲染图对不齐时先看它；命令行对应 `uml-review --explain-labels`。
 
 **结构图是最危险的一类，因为它「能解析」。** PlantUML 的组件图 / 包图 / 类图 / 部署图不声明图类型，解析器会逐行碰上它的关键字。箭头看起来就是迁移，于是 `parse` 会返回一个副产品模型——但现在同时给出 error 级发现 `UML_NOT_A_STATE_DIAGRAM`、`discardedConstructs`（每条无法表达的声明及其行号与原文）、`discardedEdges`（被误读成迁移的箭头数），以及 `verdict: "fail"`。意思是：**这份文件没有被建模，这张图没有被审查。** 不要把那个副产品喂给 `logicprobe_verify` 当作架构审查结论。针对真正依赖图的结构检查（允许依赖矩阵、环、孤立节点）尚未实现，编号 `UML020`+ 已为其保留。
 
@@ -182,7 +125,7 @@ pnpm 会把该版本写进 profile 的 `pnpm-workspace.yaml` 的 `minimumRelease
 
 ## 使用
 
-插件在会话首个模型步骤自动注入能力通知。技能按**领域**拆分,一共四个;`logicprobe` 是总入口,只要有一点「想验证代码/某个说法是否成立」的念头就加载它,它自己的路由表再把相邻领域交出去:
+插件在会话首个模型步骤自动注入能力通知。技能按**领域**拆分;`logicprobe` 是总入口,只要有一点「想验证代码/某个说法是否成立」的念头就加载它,它自己的路由表再把相邻领域交出去:
 
 | 技能 | 领域 | 典型触发 |
 |---|---|---|
@@ -196,20 +139,89 @@ pnpm 会把该版本写进 profile 的 `pnpm-workspace.yaml` 的 `minimumRelease
 
 在 dsh 之外（Claude Code、Cursor、Codex、终端、CI），装的是**仓库**（marketplace / git），随仓库带 `tools/python/logicprobe-engine.py`：只需 Python 3.8+ 标准库。dsh 安装包（npm / bundle）不含它。已有 LogicModelV1 JSON 时直接运行：
 
-- `verify` 跑 S1-S8 / A1-A14 / D1-D4
+- `verify` 跑 S1-S8 / A1-A14 / D1-D4（`--before-model`、`--baseline`、`--hash-spec`、`--hash-check`）
 - `compose` 跑 C1 / C2 组合
 - `export` 生成 UPPAAL、TLA+、PRISM、SPIN 输入
-- `uml-render`、`uml-parse`、`uml-review` 覆盖 UML 前端
+- `uml-render`、`uml-parse`、`uml-review` 覆盖 UML 前端（`uml-review --explain-labels` 打印解析器接受的标签与注释口径）
+- `structure`、`granularity` 审查依赖图与多粒度细化（UML020-UML031）
+- 子命令的权威清单是 `--help`，本文不复制一份
 
-它与 dsh 工具逐字节一致，对照见 `tests/python/run.mjs`。模型只有抽取出的状态表时，填充模板 `tools/python/verification-harness.py`。数据模型验证使用 `tools/python/data-model-harness.py`。Python 不可用（例如离线开发机）时，对应 guide 提供手动验证模式。
+凡引擎实现的子命令，其报告与 dsh 工具逐字节一致，对照见 `tests/python/run.mjs`。模型只有抽取出的状态表时，填充模板 `tools/python/verification-harness.py`。**数据模型验证没有镜像子命令**：非 dsh 宿主用 `tools/python/data-model-harness.py`，或对应 guide 的手动验证模式；并发声称扫描同理（它只做分流）。Python 不可用（例如离线开发机）时，对应 guide 提供手动验证模式。
 
 示例模型见 [`examples/`](examples/README.md)：订单状态机 before/after、电商数据模型、User 字段迁移。
 
-## Codex CLI
+## 安装
 
-本插件同样支持 OpenAI Codex CLI。技能遵循 Agent Skills 标准，两个平台行为一致。
+### Claude Code（推荐）
 
-### Codex 安装
+在 **Claude Code** 的 `~/.claude/settings.json` 中添加 marketplace：
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "logicprobe": {
+      "source": { "source": "github", "repo": "AmethystLuna/logicprobe" }
+    }
+  }
+}
+```
+
+然后通过 CLI 安装：
+
+```bash
+claude plugin install logicprobe@logicprobe
+```
+
+### Claude Code 手动安装
+
+```bash
+git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/logicprobe
+```
+
+然后在 `~/.claude/settings.json` 中启用：
+
+```json
+{
+  "enabledPlugins": {
+    "logicprobe@dev": true
+  }
+}
+```
+
+### DeepSeek Harness (dsh)
+
+原生 dsh 支持以 cordis 插件 bundle 的形式提供，位于**仓库根**，由根 `package.json` 的 `dsh.bundle` 声明。
+
+这个 bundle 做三件事：
+
+1. **注册技能。** 技能遵循 Agent Skills 开放标准，由 dsh 的 `skill-filesystem` provider 原样发现，不需要额外代码。
+2. **注入门禁文本。** 每个会话的第一个模型步骤会收到 claim 验证门禁（主动建议）。这是 Claude `SessionStart` hook 在 dsh 上的对应物。
+3. **注册原生工具与上下文。** 工具挂在 `ctx.tools` 上，另有一条策略感知上下文 `logicprobe:mode`（`ctx.systemPrompt`），以及模型可见目录条目（`cordis_inspect`）。
+
+```bash
+# 从 npm 安装（包名 dsh-logicprobe）
+dsh plugin --profile web add dsh-logicprobe
+# 或从 GitHub 源码安装
+dsh plugin --profile web add "github:AmethystLuna/logicprobe"
+# 未全局安装 dsh 时可用 npx
+npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-logicprobe
+```
+
+装完重启 profile。运行 `dsh --profile web --dump-config` 应看到 `id: logicprobe` 且 `enabled: true`。更多方式（纯技能拷贝、项目级等）见 [`.dsh/INSTALL.md`](.dsh/INSTALL.md)。
+
+pnpm 11 有一个发布年龄闸门。它挡住发布不满一天的新版本（`minimumReleaseAge`，默认 1440 分钟），而且默认是非严格模式，所以裸名安装会**静默装到上一个版本**，profile 看起来像这次发版没发生。发版后约 24 小时内要装最新版，请带上版本号：
+
+```bash
+dsh plugin --profile web add dsh-logicprobe@<version>
+```
+
+pnpm 会把该版本写进 profile 的 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 条目。那是它官方的豁免方式。
+
+> 注意包名。npm 包名是 `dsh-logicprobe`，没有 scope。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须都写 `dsh-logicprobe`。写错时 dsh 加载器找不到 `node_modules/dsh-logicprobe`，启动会失败。
+
+### Codex CLI
+
+本插件同样支持 OpenAI Codex CLI。技能遵循 Agent Skills 标准，两个平台行为一致。
 
 ```bash
 # 添加 marketplace
@@ -227,12 +239,10 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.codex/plugins/logicp
 
 技能通过 `$logicprobe` 调用，或由 Codex 根据任务上下文自动选择。
 
-## Cursor
+### Cursor
 
 Cursor 2.5+ 内置插件支持。
 
-### Cursor 安装
-
 ```bash
 # 克隆到 Cursor 插件目录
 git clone https://github.com/AmethystLuna/logicprobe.git ~/.cursor/plugins/logicprobe
@@ -240,12 +250,10 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.cursor/plugins/logic
 
 或通过 Cursor 插件市场 UI 安装：`/add-plugin AmethystLuna/logicprobe`
 
-## Kimi CLI
+### Kimi CLI
 
 Kimi CLI 自动从 `.claude/skills/` 路径发现技能。`.kimi-plugin/plugin.json` 清单向 Kimi 插件管理器注册本插件。
 
-### Kimi 安装
-
 ```bash
 # 通过 Kimi 插件管理器
 /plugins install https://github.com/AmethystLuna/logicprobe.git
@@ -256,7 +264,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.kimi/plugins/logicpr
 
 技能通过 `/skill:logicprobe` 调用。
 
-## OpenCode
+### OpenCode
 
 技能自动从 `.claude/skills/` 和 `.codex/skills/` 路径发现。在 `opencode.json` 中添加：
 
@@ -268,7 +276,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.kimi/plugins/logicpr
 
 或通过 `skop` 安装（消费 Claude marketplace 清单）。详见 `.opencode/INSTALL.md`。
 
-## ZCode (Z.AI)
+### ZCode (Z.AI)
 
 ZCode 3.0+ 遵循 Agent Skills 标准。它没有插件市场，手动把技能复制过去：
 

package/lib/compose-tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runCompositionVerification } from './engine.js';
+import { renderReportText } from './report-view.js';
 export const LOGICPROBE_COMPOSE_TOOL_NAME = 'logicprobe_compose_verify';
 /**
  * DSH tool wrapping multi-machine composition verification:
@@ -22,14 +23,19 @@ export const logicProbeComposeTool = defineTool({
             type: 'integer',
             description: 'Maximum composite states to explore. Default 10000.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured report, which logicprobe_report_diff needs.',
+        },
     },
     output: {
         schema: {
             type: 'json',
             description: 'Composition verification report with C1/C2 findings.',
         },
-        render(_args, value) {
-            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,

package/lib/concurrency-tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runConcurrencyScan } from './concurrency.js';
+import { renderReportText } from './report-view.js';
 export const LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME = 'logicprobe_concurrency_scan';
 /**
  * Model-visible DSH tool that mines design documents/plans for concurrency-related
@@ -16,14 +17,19 @@ export const logicProbeConcurrencyScanTool = defineTool({
             required: true,
             description: 'Document or plan text to scan for concurrency-related claims.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured report, which logicprobe_report_diff needs.',
+        },
     },
     output: {
         schema: {
             type: 'json',
             description: 'Concurrency scan report with findings and summary.',
         },
-        render(_args, value) {
-            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,

package/lib/data-tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runDataVerification, DATA_ENGINE_SCHEMA_VERSION } from './data-engine.js';
+import { renderReportText } from './report-view.js';
 export const LOGICPROBE_DATAMODEL_VERIFY_TOOL_NAME = 'logicprobe_datamodel_verify';
 /**
  * Model-visible DSH tool wrapping the bundled data-model verification engine.
@@ -36,14 +37,19 @@ export const logicProbeDataModelVerifyTool = defineTool({
             type: 'json',
             description: 'Optional backup/restore pairs for DA7 rollback symmetry.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured report, which logicprobe_report_diff needs.',
+        },
     },
     output: {
         schema: {
             type: 'json',
             description: 'logicprobe-datamodel verification report with summary and per-check findings.',
         },
-        render(_args, value) {
-            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,