dsh-logicprobe 0.7.0 → 0.8.0

package/README.en-US.md

@@ -4,23 +4,24 @@
 
 [![HOL Guard Scanner](https://img.shields.io/badge/HOL%20Guard-passing-00a67e)](https://github.com/hashgraph-online/hol-guard)
 
-Design documents are not truth — code is. A claim-verification skill that checks every verifiable claim in design docs, architecture specs, and refactoring plans against the actual codebase — and escalates to executable-model verification for behavioral claims.
+Design documents are not truth. Code is. This skill checks every verifiable claim in a design document, an architecture spec, or a refactoring plan against the real codebase. For behavioral claims it escalates to executable-model verification.
 
-**Cross-platform** — works with Claude Code, Codex CLI, Cursor, Kimi CLI, OpenCode, and ZCode. Built on the [Agent Skills](https://agentskills.io) open standard.
+**Cross-platform**: works with Claude Code, Codex CLI, Cursor, Kimi CLI, OpenCode, and ZCode. Built on the [Agent Skills](https://agentskills.io) open standard.
 
 ## What It Does
 
 | Phase | What |
 |-------|------|
-| Phase 1-2 | Enumerate every verifiable claim (API names, file paths, enum values, counts, mechanism feasibility) → verify each against the codebase with evidence |
-| Phase 2a | **8 structural checks (S1-S8)** on extracted state-machine models: S1 reachability, S2 deadlock, S3 liveness, S4 determinism, S5 event completeness, S6 guard completeness, S7 invariant validity, S8 monotonic variables |
-| Phase 2b | **14 adversarial probes (A1-A14)**: unexpected events, race interleaving, order permutation, pair symmetry (lock/unlock, incl. implicit onEntry/onExit pairing), boundary blast, resource injection, minimal counter-example, idempotent replay, leads-to, sequence, atomicity, budget (A12 worst-case path cost, incl. positive-cost-cycle detection), probability reachability (A13, P(hit) meets a lower bound), deadline (A14, maxTicks + tickEvents) |
-| Refactoring | Before/after model comparison — behavioral preservation, invariant continuity, deadlock regression, complexity claims |
-| Data models | DataModelV1 verification — DS/DA/DD checks, migration coverage, copy consistency, before/after breaking-change regression |
-| Concurrency risk mining | Scans documents/plans for concurrency safety claims (thread-safe, lock-free, race condition, interrupt safety, etc.) and flags them for dedicated verification |
-| Output | Structured findings with exact file:line evidence, severity classification, correction direction — never inline fixes; the report carries `coverageNotes` (timing/preemption/hybrid/probability vocabulary routed to UPPAAL / TSan / CBMC / TLA+ / SpaceEx / PRISM, see `skills/logicprobe/references/gap-routing-guide.md`), and the model may carry a natural-language `narrative` (state/event/scenario annotations) echoed verbatim in the report |
+| Phase 1-2 | Enumerate every verifiable claim: API names, file paths, enum values, counts, mechanism feasibility. Verify each one against the codebase with evidence. |
+| Phase 2a | **8 structural checks (S1-S8)** on the extracted state machine: S1 reachability, S2 deadlock, S3 liveness, S4 determinism, S5 event completeness, S6 guard completeness, S7 invariant validity, S8 monotonic variables. |
+| Phase 2b | **14 adversarial probes (A1-A14)**: unexpected events, race interleaving, order permutation, pair symmetry (lock/unlock, incl. implicit onEntry/onExit pairing), boundary blast, resource injection, minimal counter-example, idempotent replay, leads-to, sequence, atomicity, budget (A12 worst-case path cost, incl. positive-cost-cycle detection), probability reachability (A13), deadline (A14). |
+| Refactoring | Before/after model comparison: behavioral preservation, invariant continuity, deadlock regression, complexity claims. |
+| Data models | DataModelV1 verification (DS/DA/DD): migration coverage, copy consistency, before/after breaking-change regression. |
+| UML modelling and review | Draw a code flow as UML, then review the modelling itself: structural defects, documentation gaps, diagram-versus-model fidelity. |
+| Concurrency risk mining | Scan documents and plans for concurrency safety claims (thread-safe, lock-free, race condition, interrupt safety) and flag them for dedicated verification. |
+| Output | Structured findings with exact file:line evidence, severity, and correction direction. Never an inline fix. The report carries `coverageNotes`, which routes timing, preemption, hybrid-control and probability vocabulary to external tools (UPPAAL, TSan, CBMC, TLA+, SpaceEx, PRISM). See `skills/logicprobe/references/gap-routing-guide.md`. A model may also carry a natural-language `narrative` (state, event and scenario annotations), which the report echoes verbatim. |
 
-The model is always shown as a transition table and **confirmed with the user before running** — extraction errors are the dominant failure mode.
+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
 
@@ -38,7 +39,7 @@ Add the marketplace to **Claude Code**'s `~/.claude/settings.json`:
 }
 ```
 
-Then install from CLI:
+Then install from the CLI:
 
 ```bash
 claude plugin install logicprobe@logicprobe
@@ -50,7 +51,7 @@ claude plugin install logicprobe@logicprobe
 git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/logicprobe
 ```
 
-Then enable in `~/.claude/settings.json`:
+Then enable it in `~/.claude/settings.json`:
 
 ```json
 {
@@ -62,18 +63,26 @@ Then enable in `~/.claude/settings.json`:
 
 ## DeepSeek Harness (dsh)
 
-Native dsh support ships as a cordis plugin bundle at the repository root (the root `package.json` declares `dsh.bundle`):
+Native dsh support ships as a cordis plugin bundle at the repository root, declared by `dsh.bundle` in the root `package.json`.
 
-- The skill is discovered as-is by dsh's `skill-filesystem` provider (Agent Skills open standard) — zero code.
-- The bundle injects the claim-verification gate (1% Rule / Red Flags / proactive suggestion) into the first model step of every agent session — the dsh-native counterpart of the Claude `SessionStart` hook. It also registers a model-visible catalog entry (`cordis_inspect`), a native `logicprobe_verify` tool (`ctx.tools`), and a policy-aware `logicprobe:mode` context (`ctx.systemPrompt`).
-- `logicprobe_datamodel_verify` adds data-model verification: DataModelV1, migration coverage, copy consistency, and DD1-DD4 before/after data regression.
-- `logicprobe_concurrency_scan` mines documents/plans for concurrency risk claims (thread-safe, lock-free, race condition, mutex, etc.), flags them for dedicated verification, and attaches tool-routing `suggestions` to absolute claims.
-- `logicprobe_verify` also supports transition `cost` (default 1) with `budget` invariants (A12 worst-case path-cost check incl. positive-cost-cycle detection), and transition `weight` (default 1) with `probability` invariants (A13 probability reachability).
-- State `onEntry`/`onExit` actions are treated by A4 Pair Symmetry as implicit acquire/release; `maxTicks` + `tickEvents` deadlines (A14); report `coverageNotes` routes timing/preemption/hybrid/probability vocabulary to dedicated tools (UPPAAL, TSan/CBMC/TLA+, SpaceEx, PRISM, ...).
-- The engine runs **22 checks (S1-S8 structural + A1-A14 adversarial)**; the model may carry a natural-language `narrative` (state/event/scenario annotations) echoed verbatim in the report.
-- `logicprobe_compose_verify`: composition verification of two or more state machines (rendezvous handshake semantics) reporting C1 composition deadlock / C2 rendezvous never fires.
-- `logicprobe_export`: exports a LogicModelV1 as native input for external tools — UPPAAL (XML `.xta` + queries), TLA+ (TLC module), PRISM (DTMC `.pm` + `.pctl`), SPIN (Promela + ltl) — matching the dimensions covered by `coverageNotes`/gap-routing; exports follow each tool's official syntax so the generated files can be handed straight to the checker (SPIN is verified end-to-end for real).
-- Together with the embedded-workbench bundle's Plan Verification Gate, this closes the claim-verification loop in dsh.
+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 tools:
+
+| Tool | What it does |
+|------|------|
+| `logicprobe_verify` | State-machine verification: S1-S8 structural checks plus A1-A14 adversarial probes. Pass `beforeModel` and `stateMapping` to add the D1-D4 before/after regression. |
+| `logicprobe_datamodel_verify` | Data-model verification: DataModelV1, migration coverage, copy consistency, DD1-DD4 data regression. |
+| `logicprobe_concurrency_scan` | Mines concurrency risk claims (thread-safe, lock-free, race condition, mutex) and flags them for dedicated verification. |
+| `logicprobe_compose_verify` | Composition verification of two or more machines (rendezvous handshake semantics): C1 composition deadlock, C2 rendezvous never fires. |
+| `logicprobe_export` | Exports external-tool input: UPPAAL (`.xta` + queries), TLA+ (TLC module), PRISM (DTMC `.pm` + `.pctl`), SPIN (Promela + ltl). |
+| `logicprobe_uml` | Models a code flow as UML and reviews the modelling. See "UML modelling and review" below. |
+
+Transition `cost` (default 1) plus a `budget` invariant makes A12 check the worst-case path cost. A reachable cycle with positive cost counts as unbounded. Transition `weight` (default 1) plus a `probability` invariant makes A13 compute probability reachability. State `onEntry`/`onExit` actions enter A4 pair symmetry automatically, and `maxTicks` plus `tickEvents` drive the A14 deadline check.
 
 Install (native bundle, recommended):
 
@@ -86,28 +95,48 @@ dsh plugin --profile web add "github:AmethystLuna/logicprobe"
 npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-logicprobe
 ```
 
-Restart the profile, then run `dsh --profile web --dump-config`: the `id: logicprobe` row must appear with `enabled: true`. More options (plain skill copy, project-level, ...) are in [`.dsh/INSTALL.md`](.dsh/INSTALL.md).
+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).
+
+> 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.
+
+## UML Modelling and Review
 
-> DSH install note: the package name is `dsh-logicprobe`. In the web profile's `package.json`, both the dependency key and the `dsh.profile.bundles` entry must use the same name; a mismatch causes the dsh loader to fail with `ERR_MODULE_NOT_FOUND`.
+`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:
+
+- **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`. A sequence diagram is a trace, not a machine, so parsing one is refused.
+- **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.
+
+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.
+
+The review covers the modelling, never the behaviour. Every finding names the engine check that settles the behavioural half. The full list (`UML001`-`UML019`), the directive format, a worked example and the limits of each view are in [`skills/logicprobe/references/uml-modeling-guide.md`](skills/logicprobe/references/uml-modeling-guide.md).
 
 ## Usage
 
-The plugin auto-injects a capability notification into the first model step. The skill activates when its `Use when` description matches your task:
+The plugin injects a capability notification into the first model step. The skill activates when its `Use when` description matches your task:
 
-- **Design doc / plan review** — "Review this design document" → claim enumeration and codebase verification
-- **Behavioral questions** — "could this state machine deadlock", "is this retry limit safe", "check this timing for bugs" → the skill is proactively suggested (not auto-loaded) as an optional verification pass
-- **Refactoring plans** — the pipeline compares before/after models to flag undocumented behavioral changes
-- **Data model / migration review** — "is this migration non-breaking", "does this copy cover all required fields" → use the `logicprobe-datamodel` skill
+- **Design doc or plan review** — "Review this design document" → claim enumeration and codebase verification
+- **Behavioral questions** — "could this state machine deadlock", "is this retry limit safe" → the skill is proactively suggested (not auto-loaded) as an optional verification pass
+- **Refactoring plans** — the pipeline compares before/after models and flags undocumented behavioral changes
+- **Data model or migration review** — "is this migration non-breaking" → use the `logicprobe-datamodel` skill
+- **Code-flow modelling** — "draw this state machine", "is this UML diagram right" → use `logicprobe_uml` to draw the diagram and review the modelling, then run `logicprobe_verify` for the behaviour
 
-The skill auto-classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED) from plan features in Phase 0, and appends a `## Plan Verification` summary block as the audit trail.
+The skill classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED) from plan features in Phase 0, and appends a `## Plan Verification` summary block as the audit trail.
 
-In DSH, prefer the native `logicprobe_verify` tool for state machines and `logicprobe_datamodel_verify` for data models (see the schema references under each skill). Python remains optional for non-DSH hosts: when a LogicModelV1 JSON already exists, run the standalone engine `skills/logicprobe/references/logicprobe-engine.py` (`verify` runs S1-S8/A1-A14/D1-D4, `compose` runs C1/C2 composition, `export` emits UPPAAL/TLA+/PRISM/SPIN input — byte-identical to the dsh tools, cross-checked by tests/python/run.mjs); when the model only exists as extracted tables, fill in `skills/logicprobe/references/verification-harness.py`; data-model checks use `skills/logicprobe-datamodel/references/data-model-harness.py`. When Python is unavailable, the corresponding guide provides a manual verification mode.
+Python is optional. When a LogicModelV1 JSON already exists, run the standalone engine at `skills/logicprobe/references/logicprobe-engine.py`:
 
-Sample models are available under [`examples/`](examples/README.md): order state-machine before/after, e-commerce data model, and User field migration.
+- `verify` runs S1-S8 / A1-A14 / D1-D4
+- `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
+
+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 `skills/logicprobe/references/verification-harness.py`. Data-model checks use `skills/logicprobe-datamodel/references/data-model-harness.py`. 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
 
-This plugin also supports OpenAI Codex CLI. Skills follow the Agent Skills standard and work identically across both platforms.
+This plugin also supports OpenAI Codex CLI. Skills follow the Agent Skills standard and work identically on both platforms.
 
 ### Codex install
 
@@ -125,7 +154,7 @@ Or manually:
 git clone https://github.com/AmethystLuna/logicprobe.git ~/.codex/plugins/logicprobe
 ```
 
-Skills are invoked with `$logicprobe` or auto-selected by Codex based on task context.
+Skills are invoked with `$logicprobe`, or selected automatically by Codex from the task context.
 
 ## Cursor
 
@@ -158,7 +187,7 @@ Skills are invoked with `/skill:logicprobe`.
 
 ## OpenCode
 
-Skills are auto-discovered from `.claude/skills/` and `.codex/skills/` paths. Add to your `opencode.json`:
+Skills are auto-discovered from `.claude/skills/` and `.codex/skills/` paths. Add this to your `opencode.json`:
 
 ```json
 {
@@ -166,28 +195,29 @@ Skills are auto-discovered from `.claude/skills/` and `.codex/skills/` paths. Ad
 }
 ```
 
-Or install via `skop` which consumes the Claude marketplace manifest. See `.opencode/INSTALL.md` for detailed instructions.
+Or install through `skop`, which consumes the Claude marketplace manifest. See `.opencode/INSTALL.md`.
 
 ## ZCode (Z.AI)
 
-ZCode 3.0+ follows the Agent Skills standard. No plugin marketplace — manually copy skills to `.zcode/skills/`:
+ZCode 3.0+ follows the Agent Skills standard. It has no plugin marketplace, so copy the skills yourself:
 
 ```bash
 git clone https://github.com/AmethystLuna/logicprobe.git
 cp -r logicprobe/skills/* .zcode/skills/
 ```
 
-Skills are invoked with `$logicprobe`. See `.zcode/INSTALL.md` for details.
+Skills are invoked with `$logicprobe`. See `.zcode/INSTALL.md`.
 
 ## Requirements
 
-- Claude Code v2.1+ / Codex CLI latest / Cursor 2.5+ / Kimi CLI latest / OpenCode latest / ZCode 3.0+
-- DeepSeek Harness (dsh): dev preview — verified on mainline 2026-08-14 (gate bundle loaded and injected in-session)
-- Python 3.6+ optional (only for the automated harness; manual fallback mode requires none)
+- Host: Claude Code v2.1+ / Codex CLI latest / Cursor 2.5+ / Kimi CLI latest / OpenCode latest / ZCode 3.0+
+- DeepSeek Harness (dsh): dev preview, declared support for `>= 0.1.0-rc.7`. The latest round measured install, mount, boot and uninstall on 0.2.1-alpha.1. The earlier round measured 0.1.5-rc.2 through 0.2.0-rc.2. Per-release evidence is in [DSH-COMPATIBILITY.md](DSH-COMPATIBILITY.md).
+- The Web Plugins-page "Gate injection" switch requires **dsh ≥ 0.1.7-alpha.1**, because its settings service must be able to project live fields. On older dsh the plugin still loads and still injects. The switch is simply absent, with no error.
+- Python 3.6+ optional, needed only by the automated tools. The manual fallback mode needs no dependencies.
 
 ## Configuration
 
-In DeepSeek Harness, the bundle registers the `logicprobe_verify` tool (through `ctx.tools`) and a policy-aware `logicprobe:mode` context (through `ctx.systemPrompt`). The bundle accepts a small configuration object:
+In DeepSeek Harness the bundle accepts a small configuration object:
 
 | Key | Type | Default | Description |
 |---|---|---|---|
@@ -195,7 +225,9 @@ In DeepSeek Harness, the bundle registers the `logicprobe_verify` tool (through
 | `gateContent` | string | built-in gate text | Override the text injected into the first model step. |
 | `interaction` | `ask` \| `auto` \| `follow-approval` | `follow-approval` | Model-confirmation policy. `follow-approval` resolves to `auto` when the session approval policy is `never`. |
 
-To change it, override the row by id in your profile's `cordis.patch.yml`:
+The switch is editable live in the dsh Web GUI: sidebar **Plugins** → this plugin's card → "Gate injection". It takes effect without a profile restart, and it controls only the injected text. Turning it off leaves the skills and the verification tools registered. The same card also carries a coarser row switch: turning that one off unmounts the whole row, so the skills, the tools and this switch all disappear. Persistent overrides still go through the profile patch below.
+
+To override the row by id, edit your profile's `cordis.patch.yml`:
 
 ```yaml
 - insert:
@@ -210,24 +242,24 @@ To change it, override the row by id in your profile's `cordis.patch.yml`:
 
 ## Uninstall
 
-- If you installed through the DSH plugin manager, remove the `logicprobe` plugin from the target profile using the same manager you used to install it.
-- If you copied `skills/*` manually, delete the copied skill directories from `~/.agents/skills/` or the project `.dsh/skills/`.
+- If you installed through the DSH plugin manager, remove the `logicprobe` plugin from the target profile with the same manager.
+- If you copied `skills/*` manually, delete the copied skill directories from `~/.agents/skills/` or the project's `.dsh/skills/`.
 - If you added the bundle as a `cordis.patch.yml` row, remove the row with `id: logicprobe` from the profile patch and restart DSH.
 
 ## Permissions & Data
 
 - The plugin runtime reads only the `skills/` directory shipped inside the package, in order to register skills through DSH's standard filesystem skill provider.
 - It injects the configured gate text into the first model step of a session.
-- It does not read credentials, open network connections, or access user data outside the DSH session context.
+- It does not read credentials, open network connections, or touch user data outside the DSH session context.
 - When the skill is actually used, the model may read project files as directed by the user, just like any other coding skill.
 
 ## Troubleshooting
 
-- Skill not visible in DSH: confirm you are on a DSH version that supports `ctx.skills`/Agent Skills discovery, and restart the profile after install.
-- Gate not injected: check that `enabled` is not `false` and that the row id `logicprobe` is present in the active profile patch.
-- `logicprobe_verify` not visible: check `cordis_inspect_query` status for `toolRegistered: true`, and confirm the DSH profile resolved the `@deepseek-ai/dsh-tools` peer dependency.
-- Plugin manager rejects installation: make sure `@deepseek-ai/*` packages are declared as `peerDependencies`, not regular `dependencies`.
-- After manual copy, DSH still doesn't see the skill: use the native bundle install (`dsh plugin add "github:AmethystLuna/logicprobe"`) instead of copying.
+- Skill not visible in DSH: confirm the DSH version supports `ctx.skills` and Agent Skills discovery, then restart the profile.
+- Gate not injected: check that `enabled` is not `false`, and that the row id `logicprobe` is present in the active profile patch.
+- `logicprobe_verify` not visible: check `cordis_inspect_query` status for `toolRegistered: true`, and confirm the profile resolved the `@deepseek-ai/dsh-tools` peer dependency.
+- Plugin manager rejects the installation: make sure the `@deepseek-ai/*` packages are declared as `peerDependencies`, not as regular `dependencies`.
+- After a manual copy DSH still does not see the skill: install the native bundle instead (`dsh plugin add "github:AmethystLuna/logicprobe"`).
 
 ## Development
 
@@ -239,10 +271,12 @@ npm run build
 
 Test chain:
 
-- `npm run test:engine` — state-machine / data-model engine regression (`tests/engine`, `tests/data-engine`, `tests/concurrency`, `tests/apply-smoke`, `tests/exporters`, `tests/external`) plus byte-for-byte Python parity (`tests/python/run.mjs`: the same fixtures are compared between the TS engine and `skills/logicprobe/references/logicprobe-engine.py` across reports / composition / exporter output; auto-SKIP when Python is absent)
-- `npm run test:full` — `tests/full-suite.mjs` combined end-to-end suite
-- `npm run test:python` — Python parity only (build + `tests/python/run.mjs`)
-- Trigger tests are under `tests/skill-triggering/`: `bash tests/skill-triggering/run-all.sh`
+| Command | What it covers |
+|---|---|
+| `npm run test:engine` | State-machine and data-model engine regression (`tests/engine`, `tests/data-engine`, `tests/concurrency`, `tests/uml`, `tests/apply-smoke`, `tests/dsh-client-half`, `tests/exporters`, `tests/external`), plus byte-for-byte Python parity. The parity script `tests/python/run.mjs` compares the same fixtures between the TS engine and `skills/logicprobe/references/logicprobe-engine.py` across reports, composition and exporter output. It SKIPs when Python is absent. |
+| `npm run test:full` | `tests/full-suite.mjs` combined end-to-end suite |
+| `npm run test:python` | Python parity only (build + `tests/python/run.mjs`) |
+| `bash tests/skill-triggering/run-all.sh` | Trigger tests under `tests/skill-triggering/` |
 
 ## License & Security
 

package/README.md

@@ -2,23 +2,24 @@
 
 <p align="center"><a href="README.en-US.md">English</a> · <strong>中文</strong></p>
 
-文档不是事实——代码才是。一个声称核查技能：逐条核验设计文档、架构规格、重构计划中每一个可验证的声称与代码库实际是否一致；遇到行为类声称时升级为可执行模型验证。
+文档不是事实，代码才是。本技能逐条核验设计文档、架构规格与重构计划里的可验证声称，再把每一条对照到代码库的真实实现。遇到行为类声称时，它升级为可执行模型验证。
 
-**跨平台** — 支持 Claude Code、Codex CLI、Cursor、Kimi CLI、OpenCode、ZCode。基于 [Agent Skills](https://agentskills.io) 开放标准构建。
+**跨平台**：支持 Claude Code、Codex CLI、Cursor、Kimi CLI、OpenCode、ZCode。技能基于 [Agent Skills](https://agentskills.io) 开放标准。
 
 ## 功能
 
 | 阶段 | 内容 |
 |------|------|
-| Phase 1-2 | 枚举每个可验证声称（API 名、文件路径、枚举值、数量、机制可行性）→ 逐条对照代码库给出证据 |
-| Phase 2a | 对提取的状态机模型执行 **8 项结构检查（S1-S8）**：S1 可达性、S2 死锁、S3 活性、S4 确定性、S5 事件完备性、S6 守卫完备性、S7 不变量有效性、S8 单调变量 |
-| Phase 2b | **14 项对抗探针（A1-A14）**：意外事件、竞态交错、顺序置换、配对对称（lock/unlock，含 onEntry/onExit 隐式配对）、边界轰炸、资源注入、最小反例、幂等重放、必达、顺序、原子性、预算（A12 最坏路径代价，含正成本环检测）、概率可达（A13，P(击中) 满足下界）、期限（A14，maxTicks + tickEvents） |
-| 重构模式 | 前后模型对比——行为保持、不变量连续性、死锁回归、复杂度声称 |
-| 数据模型模式 | DataModelV1 数据模型验证——DS/DA/DD 检查，迁移覆盖、copy 一致性、before/after 破坏性变更回归 |
-| 并发风险挖掘 | 扫描文档/计划中的并发安全声称（thread-safe、lock-free、race condition、中断安全等），标记需要专用验证 |
-| 输出 | 结构化发现：精确 file:line 证据、严重性分级、修正方向——绝不在核查中直接改代码；报告含 `coverageNotes`（时序/抢占/混合/概率词汇 → UPPAAL/TSan/CBMC/TLA+/SpaceEx/PRISM 等外部工具路由，见 `skills/logicprobe/references/gap-routing-guide.md`），模型可携带自然语言 `narrative`（状态/事件/场景注释）并被报告原样回显 |
+| Phase 1-2 | 枚举每个可验证声称：API 名、文件路径、枚举值、数量、机制可行性。逐条对照代码库给出证据。 |
+| Phase 2a | 对提取的状态机模型执行 **8 项结构检查（S1-S8）**：S1 可达性、S2 死锁、S3 活性、S4 确定性、S5 事件完备性、S6 守卫完备性、S7 不变量有效性、S8 单调变量。 |
+| Phase 2b | **14 项对抗探针（A1-A14）**：意外事件、竞态交错、顺序置换、配对对称（lock/unlock，含 onEntry/onExit 隐式配对）、边界轰炸、资源注入、最小反例、幂等重放、必达、顺序、原子性、预算（A12 最坏路径代价，含正成本环检测）、概率可达（A13）、期限（A14）。 |
+| 重构模式 | 对比前后模型：行为保持、不变量连续性、死锁回归、复杂度声称。 |
+| 数据模型模式 | 验证 DataModelV1 数据模型（DS/DA/DD）：迁移覆盖、copy 一致性、before/after 破坏性变更回归。 |
+| UML 建模与审查 | 用 UML 画出代码流程，再审查这份建模本身：结构缺陷、文档缺口、图与模型的往返保真度。 |
+| 并发风险挖掘 | 扫描文档与计划中的并发安全声称（thread-safe、lock-free、race condition、中断安全等），标记出来交给专用验证。 |
+| 输出 | 结构化发现：精确 file:line 证据、严重性分级、修正方向。核查过程中绝不直接改代码。报告附带 `coverageNotes`，把时序、抢占、混合控制、概率等词汇路由到外部工具（UPPAAL、TSan、CBMC、TLA+、SpaceEx、PRISM 等），见 `skills/logicprobe/references/gap-routing-guide.md`。模型可携带自然语言 `narrative`（状态、事件、场景注释），报告原样回显。 |
 
-模型永远先以转换表形式展示并**经用户确认后才运行**——模型提取错误是验证的头号失败模式。
+模型永远先以转换表形式展示，**经用户确认后才运行**。模型提取错误是验证的头号失败模式。
 
 ## 安装
 
@@ -60,19 +61,26 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/l
 
 ## DeepSeek Harness (dsh)
 
-原生 dsh 支持以 cordis 插件 bundle 的形式提供，位于**仓库根**（根 `package.json` 声明了 `dsh.bundle`）：
+原生 dsh 支持以 cordis 插件 bundle 的形式提供，位于**仓库根**，由根 `package.json` 的 `dsh.bundle` 声明。
 
-- 技能遵循 Agent Skills 开放标准，被 dsh 的 `skill-filesystem` provider 原样发现——零代码。
-- bundle 将 claim 验证门禁（1% Rule / Red Flags / 主动建议）注入每个 agent 会话的第一个模型步骤——是 Claude `SessionStart` hook 在 dsh 的原生对应物，并注册模型可见目录条目（`cordis_inspect`）、原生工具 `logicprobe_verify`（`ctx.tools`）以及策略感知上下文 `logicprobe:mode`（`ctx.systemPrompt`）。
-- `logicprobe_verify` 支持 `beforeModel` + `stateMapping` 的 BEFORE/AFTER 对比（D1-D4），可直接验证重构/迁移的行为保持、不变量连续性、回归增量和死锁/活性回归。
-- `logicprobe_verify` 还支持：迁移/处理器代价 `cost`（缺省 1）与 `budget` 不变量（A12 最坏路径代价检查，含正成本环检测）、迁移权重 `weight` 与 `probability` 不变量（A13 概率可达）。
-- 状态 `onEntry`/`onExit` 动作（A4 自动纳入配对检查）；`maxTicks`+`tickEvents` 期限（A14）；报告 `coverageNotes`（时序/抢占/混合/概率词汇 → UPPAAL/TSan/CBMC/TLA+/SpaceEx/PRISM 等外部工具路由）。
-- 引擎共运行 **22 项检查（S1-S8 结构 + A1-A14 对抗）**；模型可带自然语言 `narrative`（状态/事件/场景注释），报告原样回显。
-- `logicprobe_compose_verify`：两台及以上状态机组合验证（握手 rendezvous 语义），报 C1 组合死锁 / C2 握手永不触发。
-- `logicprobe_export`：把 LogicModelV1 导出为外部工具原生输入——UPPAAL（XML `.xta` + queries）、TLA+（TLC 模块）、PRISM（DTMC `.pm` + `.pctl`）、SPIN（Promela + ltl）——与 `coverageNotes`/gap-routing 的维度对应；导出严格遵循各工具官方语法，生成文件可直接提交给对应检查器（SPIN 已做真实端到端验证）。
-- `logicprobe_datamodel_verify` 新增数据模型验证：DataModelV1、迁移覆盖、copy 一致性、DD1-DD4 before/after 数据回归。
-- `logicprobe_concurrency_scan` 扫描文档/计划中的并发风险声称（thread-safe、lock-free、race condition、mutex 等），标记需要专用并发验证。
-- 与 embedded-workbench bundle 的 Plan Verification Gate 配合，在 dsh 中闭环了 claim 验证链路。
+这个 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`）。
+
+工具清单：
+
+| 工具 | 作用 |
+|------|------|
+| `logicprobe_verify` | 状态机验证：S1-S8 结构检查 + A1-A14 对抗探针。传 `beforeModel` 与 `stateMapping` 可加做 D1-D4 前后回归。 |
+| `logicprobe_datamodel_verify` | 数据模型验证：DataModelV1、迁移覆盖、copy 一致性、DD1-DD4 数据回归。 |
+| `logicprobe_concurrency_scan` | 扫描并发风险声称（thread-safe、lock-free、race condition、mutex 等），标注需要专用验证。 |
+| `logicprobe_compose_verify` | 两台及以上状态机组合验证（握手 rendezvous 语义）：C1 组合死锁、C2 握手永不触发。 |
+| `logicprobe_export` | 导出外部工具原生输入：UPPAAL（`.xta` + queries）、TLA+（TLC 模块）、PRISM（DTMC `.pm` + `.pctl`）、SPIN（Promela + ltl）。 |
+| `logicprobe_uml` | 用 UML 建模代码流程，并审查这份建模。见下方「UML 建模与审查」。 |
+
+迁移代价用 `cost`（缺省 1），配 `budget` 不变量即由 A12 检查最坏路径代价，正成本环会被判为无界。迁移权重用 `weight`（缺省 1），配 `probability` 不变量即由 A13 计算概率可达。状态上的 `onEntry`/`onExit` 动作由 A4 自动纳入配对检查，`maxTicks` 加 `tickEvents` 由 A14 检查期限。
 
 安装（原生 bundle，推荐）：
 
@@ -85,22 +93,42 @@ dsh plugin --profile web add "github:AmethystLuna/logicprobe"
 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)。
+装完重启 profile。运行 `dsh --profile web --dump-config` 应看到 `id: logicprobe` 且 `enabled: true`。更多方式（纯技能拷贝、项目级等）见 [`.dsh/INSTALL.md`](.dsh/INSTALL.md)。
+
+> 注意包名。npm 包名是 `dsh-logicprobe`，没有 scope。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须都写 `dsh-logicprobe`。写错时 dsh 加载器找不到 `node_modules/dsh-logicprobe`，启动会失败。
+
+## UML 建模与审查
 
-> DSH 安装注意：npm 包名为 `dsh-logicprobe`（无 scope）。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须写 `dsh-logicprobe`；否则 dsh 加载器会因找不到 `node_modules/dsh-logicprobe` 而启动失败。
+`logicprobe_uml` 把一份 LogicModelV1 画成 UML，也可以把手绘的 UML 读回模型，还可以审查建模本身。它有 3 个动作：
+
+- **render**：模型 → 图。Mermaid 支持状态图、活动流程图、时序图；PlantUML 支持状态图与时序图。notation 表达不了的构造会变成 warning，不会被悄悄丢掉。PlantUML 活动图直接拒绝，因为它的语法无法忠实承载带合流或环的图。
+- **parse**：图 → 模型。支持 Mermaid 与 PlantUML 的状态图、活动图，因此手绘的图也能送进 `logicprobe_verify` 验证。时序图是迹而不是机，解析会被拒绝。
+- **review**：审查建模。它报告两类问题。结构缺陷包括不可达状态、死端、歧义分支、无出口自环、重复迁移。文档缺口包括缺 narrative、变量无界、状态无可读标注、图与 narrative 标签漂移。它还会做保真度检查：把图重新解析回模型，任何结构性差异都报出来。
+
+保真度是这套功能的核心。生成的图带有 `logicprobe:` 注释指令（init、终态、别名、变量类型），Mermaid 与 PlantUML 会忽略它们，而解析器会读取它们。因此「图 ↔ 模型」的比较是精确的。
+
+审查只覆盖建模，不覆盖行为。每条发现都会指明应该跑哪一项引擎检查。完整清单（`UML001`-`UML019`）、指令格式、示例与各视图局限见 [`skills/logicprobe/references/uml-modeling-guide.md`](skills/logicprobe/references/uml-modeling-guide.md)。
 
 ## 使用
 
-插件在会话首个模型步骤自动注入能力通知。技能在任务匹配其 `Use when` 描述时激活：
+插件在会话首个模型步骤自动注入能力通知。任务匹配技能的 `Use when` 描述时技能生效：
 
 - **设计文档 / 计划审查** — "Review this design document" → 声称枚举与代码库核查
-- **行为类问题** — "could this state machine deadlock"、"is this retry limit safe"、"check this timing for bugs" → 主动建议（不自动加载）作为可选验证
-- **重构计划** — 管线对比前后模型，标记计划未声明的行为变化
-- **数据模型/迁移审查** — "is this migration non-breaking"、"does this copy cover all required fields" → 使用 `logicprobe-datamodel` 技能
+- **行为类问题** — "could this state machine deadlock"、"is this retry limit safe" → 主动建议（不自动加载）作为可选验证
+- **重构计划** — 对比前后模型，标记计划未声明的行为变化
+- **数据模型 / 迁移审查** — "is this migration non-breaking" → 使用 `logicprobe-datamodel` 技能
+- **代码流程建模** — "把这个状态机画出来"、"这份 UML 图对吗" → 用 `logicprobe_uml` 出图并审查建模，随后仍用 `logicprobe_verify` 验证行为
 
 技能在 Phase 0 依据计划特征自动分级（LIGHTWEIGHT / STANDARD / ESCALATED），并在计划文件追加 `## Plan Verification` 摘要块作为审计痕迹。
 
-Python 可选：已有 LogicModelV1 JSON 时可直接运行独立引擎 `skills/logicprobe/references/logicprobe-engine.py`（`verify` 跑 S1-S8/A1-A14/D1-D4，`compose` 跑 C1/C2 组合，`export` 生成 UPPAAL/TLA+/PRISM/SPIN 输入——与 dsh 工具逐字节一致，见 tests/python/run.mjs）；模型仅为抽取出的状态表时，填充模板 `skills/logicprobe/references/verification-harness.py`；数据模型验证使用 `skills/logicprobe-datamodel/references/data-model-harness.py`；不可用（如离线开发机）时，对应 guide 提供手动验证模式。
+Python 可选。已有 LogicModelV1 JSON 时，可直接运行独立引擎 `skills/logicprobe/references/logicprobe-engine.py`：
+
+- `verify` 跑 S1-S8 / A1-A14 / D1-D4
+- `compose` 跑 C1 / C2 组合
+- `export` 生成 UPPAAL、TLA+、PRISM、SPIN 输入
+- `uml-render`、`uml-parse`、`uml-review` 覆盖 UML 前端
+
+它与 dsh 工具逐字节一致，对照见 `tests/python/run.mjs`。模型只有抽取出的状态表时，填充模板 `skills/logicprobe/references/verification-harness.py`。数据模型验证使用 `skills/logicprobe-datamodel/references/data-model-harness.py`。Python 不可用（例如离线开发机）时，对应 guide 提供手动验证模式。
 
 示例模型见 [`examples/`](examples/README.md)：订单状态机 before/after、电商数据模型、User 字段迁移。
 
@@ -169,7 +197,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.kimi/plugins/logicpr
 
 ## ZCode (Z.AI)
 
-ZCode 3.0+ 遵循 Agent Skills 标准。无插件市场——手动复制技能到 `.zcode/skills/`：
+ZCode 3.0+ 遵循 Agent Skills 标准。它没有插件市场，手动把技能复制过去：
 
 ```bash
 git clone https://github.com/AmethystLuna/logicprobe.git
@@ -180,9 +208,10 @@ cp -r logicprobe/skills/* .zcode/skills/
 
 ## 环境要求
 
-- Claude Code v2.1+ / Codex CLI 最新 / Cursor 2.5+ / Kimi CLI 最新 / OpenCode 最新 / ZCode 3.0+
-- DeepSeek Harness (dsh): dev preview — 已实测 mainline 2026-08-14（gate bundle 加载并注入会话成功）
-- Python 3.6+ 可选（仅自动验证工具需要；手动兜底模式无需任何依赖）
+- 宿主：Claude Code v2.1+ / Codex CLI 最新 / Cursor 2.5+ / Kimi CLI 最新 / OpenCode 最新 / ZCode 3.0+
+- DeepSeek Harness (dsh)：dev preview，声明支持 `>= 0.1.0-rc.7`。最新一轮在 0.2.1-alpha.1 上实测了安装、挂载、启动与卸载；更早一轮实测覆盖 0.1.5-rc.2 到 0.2.0-rc.2。逐版本证据见 [DSH-COMPATIBILITY.md](DSH-COMPATIBILITY.md)。
+- Web 端的「Gate 注入」开关需要 **dsh ≥ 0.1.7-alpha.1**，因为设置服务必须能投影即时字段。更早的 dsh 上插件照常加载、照常注入，只是开关不出现，也不报错。
+- Python 3.6+ 可选，仅自动验证工具需要。手动兜底模式不需要任何依赖。
 
 ## 配置
 
@@ -192,7 +221,9 @@ cp -r logicprobe/skills/* .zcode/skills/
 |---|---|---|---|
 | `enabled` | boolean | `true` | 设为 `false` 可关闭首步 Gate 注入。 |
 | `gateContent` | string | 内置 gate 文本 | 覆盖注入到首轮模型上下文中的文本。 |
-| `interaction` | `ask` \| `auto` \| `follow-approval` | `follow-approval` | 模型确认策略；`follow-approval` 在会话 approval policy 为 `never` 时解析为 `auto`。 |
+| `interaction` | `ask` \| `auto` \| `follow-approval` | `follow-approval` | 模型确认策略。`follow-approval` 在会话 approval policy 为 `never` 时解析为 `auto`。 |
+
+在 dsh Web GUI 里可以直接改这个开关：侧边栏 **插件** → 本插件卡片 → 「Gate 注入」。它实时生效，不必重启 profile。它只管注入的那段文本：关掉后 skills 与验证工具照常注册。同一张卡片上还有一个更粗粒度的行开关，关掉它会整行卸载插件，技能、工具和这个开关一起消失。要持久化覆盖，仍按下面的 profile patch 写。
 
 在 profile 的 `cordis.patch.yml` 中按 row id 覆盖：
 
@@ -209,20 +240,20 @@ cp -r logicprobe/skills/* .zcode/skills/
 
 ## 卸载
 
-- 如果通过 DSH 插件管理器安装，请使用同一管理器从目标 profile 中移除 `logicprobe`。
-- 如果手动复制过 `skills/*`，请删除复制到 `~/.agents/skills/` 或项目 `.dsh/skills/` 下的对应目录。
-- 如果通过 `cordis.patch.yml` 添加，请删除 profile patch 中 `id: logicprobe` 对应的行，并重启 DSH。
+- 通过 DSH 插件管理器安装的，用同一管理器从目标 profile 中移除 `logicprobe`。
+- 手动复制过 `skills/*` 的，删除 `~/.agents/skills/` 或项目 `.dsh/skills/` 下的对应目录。
+- 通过 `cordis.patch.yml` 添加的，删除 profile patch 中 `id: logicprobe` 的行，并重启 DSH。
 
 ## 权限与数据
 
 - 插件运行时只读取包内自带的 `skills/` 目录，用于通过 DSH 标准 filesystem skill provider 注册技能。
 - 它会在会话首轮向模型上下文注入配置好的 gate 文本。
-- 它不读取凭据、不发起网络连接，也不会访问 DSH 会话上下文之外的用户数据。
+- 它不读取凭据，不发起网络连接，也不访问 DSH 会话上下文之外的用户数据。
 - 实际使用技能时，模型会像使用其他编码技能一样，按用户指示读取项目文件。
 
 ## 故障排查
 
-- 技能在 DSH 中不可见：确认 DSH 版本支持 `ctx.skills` / Agent Skills 发现，并在安装后重启 profile。
+- 技能在 DSH 中不可见：确认 DSH 版本支持 `ctx.skills` 与 Agent Skills 发现，并在安装后重启 profile。
 - Gate 未注入：检查 `enabled` 是否为 `false`，以及 profile patch 中是否存在 `id: logicprobe` 的行。
 - 插件管理器拒绝安装：确认 `@deepseek-ai/*` 包声明在 `peerDependencies` 中，而不是 `dependencies`。
 - 手动复制后 DSH 仍看不到技能：改用原生 bundle 安装（`dsh plugin add "github:AmethystLuna/logicprobe"`）。
@@ -237,10 +268,12 @@ npm run build
 
 测试链：
 
-- `npm run test:engine` — 状态机/数据模型引擎回归（`tests/engine`、`tests/data-engine`、`tests/concurrency`、`tests/apply-smoke`、`tests/exporters`、`tests/external`）+ Python 逐字节一致性对照（`tests/python/run.mjs`：同一批 fixture 在 TS 引擎与 `skills/logicprobe/references/logicprobe-engine.py` 之间比对报告/组合/导出产物；无 Python 时自动 SKIP）
-- `npm run test:full` — `tests/full-suite.mjs` 端到端合并套件
-- `npm run test:python` — 仅 Python parity（构建 + `tests/python/run.mjs`）
-- 触发测试位于 `tests/skill-triggering/`：`bash tests/skill-triggering/run-all.sh`
+| 命令 | 内容 |
+|---|---|
+| `npm run test:engine` | 状态机与数据模型引擎回归（`tests/engine`、`tests/data-engine`、`tests/concurrency`、`tests/uml`、`tests/apply-smoke`、`tests/dsh-client-half`、`tests/exporters`、`tests/external`），再加 Python 逐字节一致性对照。对照脚本是 `tests/python/run.mjs`，它把同一批 fixture 在 TS 引擎与 `skills/logicprobe/references/logicprobe-engine.py` 之间比对报告、组合与导出产物。无 Python 时自动 SKIP。 |
+| `npm run test:full` | `tests/full-suite.mjs` 端到端合并套件 |
+| `npm run test:python` | 仅 Python parity（构建 + `tests/python/run.mjs`） |
+| `bash tests/skill-triggering/run-all.sh` | 触发测试，位于 `tests/skill-triggering/` |
 
 ## 许可证与安全
 
@@ -252,7 +285,7 @@ npm run build
 
 | 插件 | 说明 |
 |------|------|
-| [embedded-workbench](https://github.com/AmethystLuna/embedded-workbench) | 嵌入式 C/C++ 工具箱，其 Plan Verification Gate 依赖本技能。本插件已从 embedded-workbench 拆分而来。 |
+| [embedded-workbench](https://github.com/AmethystLuna/embedded-workbench) | 嵌入式 C/C++ 工具箱，其 Plan Verification Gate 依赖本技能。本插件由 embedded-workbench 拆分而来。 |
 
 ## 致谢