dsh-logicprobe 1.1.0 → 1.3.0

package/README.en-US.md

@@ -63,6 +63,15 @@ Every report separates "the tool ran" from "the review passed":
 
 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`.
 
+**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:
+
+- 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.
+
+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.
+
 ### 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.
@@ -71,12 +80,12 @@ Any key starting with `_` — at any level: `_source`, `_verified`, `_extraction
 
 `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.
+- **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. The view follows the question, not the machine, so no tool picks it for you: declare the purpose with `intent` (`present` / `verify` / `fidelity`) and a pairing that cannot serve it is refused before any work (`UML_INTENT_UNSERVABLE`, `UML_VIEW_UNREPRESENTABLE`, `UML_INTENT_MISMATCH`). Omit `intent` and nothing changes.
 - **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.
+**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) belong to `logicprobe_structure_verify`, under Architecture and Dependency Review below.
 
 Fidelity is the core of the feature. Generated diagrams carry `logicprobe:` comment directives for the initial state, the terminal states, aliases and variable kinds. Mermaid and PlantUML ignore those lines; the parser reads them. That is what makes the diagram-versus-model comparison exact.
 
@@ -118,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 |
 |---|---|---|
@@ -132,12 +141,14 @@ 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-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.
 
@@ -186,7 +197,7 @@ Native dsh support ships as a cordis plugin bundle at the repository root, decla
 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.
+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

package/README.md

@@ -61,6 +61,15 @@ logicprobe 核验声称与实物是否一致。事实类对着源码查。行为
 
 只看 `ok` 会把「有死锁」的模型读成通过——判据是 `verdict`。非 DSH 的 Python CLI 退出码跟随 verdict：`pass`/`pass_with_findings` → `0`，`fail` 或拒绝 → `2`。
 
+**工具打印的是报告正文，不是 JSON。** 结构化报告本身没有变（`schema`/`verdict`/`hashes`/检查项 id/`code`/`evidence`/`path` 都在），变的只是给模型看的那份文本：
+
+- 通过的检查只出现在 `CHECKS` 清单行里，不再展开正文（通过的检查没有可行动内容）；
+- 同一个事实被多个检查各报一遍时（例如 `S5` 与 `A1` 报同一批 `(state, event)` 对），只在先出现的检查里列出，后出现的检查写明「与上面重复」，不再重印；
+- 同一检查内逐字相同的发现折叠成一行并标注 `(xN)`；
+- 只有 `error` 级发现内联 `evidence`，`warning` 级不内联——那是机器字段，不是阅读材料。
+
+需要结构化报告本体时传 `reportView: "full"`（例如要把它交给 `logicprobe_report_diff`，它按 `check + code + evidence` 匹配身份，正文替代不了对象）。非 dsh 宿主走 CLI，它直接打印报告 JSON：那份正文是 dsh 工具的呈现层。
+
 ### 模型自带的归档记录（`_` 前缀键）
 
 任何以 `_` 开头的键（任意层级，如 `_source`、`_verified`、`_extraction_caveats`、`states[0]._note`）都是**注记元数据**：schema 跳过、`modelHash` 排除、报告以 `metadataKeys` 回显。这样来源与验证快照可以跟模型放在同一个文件里，不必再维护一个会漂移的 sidecar，而模型的哈希身份不变。其余键仍然闭合——拼错的 `sttes` 依旧报错。用 `verify model.json --hash-check <hex>` 可回答某个历史哈希是否属于任何已发布规范。
@@ -69,12 +78,12 @@ logicprobe 核验声称与实物是否一致。事实类对着源码查。行为
 
 `logicprobe_uml` 把一份 LogicModelV1 画成 UML，也可以把手绘的 UML 读回模型，还可以审查建模本身，或打印解析器接受的标签与注释口径。它有 4 个动作：
 
-- **render**：模型 → 图。Mermaid 支持状态图、活动流程图、时序图；PlantUML 支持状态图与时序图。notation 表达不了的构造会变成 warning，不会被悄悄丢掉。PlantUML 活动图直接拒绝，因为它的语法无法忠实承载带合流或环的图。
+- **render**：模型 → 图。Mermaid 支持状态图、活动流程图、时序图；PlantUML 支持状态图与时序图。notation 表达不了的构造会变成 warning，不会被悄悄丢掉。PlantUML 活动图直接拒绝，因为它的语法无法忠实承载带合流或环的图。视图由问题决定、不由模型决定，所以工具不替你选：用 `intent`（`present`/`verify`/`fidelity`）声明产物用途，服务不了的组合在开工之前就拒（`UML_INTENT_UNSERVABLE`、`UML_VIEW_UNREPRESENTABLE`、`UML_INTENT_MISMATCH`）；不给 `intent` 则行为与从前完全一致。
 - **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`+ 已为其保留。
+**结构图是最危险的一类，因为它「能解析」。** PlantUML 的组件图 / 包图 / 类图 / 部署图不声明图类型，解析器会逐行碰上它的关键字。箭头看起来就是迁移，于是 `parse` 会返回一个副产品模型——但现在同时给出 error 级发现 `UML_NOT_A_STATE_DIAGRAM`、`discardedConstructs`（每条无法表达的声明及其行号与原文）、`discardedEdges`（被误读成迁移的箭头数），以及 `verdict: "fail"`。意思是：**这份文件没有被建模，这张图没有被审查。** 不要把那个副产品喂给 `logicprobe_verify` 当作架构审查结论。真正的依赖图检查（允许依赖矩阵、环、孤立节点）由 `logicprobe_structure_verify` 承担，见下方「架构与依赖审查」。
 
 保真度是这套功能的核心。生成的图带有 `logicprobe:` 注释指令（init、终态、别名、变量类型），Mermaid 与 PlantUML 会忽略它们，而解析器会读取它们。因此「图 ↔ 模型」的比较是精确的。
 
@@ -116,7 +125,7 @@ logicprobe 核验声称与实物是否一致。事实类对着源码查。行为
 
 ## 使用
 
-插件在会话首个模型步骤自动注入能力通知。技能按**领域**拆分,一共四个;`logicprobe` 是总入口,只要有一点「想验证代码/某个说法是否成立」的念头就加载它,它自己的路由表再把相邻领域交出去:
+插件在会话首个模型步骤自动注入能力通知。技能按**领域**拆分;`logicprobe` 是总入口,只要有一点「想验证代码/某个说法是否成立」的念头就加载它,它自己的路由表再把相邻领域交出去:
 
 | 技能 | 领域 | 典型触发 |
 |---|---|---|
@@ -130,12 +139,14 @@ logicprobe 核验声称与实物是否一致。事实类对着源码查。行为
 
 在 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-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 字段迁移。
 
@@ -184,7 +195,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/l
 这个 bundle 做三件事：
 
 1. **注册技能。** 技能遵循 Agent Skills 开放标准，由 dsh 的 `skill-filesystem` provider 原样发现，不需要额外代码。
-2. **注入门禁文本。** 每个会话的第一个模型步骤会收到 claim 验证门禁（1% Rule / Red Flags / 主动建议）。这是 Claude `SessionStart` hook 在 dsh 上的对应物。
+2. **注入门禁文本。** 每个会话的第一个模型步骤会收到 claim 验证门禁（主动建议）。这是 Claude `SessionStart` hook 在 dsh 上的对应物。
 3. **注册原生工具与上下文。** 工具挂在 `ctx.tools` 上，另有一条策略感知上下文 `logicprobe:mode`（`ctx.systemPrompt`），以及模型可见目录条目（`cordis_inspect`）。
 
 ```bash

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,