dsh-logicprobe 0.9.0 → 1.1.0

package/README.en-US.md

@@ -4,7 +4,9 @@
 
 [![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. 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.
+For an unverified design, failure is only a matter of time. However complex the code, model it and run it — then it becomes clear.
+
+logicprobe checks a claim against the thing it describes. Facts go against the source. Behaviour goes through a model: state machines, protocols, composition, data models, migrations. Diagrams are read as dependency graphs, at one level or several. Two reports can be compared to see whether a change made things worse. Dimensions it cannot verify are named, and routed.
 
 **Cross-platform**: works with Claude Code, Codex CLI, Cursor, Kimi CLI, OpenCode, and ZCode. Built on the [Agent Skills](https://agentskills.io) open standard.
 
@@ -23,9 +25,125 @@ Design documents are not truth. Code is. This skill checks every verifiable clai
 
 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.
 
+## Tools and Reports
+
+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:
+
+| 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. |
+| `logicprobe_structure_verify` | Audits a component/package/class/deployment diagram as a **dependency graph** (UML020-UML026): isolated nodes, dangling endpoints, dependency cycles, edges that violate an allowed-dependency matrix, upward cross-layer edges, and required edges the diagram is missing — every judged edge names the rule ids it matched. It audits the diagram; reconcile it with a source-side include scan. |
+| `logicprobe_report_diff` | Compares two reports of the same family (baseline vs current) and reports the added, removed and changed findings with a **delta** verdict. Findings are matched by `check id + code + machine-readable locator (evidence/path)`, so a reworded message only counts as `changed`; a newly added error fails it, while `currentVerdict` keeps the run's absolute result visible. The "violations must not increase" criterion, computed instead of eyeballed. |
+
+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.
+
+### How to read a report (`ok` is not a verdict)
+
+Every report separates "the tool ran" from "the review passed":
+
+| Field | Meaning |
+|-------|---------|
+| `schema` | The versioned report contract (`logicprobe/verify/v1`, `logicprobe/uml/review/v1`, …) — branch on it instead of sniffing fields. |
+| `ok` | The engine produced a report. For `verify` it is `false` only when model *validation* failed. It is **not** a verdict. |
+| `ran` | The tool executed. `false` only for a tool-level refusal (which carries `errorCode`/`error`). |
+| `verdict` | `pass` / `pass_with_findings` / `fail`. Any `severity: "error"` finding — or a validation failure — makes it `fail`. |
+| `verdictReason` | One line, e.g. `1 error finding(s) (first: S2_NO_TRANSITIONS)`. |
+| `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. 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.
+
+## UML Modelling and Review
+
+`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.
+
+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 verdict — not `ok` — says whether the review passed: `fail` means error findings exist and the diagram did **not** pass. The full list (`UML001`-`UML019` plus `UML_NOT_A_STATE_DIAGRAM`), 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).
+
+## Architecture and Dependency Review
+
+A component diagram is not a state machine; it is a directed **dependency graph**. `logicprobe_structure_verify` parses the same PlantUML component/package/class/deployment text (or a Mermaid class diagram) into real nodes and edges — nothing is discarded — and checks it:
+
+| Check | Severity | Meaning |
+|---|---|---|
+| `UML020_ISOLATED_NODE` | warning | A declared, non-container node with no edge: a dead entry, or a dependency the diagram forgot |
+| `UML021_DANGLING_REFERENCE` | error | An arrow endpoint never declared — a dependency on a component that does not exist |
+| `UML022_CYCLE` | error | A directed cycle, reported as the **shortest** cycle path; a cycle means no build order and no layering |
+| `UML023_DISALLOWED_EDGE` | error | An edge that violates the allowed-dependency matrix (with `default: deny`, any edge no rule permits) |
+| `UML024_LAYER_VIOLATION` | error | An upward edge between declared layers (downward is allowed, upward is not) |
+| `UML025_MISSING_EXPECTED_EDGE` | warning | A `require: true` edge the diagram does not draw: the matrix and the diagram disagree |
+
+**Multi-level**: the same set can be supplied by level — `diagrams: [{name, diagram, parent}]`. Each level runs the structural checks above (findings tagged with the `file` they came from), then every declared pair is checked for **refinement**: a child must not invent a dependency between nodes its parent also has, and must not drop a parent edge without expanding it into a path (expansions are listed in `expandedEdges` for a reviewer to confirm). A cyclic parent relation is `UML030`, an unknown parent `UML028`, an empty set `UML031`. Each pair reports its node/edge/inherited/new/expanded/missing/invented counts (`pairs[]`), and every level is hashed (`hashes.diagrams`), so a baseline diff can tell which level moved. Commands: `structure diagram.puml` for one diagram, `granularity manifest.json` for several levels.
+
+The dependency matrix is the single source of truth:
+
+```json
+{
+  "rules": [
+    { "id": "R1-app-may-use-hal", "source": "app.*", "allow": ["hal.*"], "deny": ["hal.internal"] },
+    { "id": "R4-persistence-required", "source": "PAY", "allow": ["DB"], "require": true }
+  ],
+  "layers": [{ "name": "app", "members": ["SVC", "PAY"] }, { "name": "hal", "members": ["DRV", "DB"] }],
+  "default": "deny"
+}
+```
+
+`source`, `allow`, `deny` and `members` accept globs (`*`, `?`); **`deny` wins globally**, so the result never depends on rule order; an invalid matrix (typo'd key, duplicate rule id, `require` without `allow`) is a hard `MATRIX_INVALID` error rather than a silently weaker check. Every edge is echoed in `edgeVerdicts` as `{from, to, matchedRules, allowed, basis}`.
+
+**What it does not do, stated plainly**: write-site analysis ("only the ISR writes this flag", "one writer per register") is **out of scope** — it needs the source and statement-level rules, not a model or a diagram. `logicprobe_concurrency_scan` marks such a claim unverified and routes it to a source-side check (your own include/arch checker, a static analyzer, or CBMC).
+
+**It audits the diagram, not the code.** Function pointers, DI, registries and plugin loading never appear as edges; a clean `pass` only means the drawn graph is self-consistent and satisfies the matrix. The step that touches the source is the **reconciliation**: run a source-side include/dependency scan (your own include or dependency checker, for instance) with the same rule ids and classify every difference — the diagram is stale (`UML025` when the rule is `require: true`), the diagram is aspirational or the scan scope is narrower, the code violates a rule the diagram never showed (**the architecture defect the diagram hid** — the one worth acting on), or both agree it is a violation. The full matrix schema, a worked example and the reconciliation table are in [`skills/logicprobe-structure/references/structure-review-guide.md`](skills/logicprobe-structure/references/structure-review-guide.md).
+
+## 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.
+
+| Skill | Domain | Typical trigger |
+|---|---|---|
+| `logicprobe` | Claim verification plus behavioural verification (state machines and protocols, timing and quantitative guarantees, composition, refactoring regression) | "Review this design document", "could this state machine deadlock", "is this retry limit safe", "is this budget enough" |
+| `logicprobe-uml` | Diagram modelling and diagram review | "draw this state machine", "is this UML diagram right", "can this component diagram be reviewed as a state machine" |
+| `logicprobe-structure` | Architecture and dependency-structure review | "review this architecture", "are the module dependencies sound", "is the layering right" |
+| `logicprobe-concurrency` | Concurrency claims: mined and routed, never proven | "is this thread-safe", "can this ISR race" |
+| `logicprobe-datamodel` | Data models, migrations and data invariants | "is this migration non-breaking", "does this copy cover every field" |
+
+Behavioural questions still follow the suggest-don't-escalate rule: offer an optional verification pass and let the user decide. The skill classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED) from plan features in Phase 0, and appends a `## Plan Verification` summary block as the audit trail.
+
+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
+- `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)
+
+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.
+
+Sample models live under [`examples/`](examples/README.md): an order state machine before/after, an e-commerce data model, and a User field migration.
+
 ## Installation
 
-### Claude Code install (recommended)
+### Claude Code (recommended)
 
 Add the marketplace to **Claude Code**'s `~/.claude/settings.json`:
 
@@ -61,7 +179,7 @@ Then enable it in `~/.claude/settings.json`:
 }
 ```
 
-## DeepSeek Harness (dsh)
+### 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`.
 
@@ -71,21 +189,6 @@ The bundle does three things:
 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):
-
 ```bash
 # from npm (package name: dsh-logicprobe)
 dsh plugin --profile web add dsh-logicprobe
@@ -107,47 +210,10 @@ pnpm records that version in a `minimumReleaseAgeExclude` entry in the profile's
 
 > 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
-
-`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 injects a capability notification into the first model step. The skill activates when its `Use when` description matches your task:
-
-- **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 classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED) from plan features in Phase 0, and appends a `## Plan Verification` summary block as the audit trail.
-
-Python is optional. When a LogicModelV1 JSON already exists, run the standalone engine at `skills/logicprobe/references/logicprobe-engine.py`:
-
-- `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
+### Codex CLI
 
 This plugin also supports OpenAI Codex CLI. Skills follow the Agent Skills standard and work identically on both platforms.
 
-### Codex install
-
 ```bash
 # Add as a marketplace
 codex plugin marketplace add AmethystLuna/logicprobe
@@ -164,12 +230,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
@@ -177,12 +241,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
@@ -193,7 +255,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`:
 
@@ -205,7 +267,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:
 
@@ -221,7 +283,7 @@ Skills are invoked with `$logicprobe`. See `.zcode/INSTALL.md`.
 - 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.
+- Python 3.8+ (standard library), needed to run the checks outside dsh. The manual mode needs no dependencies.
 
 ## Configuration
 
@@ -281,7 +343,7 @@ Test chain:
 
 | 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: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 `tools/python/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/` |

package/README.md

@@ -2,7 +2,9 @@
 
 <p align="center"><a href="README.en-US.md">English</a> · <strong>中文</strong></p>
 
-文档不是事实，代码才是。本技能逐条核验设计文档、架构规格与重构计划里的可验证声称，再把每一条对照到代码库的真实实现。遇到行为类声称时，它升级为可执行模型验证。
+没验证过的设计，翻车只是时间问题；再复杂的代码，建模再跑就清楚了。
+
+logicprobe 核验声称与实物是否一致。事实类对着源码查。行为类跑模型：状态机、协议、组合、数据模型、迁移。图按依赖图读，单层或多层。改动前后用基线对比。验不了的维度明说，并指出该用哪个工具。
 
 **跨平台**：支持 Claude Code、Codex CLI、Cursor、Kimi CLI、OpenCode、ZCode。技能基于 [Agent Skills](https://agentskills.io) 开放标准。
 
@@ -21,9 +23,125 @@
 
 模型永远先以转换表形式展示，**经用户确认后才运行**。模型提取错误是验证的头号失败模式。
 
+## 工具与报告
+
+下面两份清单（原生工具清单，以及怎么读它们的报告）与**安装方式无关**：dsh 走原生工具，Claude Code / Codex / Cursor / 终端 / CI 走同一套技能与 Python CLI 引擎（见「使用」）。
+
+工具清单：
+
+| 工具 | 作用 |
+|------|------|
+| `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 建模与审查」。 |
+| `logicprobe_structure_verify` | 把组件/包/类/部署图当**依赖图**审查（UML020-UML026）：孤立节点、悬空端点、依赖环、违反允许依赖矩阵的边、跨层反向依赖、矩阵要求却缺失的边；每条被判定的边都会报出命中的规则 id。它审的是**图**，代码侧要用 include/依赖扫描对账。 |
+| `logicprobe_report_diff` | 对比两份同族报告（baseline vs current），给出新增/消除/变化的发现与**增量**判定：按 `检查 id + code + 机器可读定位（evidence/path）` 匹配，改措辞只会算作 `changed`；新增 error 判 fail，而 `currentVerdict` 仍保留本次运行的绝对结论。"违规不增"的验收判据，算出来而不是看出来的。 |
+
+迁移代价用 `cost`（缺省 1），配 `budget` 不变量即由 A12 检查最坏路径代价，正成本环会被判为无界。迁移权重用 `weight`（缺省 1），配 `probability` 不变量即由 A13 计算概率可达。状态上的 `onEntry`/`onExit` 动作由 A4 自动纳入配对检查，`maxTicks` 加 `tickEvents` 由 A14 检查期限。
+
+### 怎么读报告（`ok` 不是结论）
+
+所有报告都同时给「工具跑成功」与「审查通过」两件事：
+
+| 字段 | 含义 |
+|------|------|
+| `schema` | 版本化报告契约（`logicprobe/verify/v1`、`logicprobe/uml/review/v1`…），消费方按它分支而不是猜字段。 |
+| `ok` | 引擎产出了报告。对 `verify` 只在**模型校验失败**时为 `false`；它**不是**结论。 |
+| `ran` | 工具确实执行了。仅在工具层拒绝请求（带 `errorCode`/`error`）时为 `false`。 |
+| `verdict` | `pass` / `pass_with_findings` / `fail`。任何 `severity: "error"` 的发现、或校验失败，都会是 `fail`。 |
+| `verdictReason` | 一行说明，例如 `1 error finding(s) (first: S2_NO_TRANSITIONS)`。 |
+| `hashSpec` | `modelHash` 依据的已发布规范（见 [`hash-spec.md`](skills/logicprobe/references/hash-spec.md)）。 |
+| `hashes` | 本次报告涉及的全部哈希集中一处（模型哈希、图/矩阵哈希、前后模型哈希）。 |
+| `metadataKeys` | 输入里带 `_` 前缀的注记键路径（仅当存在时出现）。 |
+| `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>` 可回答某个历史哈希是否属于任何已发布规范。
+
+## UML 建模与审查
+
+`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`+ 已为其保留。
+
+保真度是这套功能的核心。生成的图带有 `logicprobe:` 注释指令（init、终态、别名、变量类型），Mermaid 与 PlantUML 会忽略它们，而解析器会读取它们。因此「图 ↔ 模型」的比较是精确的。
+
+审查只覆盖建模，不覆盖行为。每条发现都会指明应该跑哪一项引擎检查。判据是 `verdict`（`fail` 表示有 error 级发现，图**未**通过审查），不是 `ok`。完整清单（`UML001`-`UML019` 加 `UML_NOT_A_STATE_DIAGRAM`）、指令格式、示例与各视图局限见 [`skills/logicprobe/references/uml-modeling-guide.md`](skills/logicprobe/references/uml-modeling-guide.md)。
+
+## 架构与依赖审查
+
+组件图不是状态机，它是一张**有向依赖图**。`logicprobe_structure_verify` 把同一份 PlantUML 组件/包/类/部署图（或 Mermaid 类图）解析成真正的节点与边——不再丢弃——然后逐项检查：
+
+| 检查 | 严重度 | 含义 |
+|---|---|---|
+| `UML020_ISOLATED_NODE` | warning | 已声明且非容器的节点一条边都没有：死条目，或漏画的依赖 |
+| `UML021_DANGLING_REFERENCE` | error | 箭头端点从未被声明——依赖指向了根本不存在的组件 |
+| `UML022_CYCLE` | error | 有向环，给出**最短环**路径；环意味着没有构建顺序、没有分层 |
+| `UML023_DISALLOWED_EDGE` | error | 违反允许依赖矩阵的边（`default: deny` 时未被任何规则允许的边也算） |
+| `UML024_LAYER_VIOLATION` | error | 从下层指向已声明上层的反向依赖（向下允许、向上禁止） |
+| `UML025_MISSING_EXPECTED_EDGE` | warning | `require: true` 要求存在的边图里没有；矩阵与图不一致 |
+
+**多粒度**:同一套图可以按层级给出来 —— `diagrams: [{name, diagram, parent}]` —— 每一层先各自跑上面的结构检查(发现按 `file` 标注来源),再逐对做**细化校验**:子图不得在父层节点之间凭空造出依赖,也不得丢掉父图的边而不把它展开成路径(展开成路径的会列进 `expandedEdges` 供人确认);父图关系成环报 `UML030`,父图未知名报 `UML028`。每对还给出节点/边/继承/新增/展开/丢失/造出的计数(`pairs[]`),并给每层记 sha256(`hashes.diagrams`),这样"哪一层动了"可以由 `--baseline` 直接算出来。命令:`structure diagram.puml` 审单图,`granularity manifest.json` 审多层。
+
+依赖矩阵就是单一事实源，JSON 形式：
+
+```json
+{
+  "rules": [
+    { "id": "R1-app-may-use-hal", "source": "app.*", "allow": ["hal.*"], "deny": ["hal.internal"] },
+    { "id": "R4-persistence-required", "source": "PAY", "allow": ["DB"], "require": true }
+  ],
+  "layers": [{ "name": "app", "members": ["SVC", "PAY"] }, { "name": "hal", "members": ["DRV", "DB"] }],
+  "default": "deny"
+}
+```
+
+`source`/`allow`/`deny`/`members` 支持 glob（`*`、`?`）；**`deny` 全局优先**，结果不依赖规则书写顺序；矩阵写错（键名拼错、规则 id 重复、`require` 没有 `allow`）是硬错误 `MATRIX_INVALID`，不会静默放宽检查。每条边都会在 `edgeVerdicts` 里回显 `{from, to, matchedRules, allowed, basis}`。
+
+**不做的事说得清楚**:写点分析("只有 ISR 写这个标志""一个寄存器只有一个写者")**不在本插件射程**——它需要读源码与语句级规则,不是模型或图;这类声称由 `logicprobe_concurrency_scan` 标为未验证并路由到源码侧检查(自己的 include/arch 检查器、静态分析器或 CBMC)。
+
+**它审的是图，不是代码。** 函数指针、DI、注册表、插件加载这些运行期依赖不会出现在边上；干净的 `pass` 只说明"画出来的图自洽且满足矩阵"。真正碰代码的那一步是**对账**：与源码侧的 include/依赖扫描（例如你们自己的 include/依赖检查脚本）用同一套规则 id 跑一遍，差异按四类定性——图漏了代码里有的边（图过期，`require` 时由 `UML025` 报出）、图画了代码里没有的边（图是愿景，或扫描范围更窄）、代码违反了图里没画出的规则（**图掩盖的架构缺陷**，这条才是要动手的）、两边一致判违规（真违规）。完整矩阵 schema、worked example 与对账表见 [`skills/logicprobe-structure/references/structure-review-guide.md`](skills/logicprobe-structure/references/structure-review-guide.md)。
+
+## 使用
+
+插件在会话首个模型步骤自动注入能力通知。技能按**领域**拆分,一共四个;`logicprobe` 是总入口,只要有一点「想验证代码/某个说法是否成立」的念头就加载它,它自己的路由表再把相邻领域交出去:
+
+| 技能 | 领域 | 典型触发 |
+|---|---|---|
+| `logicprobe` | 声称核查 + 行为验证(状态机/协议、时序与量化保证、组合、重构回归) | "Review this design document"、"could this state machine deadlock"、"is this retry limit safe"、"这个预算够不够" |
+| `logicprobe-uml` | 图的建模与审查 | "把这个状态机画出来"、"这份 UML 图对吗"、"component 图能不能当状态机审" |
+| `logicprobe-structure` | 架构 / 依赖结构审查 | "审查一下这个架构"、"模块依赖有没有问题"、"分层对不对" |
+| `logicprobe-concurrency` | 并发声称:挖矿 + 路由(不证明) | "thread-safe 吗"、"这个 ISR 会 race 吗" |
+| `logicprobe-datamodel` | 数据模型 / 迁移与不变量 | "is this migration non-breaking"、"这份 copy 覆盖全字段了吗" |
+
+行为类问题仍按"主动建议、不自动升级"处理:先建议一次可选验证,由你决定是否跑。技能在 Phase 0 依据计划特征自动分级(LIGHTWEIGHT / STANDARD / ESCALATED),并在计划文件追加 `## Plan Verification` 摘要块作为审计痕迹。
+
+在 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
+- `compose` 跑 C1 / C2 组合
+- `export` 生成 UPPAAL、TLA+、PRISM、SPIN 输入
+- `uml-render`、`uml-parse`、`uml-review` 覆盖 UML 前端（`uml-review --explain-labels` 打印解析器接受的标签与注释口径）
+
+它与 dsh 工具逐字节一致，对照见 `tests/python/run.mjs`。模型只有抽取出的状态表时，填充模板 `tools/python/verification-harness.py`。数据模型验证使用 `tools/python/data-model-harness.py`。Python 不可用（例如离线开发机）时，对应 guide 提供手动验证模式。
+
+示例模型见 [`examples/`](examples/README.md)：订单状态机 before/after、电商数据模型、User 字段迁移。
+
 ## 安装
 
-### Claude Code 安装（推荐）
+### Claude Code（推荐）
 
 在 **Claude Code** 的 `~/.claude/settings.json` 中添加 marketplace：
 
@@ -59,7 +177,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/l
 }
 ```
 
-## DeepSeek Harness (dsh)
+### DeepSeek Harness (dsh)
 
 原生 dsh 支持以 cordis 插件 bundle 的形式提供，位于**仓库根**，由根 `package.json` 的 `dsh.bundle` 声明。
 
@@ -69,21 +187,6 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.claude/plugins/dev/l
 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，推荐）：
-
 ```bash
 # 从 npm 安装（包名 dsh-logicprobe）
 dsh plugin --profile web add dsh-logicprobe
@@ -105,47 +208,10 @@ pnpm 会把该版本写进 profile 的 `pnpm-workspace.yaml` 的 `minimumRelease
 
 > 注意包名。npm 包名是 `dsh-logicprobe`，没有 scope。在 web profile 的 `package.json` 中，依赖键与 `dsh.profile.bundles` 必须都写 `dsh-logicprobe`。写错时 dsh 加载器找不到 `node_modules/dsh-logicprobe`，启动会失败。
 
-## UML 建模与审查
-
-`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` 描述时技能生效：
-
-- **设计文档 / 计划审查** — "Review this design document" → 声称枚举与代码库核查
-- **行为类问题** — "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 输入
-- `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 字段迁移。
-
-## Codex CLI
+### Codex CLI
 
 本插件同样支持 OpenAI Codex CLI。技能遵循 Agent Skills 标准，两个平台行为一致。
 
-### Codex 安装
-
 ```bash
 # 添加 marketplace
 codex plugin marketplace add AmethystLuna/logicprobe
@@ -162,12 +228,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
@@ -175,12 +239,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
@@ -191,7 +253,7 @@ git clone https://github.com/AmethystLuna/logicprobe.git ~/.kimi/plugins/logicpr
 
 技能通过 `/skill:logicprobe` 调用。
 
-## OpenCode
+### OpenCode
 
 技能自动从 `.claude/skills/` 和 `.codex/skills/` 路径发现。在 `opencode.json` 中添加：
 
@@ -203,7 +265,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 标准。它没有插件市场，手动把技能复制过去：
 
@@ -219,7 +281,7 @@ 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，声明支持 `>= 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+ 可选，仅自动验证工具需要。手动兜底模式不需要任何依赖。
+- Python 3.8+（标准库），在 dsh 之外运行验证所需；手动兜底模式不需要任何依赖。
 
 ## 配置
 
@@ -278,7 +340,7 @@ npm run build
 
 | 命令 | 内容 |
 |---|---|
-| `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: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 引擎与 `tools/python/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/` |