dsh-logicprobe 0.9.0 → 1.0.0

package/skills/logicprobe-structure/references/structure-review-guide.md

@@ -0,0 +1,177 @@
+# Structure Review Guide
+
+How to audit a component, package, class or deployment diagram as a dependency graph: the matrix schema, every finding code, a worked example, and the method for reconciling the diagram with a source-side check.
+
+The tool is `logicprobe_structure_verify`. A host without it runs the repository engine on the same diagram text; the parity test compares the two field for field.
+
+## Inputs
+
+```text
+logicprobe_structure_verify  { diagram: "<PlantUML or Mermaid class text>", notation?: auto|plantuml|mermaid, matrix?: {...} }
+```
+
+**Accepted diagram families**: PlantUML `component`, `package`, `class`, `interface`, `enum`, `object`, `actor`, `usecase`, `database`, `node`, `artifact`, `deployment`, `rectangle`, `folder`, `frame`, `cloud`, `queue`, `stack`, `storage`, `collections`, `agent`, `boundary`, `control`, `entity`, `namespace`, `module`; Mermaid `classDiagram` (`class X`, `X --> Y : label`, `X ..|> Y`).
+
+**Edge forms** (PlantUML): `-->`, `->`, `..>`, `--`, `==>`, `<--`, `<..`. Mermaid class: `-->`, `..>`, `--|>`, `..|>`, `--`, `..`.
+
+**What is read**: declarations (with `as` aliases and quoted labels), container nesting (`package "app" { … }`), arrows with labels, and note blocks (skipped — a note is not a dependency). Anything else is reported as `STRUCTURE_IGNORED_LINE` in `warnings`, never silently dropped.
+
+**Node identity**: the alias/id when one exists (`component [Order Service] as SVC` → `SVC`), otherwise the declared name. An endpoint that only ever appears in an arrow still becomes a node, marked `declared: false` — that is what `UML021` reports.
+
+## Matrix schema
+
+```jsonc
+{
+  "rules": [
+    {
+      "id": "R1",              // required, unique; this is what the report cites
+      "source": "app.*",       // node id or glob; absent = the rule judges no source
+      "allow": ["hal.*"],      // permitted targets (glob or id)
+      "deny": ["hal.secret"],  // forbidden targets; deny wins over allow, globally
+      "require": false         // true = an edge matching source→allow must exist (UML025)
+    }
+  ],
+  "layers": [
+    { "name": "app", "members": ["SVC", "PAY"] },   // top first
+    { "name": "hal", "members": ["DRV", "DB"] }
+  ],
+  "default": "allow"           // or "deny": anything unlisted is a violation
+}
+```
+
+Rules:
+
+- Glob: `*` matches any run of characters (including `.` and `:`), `?` exactly one. `app.*` matches `app.motion`, not `hal.app`.
+- **Deny is global.** Evaluation collects every rule whose `source` matches the edge, then: any deny match ⇒ violation; else any allow match ⇒ permitted; else the matrix `default` decides (`default` basis vs `unlisted` basis). The verdict cannot depend on rule order.
+- `default: "allow"` is the permissive default: rules are exceptions. `default: "deny"` is the closed-world form and is what most architecture tables actually mean.
+- Layers are independent of rules and are evaluated on every edge whose endpoints both belong to a layer: index order is top→bottom, so `app → hal` is allowed and `hal → app` is `UML024`.
+- An invalid matrix is a hard error (`MATRIX_INVALID`) and no rules apply — a typo must never silently weaken the check. Unknown keys, duplicate rule ids, non-string patterns and `require` without `allow` are all rejected.
+
+## Finding codes
+
+| Code | Severity | Evidence | How to read it |
+|---|---|---|---|
+| `UML020_ISOLATED_NODE` | warning | `nodes[{id,line}]` | Declared, non-container, degree 0. Either a dead entry or a forgotten dependency. |
+| `UML021_DANGLING_REFERENCE` | error | `nodes[{id,line}]` | An arrow endpoint no declaration introduced. The dependency targets something the diagram never defines. |
+| `UML022_CYCLE` | error | `cycle[]`, `path[]` | Shortest directed cycle, start repeated (`A → B → C → A`). A self-loop is a cycle of two elements (`A → A`). |
+| `UML023_DISALLOWED_EDGE` | error | `edge{from,to,line}`, `rule?`, `matchedRules[]`, `basis` | `basis: deny` means a rule forbade it; `basis: unlisted` means no rule allowed it under `default: deny`. |
+| `UML024_LAYER_VIOLATION` | error | `violations[{from,to,fromLayer,toLayer,line}]` | An upward edge between declared layers. |
+| `UML025_MISSING_EXPECTED_EDGE` | warning | `missing[{rule,source,expected,unsatisfiedFrom,noSourceMatch}]` | A `require: true` rule the diagram does not satisfy. `noSourceMatch` distinguishes "wrong target" from "no such source node". |
+| `UML026_NO_NODES` | error | `notation` | Nothing to review; the text is not a structure diagram. |
+| `MATRIX_INVALID` | error | — | The matrix was rejected; its messages name the exact field. |
+
+Every report also carries `summary` (nodes, edges, containers, isolated, dangling, cycles, disallowedEdges, layerViolations, missingExpectedEdges, errors, warnings, rules), `edgeVerdicts` when a matrix was supplied, and `verdict` / `verdictReason`. A structure diagram with an error finding is `verdict: "fail"` even though `ok: true` — `ok` only means the tool ran.
+
+## Worked example
+
+The diagram (a real shape: two packages, an orphan, a back edge, an undeclared endpoint):
+
+```plantuml
+@startuml
+package "app" {
+  component [Order Service] as SVC
+  component [Payment Adapter] as PAY
+}
+package "hal" {
+  component [Storage Driver] as DRV
+}
+component [Orphan Cache] as CACHE
+SVC --> PAY : plan
+PAY --> DRV : read
+DRV --> SVC : fault
+SVC --> GHOST : unknown
+@enduml
+```
+
+Without a matrix the structural checks already speak:
+
+```text
+UML021_DANGLING_REFERENCE (error)   GHOST is never declared
+UML020_ISOLATED_NODE      (warning) CACHE has no edge
+UML022_CYCLE              (error)   SVC → PAY → DRV → SVC
+verdict: fail
+```
+
+With the matrix from the skill body (`default: "deny"`, layers `app` over `hal`):
+
+```text
+UML023_DISALLOWED_EDGE (error)  DRV → SVC  basis=deny      (R3-no-back-edges)
+UML023_DISALLOWED_EDGE (error)  SVC → GHOST basis=unlisted (no rule allows it)
+UML024_LAYER_VIOLATION (error)  DRV (hal) → SVC (app)
+verdict: fail, disallowedEdges: 2, layerViolations: 1
+```
+
+Both `UML022` and `UML023` fire on the same back edge: the cycle is a graph property, the violation is a matrix property. Report both — they are different findings with different fixes (a cycle needs restructuring; a disallowed edge needs either the edge removed or the matrix amended deliberately).
+
+## Reconciliation with a source-side check
+
+The diagram and an include/dependency scan over the source are two representations of one fact, and they drift. Keep the rule ids identical on both sides, then classify each difference:
+
+| Difference | Reading | Action |
+|---|---|---|
+| Code has the include, diagram has no edge | The diagram is stale | Redraw; `require: true` makes this a `UML025` warning every run |
+| Diagram has the edge, code has no include | Either the diagram is aspirational, or the scan scope is narrower (generated files, `#ifdef`, build-time includes) | State which, with both citations |
+| Code violates a rule the diagram never showed | The architecture defect the diagram hid | Fix the code, or amend the rule deliberately and record why |
+| Both agree an edge is forbidden | A real violation, agreed by two methods | Act on it |
+
+Never present the diagram's clean verdict as evidence about the code: it is evidence about the drawing. The reconciliation is the part that touches the source.
+
+## Multi-granularity: one architecture at several levels
+
+A module-level diagram and the repository-level diagram it belongs to are two views of one
+fact, and nothing keeps them in step. Declare the relation and both are checked:
+
+```text
+logicprobe_structure_verify  { diagrams: [ { name, diagram, parent? }, … ] }
+logicprobe_structure_verify { diagrams: [ { name: "L1", diagram: "…", parent: "L0" }, … ] }
+```
+
+Per-diagram structural checks run first (UML020-UML026), and every finding is tagged with
+the `file` it came from, so a report over several levels never carries an anonymous
+finding. Then each declared pair is checked:
+
+| Code | Severity | What it means |
+|---|---|---|
+| `UML028_UNKNOWN_PARENT` | error | The `parent` names a diagram that is not in the set. |
+| `UML029_REFINEMENT_VIOLATION` | error | **invented-edge**: the child draws a dependency between two nodes the parent also has, but the parent does not. **unexpanded-edge**: the parent draws an edge between two nodes the child also has, the child does not draw it, and no child path connects the same ends. |
+| `UML030_PARENT_CYCLE` | error | The parent relation contains a cycle, so "which level owns this dependency" has no answer. |
+| `UML031_NO_DIAGRAMS` | error | Nothing was supplied to compare. |
+
+The rule is *refinement*, not equality: a child may add nodes and edges **below** the
+parent level (an edge with an endpoint the parent does not have is the child's own
+detail), and it may cover a **subtree** of the parent — a parent edge whose ends are not
+both present in the child is out of scope for that level, not dropped. What it may never
+do is invent a dependency at the parent level, or silently drop one it should have
+expanded.
+
+Each pair is summarised so the counts can be read without diffing two diagrams by eye:
+
+```json
+{ "parent": "L0", "child": "L1",
+  "parentNodes": 3, "childNodes": 4, "parentEdges": 2, "childEdges": 4,
+  "inheritedEdges": 1, "newEdges": 2,
+  "expandedEdges": [{ "from": "SVC", "to": "PAY", "line": 5 }],
+  "missingEdges": [], "inventedEdges": [] }
+```
+
+A parent edge the child replaces with a path is a **legitimate expansion**, and it is
+listed in `expandedEdges` rather than silently accepted: a reviewer confirms each one,
+because that is where a refactoring quietly changes who calls whom. `hashes.diagrams`
+records a sha256 per level, so a baseline diff can tell which level moved.
+
+The same discipline as the single-diagram review applies: this checks the *diagrams*
+against each other, not against the code. A level that is consistent with its parent but
+not with the code is a drawing bug; a level that disagrees with its parent is a hierarchy
+bug. Both need the source-side scan to settle.
+
+## Extracting the matrix from an existing rule table
+
+A machine-checked rule table (an include/dependency checker, a lint config, a review checklist) can seed the matrix: one rule entry per row, `id` = the row's own number so citations line up, `source`/`allow`/`deny` = the row's patterns, `layers` = the layering the table describes. Review the result before trusting it — a translation that silently widens `deny` into `allow` is worse than no check. Keep both files under version control together, and treat a matrix change as a code change.
+
+## Limits
+
+- The graph is what the diagram draws. Function pointers, DI, registries, plugins and dynamic dispatch are invisible.
+- No transitive closure unless you write the rule for it.
+- Containers (`package`, `rectangle`, `frame`) are exempt from the isolated-node check by design.
+- `STRUCTURE_IGNORED_LINE` warnings mean the parser met a statement it does not model; treat a non-empty list as a signal that the diagram family may not be the one you think it is.
+- Behaviour is out of scope: state machines, protocols, timing, budget, probability and deadlines belong to `logicprobe` (verification) and `logicprobe-uml` (the diagram round trip).

package/skills/logicprobe-uml/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: logicprobe-uml
+description: "Use when drawing a code flow as UML or auditing a diagram someone drew: parse a hand-drawn state or activity diagram, render a model, and check round-trip fidelity (dead ends, unreachable states, label drift). Component, class and ER diagrams are refused, not modelled. Doctrine and behavioural verification: the logicprobe skill."
+---
+
+# Logic Probe — UML Modelling
+
+A diagram is a model, and a model can be wrong. A tidy flow chart is not evidence about the code, and a diagram that disagrees with its own model is worse than no diagram, because a reader will believe it.
+
+This skill covers the diagram half of the Logic Probe toolbox. The claim-verification doctrine it inherits — enumerate verifiable claims, cite `file:line`, read `verdict` and never `ok` — lives in the `logicprobe` skill; load that one when the task is to verify behaviour rather than to draw or audit a diagram.
+
+## When This Skill Applies
+
+| The task involves… | What it does |
+|---|---|
+| Modelling a code flow as a state, activity or sequence diagram | `logicprobe_uml action=render`: model to diagram source, with a citation per state, event, guard and action |
+| Reading a hand-drawn diagram back into a model | `action=parse`: Mermaid or PlantUML state/activity text into a LogicModelV1 that `logicprobe_verify` can check |
+| Auditing a diagram somebody drew | `action=review`: structural defects, documentation gaps, and render-versus-model round-trip fidelity |
+| A diagram whose claims must be tied to the code | Every element needs a source citation; the review says what the diagram says, not whether the code is correct |
+
+Pipeline (DSH):
+
+```text
+code flow → model (citation per element) → logicprobe_uml action=render → diagram source
+          → logicprobe_uml action=review → modelling findings + round-trip fidelity
+          → logicprobe_verify           → behaviour (S1-S8 structural, A1-A14 adversarial)
+```
+
+- **render** — model to diagram. Mermaid covers `state`, `activity` and `sequence`. PlantUML covers `state` and `sequence`. Any construct the notation cannot carry becomes a warning, never a silent drop. PlantUML activity is refused instead of approximated.
+- **parse** — diagram to model. It reads Mermaid and PlantUML state or activity text, so a hand-drawn diagram can be verified like any other model. Two inputs are refused because they cannot become a machine: a sequence diagram (a trace cannot reconstruct a machine) and a different Mermaid family (`classDiagram`, `erDiagram`, `gantt`, `mindmap`, …) — both come back as `errorCode: "UML_NOT_A_STATE_DIAGRAM"` with the discarded construct named.
+- **review** — it answers one of three questions. Give it a model: is the machine well-modelled? Give it a diagram: what does the diagram say? Give it both: does the diagram match the model?
+
+A host without the tools runs the same three actions through the repository engine. The engine is deliberately single-source — do not copy it into this skill.
+
+## A Structure Diagram Is the Dangerous Case, Because It Parses
+
+PlantUML component, package, class and deployment diagrams declare no diagram kind, so the parser meets their keywords line by line. It still returns *something* — the arrows look like transitions — so `parse` reports the by-product model **plus** an error finding `UML_NOT_A_STATE_DIAGRAM`, the declarations it could not represent in `discardedConstructs` (with line and text), the arrows that were misread in `discardedEdges`, and `verdict: "fail"`.
+
+Read that as: **there is no model of this file; the diagram was not checked.** Do not feed that model to `logicprobe_verify` and call the result a review of the architecture, and do not present a component diagram as evidence about dependencies. A structure diagram has its own reviewer: the `logicprobe-structure` skill and the `logicprobe_structure_verify` tool parse the same text into a real dependency graph and check isolated nodes, dangling endpoints, cycles, allowed-dependency and layer violations (`UML020`-`UML026`). Use that one when the question is *where the dependencies point*.
+
+Mermaid families with an explicit header (`classDiagram`, `erDiagram`, `gantt`, …) are refused outright, because an empty model would be worse than no model.
+
+## What the Review Reports
+
+Structural defects: unreachable states, dead ends, ambiguous or non-exhaustive branches, self-loops with no exit, duplicate transitions. Documentation gaps: a missing narrative, unbounded variables, states the reader cannot map back to code, and label drift between diagram and narrative. It also runs the fidelity check — any structural difference between the diagram and its model is `UML017_ROUND_TRIP_MISMATCH`.
+
+## Rules for This Mode
+
+1. **A diagram is not evidence.** Every state, event, guard and action needs a citation. Use `file:line` for code and a section reference for a document. Present the citations with the diagram.
+2. **Review before you present.** Run `logicprobe_uml action=review` and fix the error findings first. An ambiguous or dead-ended diagram misleads every later reader.
+3. **Check the verdict before the picture.** `ok: true` with `verdict: "fail"` means the review failed; a diagram whose review failed is not something to show as if it were checked.
+4. **The review never replaces verification.** It covers the modelling. S1-S8 and A1-A14 cover the behaviour, and each finding names the check that settles it — hand those over to the `logicprobe` skill.
+5. **Keep the narrative with the model.** Write `narrative.states`, `narrative.events` and `narrative.scenarios`. Then the diagram stays readable against the code, and label drift shows up as a finding instead of as a stale picture.
+
+The full checklist (codes `UML001` to `UML019` plus `UML_NOT_A_STATE_DIAGRAM`), the directive format generated diagrams carry, a worked example, and the limits of each view are in [`references/uml-modeling-guide.md`](references/uml-modeling-guide.md).

package/skills/{logicprobe → logicprobe-uml}/references/uml-modeling-guide.md

@@ -28,7 +28,7 @@ One machine, three projections. They are not interchangeable. The review reports
 
 ## Modelling a code flow from source
 
-Extraction follows the same discipline as `logic-verification-guide.md`, applied to code instead of a plan.
+Extraction follows the same discipline as `logic-verification-guide.md`, applied to code instead of a plan. That guide ships with the entry-point skill: `../logicprobe/references/logic-verification-guide.md`.
 
 1. **Fix the boundary.** Decide which function, task, or module is the machine. In scope: state the code holds across calls, such as statics, fields, enums, and task state variables. Out of scope: the call stack inside one invocation, hardware behaviour, and scheduler preemption.
 2. **Name the states from the code.** A state exists if something survives a call boundary and is tested later. An enum, a `state` field, or a task-local variable that gates the next entry all qualify. A local variable inside one function does not.
@@ -55,11 +55,7 @@ In DSH:
 
 `logicprobe_uml` with `action=render` returns the diagram source plus `warnings`. Read those warnings. They list every construct the notation could not carry verbatim: a state id that needed an alias, a label containing `[` or `/`, a trace that was capped.
 
-Without the DSH tool, run the standalone engine:
-
-```bash
-python skills/logicprobe/references/logicprobe-engine.py uml-render model.json --notation mermaid --diagram state
-```
+Without the DSH tool, run the repository engine on the same model JSON.
 
 You can also write the diagram by hand. The generator is a convenience, not a requirement. A hand-written diagram is parsed and reviewed exactly like a generated one.
 
@@ -99,6 +95,7 @@ Four input shapes, four different questions:
 | Code | Severity | What it means |
 |---|---|---|
 | `UML001_DIAGRAM_UNREADABLE` | error | The text is not readable as a Mermaid or PlantUML state or activity diagram. |
+| `UML_NOT_A_STATE_DIAGRAM` | error | The text belongs to another diagram family. Numbers are reserved for `UML0xx` modelling findings, so this one carries a name instead; see [Structure diagrams are not models](#structure-diagrams-are-not-models). |
 | `UML002_UNREACHABLE_STATE` | error | No transition can enter this state from init. The diagram draws flow nobody can reach. The check is structural and ignores guards; S1 is the guard-aware check. |
 | `UML003_DEAD_END_STATE` | error | A non-terminal state has no outgoing transition. Either it is terminal, or the outgoing flow was never modelled. |
 | `UML004_AMBIGUOUS_BRANCH` | error | Two unconditional arrows share one state and event. No reader and no implementation can resolve that. S4 is the authoritative check. |
@@ -110,7 +107,8 @@ Four input shapes, four different questions:
 | `UML010_UNUSED_VARIABLE` | warning | No guard reads this variable and no action writes it. It is a symbol with no source. |
 | `UML011_UNBOUNDED_VARIABLE` | info | An integer variable has no min or max, so no range invariant can be checked and A5 has no declared domain. |
 | `UML012_NO_TERMINAL` | warning | No state is terminal, so completion, failure and a stuck flow all look the same. |
-| `UML013_NO_NARRATIVE` | info | The model carries no meanings, so a reader must re-derive every symbol from the source. |
+| `UML013_NO_NARRATIVE` | info | The model carries no meanings, so a reader must re-derive every symbol from the source. Adding a partial narrative is a valid first step. |
+| `UML027_NARRATIVE_PARTIAL` | info | The narrative covers part of the model. `narrativeCoverage` (also in the finding's `evidence`) reports `covered/total` per dimension — states, events, scenarios. Incomplete is not wrong. |
 | `UML014_UNDOCUMENTED_STATE` | info | These states render as their bare id, so the diagram cannot be read against the code. |
 | `UML015_LABEL_DRIFT` | warning | A diagram label disagrees with the model narrative. One of the two is stale, and the review cannot tell which. |
 | `UML016_DIAGRAM_PARSE_NOTES` | info | Notes collected while rendering or reading the diagram. They mark information the notation could not carry. |
@@ -118,7 +116,77 @@ Four input shapes, four different questions:
 | `UML018_FIDELITY_UNCHECKED` | info | Only a diagram was supplied, so nothing here proves it matches the code. |
 | `UML019_ROUND_TRIP_SKIPPED` | warning | The fidelity check could not run, either because the view is not round-trippable or because it was switched off. |
 
-`ok: true` means the review ran. It does not mean the model is good. Read the findings and the `summary` counts.
+`ok: true` means the review ran. It does not mean the model is good. Read `verdict`, not `ok`:
+
+| `verdict` | What it means | What to do |
+|---|---|---|
+| `pass` | No error and no warning finding. | Safe to present, with the scope the model covers. |
+| `pass_with_findings` | No error finding, but warnings exist (e.g. `UML012_NO_TERMINAL`, `UML006`). | Present the pass **and** the warnings; do not upgrade it to "no issues". |
+| `fail` | An error finding exists (`UML002`, `UML003`, `UML004`, `UML017`, `UML_NOT_A_STATE_DIAGRAM`, …) or the diagram could not be read (`ok: false`). | The diagram is **not** reviewed. Fix the error findings, or stop calling the file a model. |
+
+`verdictReason` states why in one line (`2 error finding(s) (first: UML002_UNREACHABLE_STATE)`).
+The non-DSH CLI (`uml-review`, `uml-parse`) exits `2` when the verdict is `fail` or the
+input is refused, `0` otherwise.
+
+### Structure diagrams are not models
+
+This is the failure mode worth a section of its own, because it does not look like a failure.
+
+A PlantUML component, package, class or deployment diagram declares no diagram kind —
+it simply starts with `@startuml`. A state parser therefore meets its keywords line by
+line, ignores the words it does not know, and reads the arrows as state transitions:
+
+```plantuml
+@startuml
+component [Order Service] as SVC
+component [Payment Adapter] as PAY
+package "HAL" {
+  component [Storage Driver] as DRV
+}
+SVC --> PAY : request
+PAY --> DRV : read
+@enduml
+```
+
+Before this contract existed, that parsed to `ok: true` with three "states" and two
+"transitions", and "the structure diagram was reviewed" was pure fabrication. Now the
+same input returns the by-product **plus**:
+
+```json
+{
+  "verdict": "fail",
+  "findings": [{ "code": "UML_NOT_A_STATE_DIAGRAM", "severity": "error",
+                 "message": "the text is not a state or activity diagram: 4 declaration(s) of unsupported construct(s) (component ×3, package ×1) and 2 arrow(s) between them were read as states and transitions, so the parsed model is not this diagram." }],
+  "discardedConstructs": [{ "construct": "component", "line": 2, "text": "component [Order Service] as SVC" }, "…"],
+  "discardedEdges": 2
+}
+```
+
+Read that as: **there is no model of this file.** Do not feed the by-product to
+`logicprobe_verify` and call the result an architecture review, and do not quote its
+"states" as dependencies. `discardedConstructs` lists every declaration that could not
+be represented (with its line and text), and `discardedEdges` counts the arrows between
+them that were misread.
+
+Mermaid families with an explicit header — `classDiagram`, `erDiagram`, `gantt`,
+`journey`, `mindmap`, `gitGraph`, `C4*`, `requirementDiagram`, `timeline`,
+`quadrantChart`, `sankey-beta`, `block-beta`, `packet-beta`, `architecture-beta`,
+`radar-beta`, `treemap-beta`, `xychart-beta` — are refused instead, because an empty
+model would be worse than no model: the tool returns `ok: false` with
+`errorCode: "UML_NOT_A_STATE_DIAGRAM"` naming the family, and `review` reports it as
+`UML001_DIAGRAM_UNREADABLE`. Sequence diagrams are in the same class of refusal, for a
+different reason (a trace cannot reconstruct a machine).
+
+Both routes are non-pass and both name what was discarded. What the tool will **not**
+do is hand back a plausible model with no verdict — that is the false guarantee.
+
+**A structure diagram has its own reviewer.** Dependency-graph checks — isolated
+nodes (`UML020`), dangling endpoints (`UML021`), cycles (`UML022`), disallowed edges
+and layer violations against an allowed-dependency matrix (`UML023`, `UML024`) and
+required-but-absent edges (`UML025`) — are implemented by the `logicprobe-structure`
+skill and the `logicprobe_structure_verify` tool, which parse the same component,
+package, class and deployment text into a real node/edge graph instead of discarding
+it. Use that for architecture questions; this guide is about the state-machine half.
 
 ### What the round trip proves
 
@@ -156,6 +224,50 @@ Neither is a behaviour bug. Add the narrative so a reader can check the diagram
 
 Now delete the `ERROR --cooldown--> STARTING` arrow and review again. `ACTIVE` and `ERROR` become dead ends (`UML003`), and `cooldown` becomes an event that only fires from an unreachable state (`UML007`). The diagram still looks plausible. That is the whole point.
 
+## Labels and comments: what the parser expects
+
+Two things cause most of the friction with hand-written diagrams. Both are printed by the
+tool itself: `logicprobe_uml` does not have a flag for it (it documents the convention in
+its description), and the CLI has `uml-review --explain-labels` (add `--notation
+plantuml` for that flavour), which prints exactly the table below from the same rules the
+parser applies.
+
+**1. State meanings, in the spellings the parser accepts.** A label carries a *meaning*
+when it differs from the bare id. Accepted, in this order:
+
+| Spelling | Example | Notes |
+|---|---|---|
+| bare id | `state "IDLE" as IDLE` | counts as **no** meaning: the state is reported undocumented (`UML014`) |
+| `ID（meaning）` | `state "IDLE（waiting for power）" as IDLE` | what the renderer writes; full-width parentheses |
+| `ID(meaning)` | `state "IDLE(waiting for power)" as IDLE` | accepted as well |
+| a description line | `IDLE : waiting for power` | the same meaning in the other PlantUML spelling |
+| a single-line note | `note right of IDLE : waiting for power` | read as the meaning, not as a comment |
+| any other text | `state "waiting for power" as IDLE` | taken verbatim |
+
+`UML015_LABEL_DRIFT` compares the *meaning* with `narrative.states[id]` character for
+character: the wrapper (`ID（…）`) is stripped, the rest must match. A different wording is
+still drift — the review cannot tell which side is stale. Writing no label is not drift;
+it is `UML014_UNDOCUMENTED_STATE` (info).
+
+**2. Comment lines.** The only comment lines the parser *consumes* are the `logicprobe:`
+directives the renderer writes (`%%logicprobe:` in Mermaid, `'logicprobe:` in PlantUML):
+`uml v1 …`, `init ID`, `terminal ID`, `alias X id`, `variable NAME kind`. They are
+ordinary comments to every renderer, which is why the diagram stays valid.
+
+Everything else is either notation chrome (skipped silently) or an ignored line:
+
+| Line | Behaviour |
+|---|---|
+| a `%%` / `'` comment that is not a directive | `UML_PARSE_IGNORED_LINE` warning — the line carried no statement |
+| a multi-line `note … end note` block | skipped silently (prose is not a state meaning) |
+| `@startuml`/`@enduml`, `stateDiagram-v2`, `direction`, `classDef`/`style`/`linkStyle`/`click`, `scale`, `skinparam`, `title`, `hide`, `autonumber` | skipped silently |
+| anything else the parser cannot read | `UML_PARSE_IGNORED_LINE` warning, and the model is built from what it did read |
+
+So the practical rule is: keep non-directive comments out of the diagram body (put render
+commands and explanations around the diagram, not inside it), and give every state a
+`ID（meaning）` label when the model carries a narrative — otherwise the diagram compares
+as undocumented and a later drift check has nothing to compare against.
+
 ## Limits
 
 - The review is **structural**. It evaluates no guard over any valuation. "Probably exhaustive" is a shape test, not a proof. S6 is the check that decides.

package/src/baseline.ts

@@ -0,0 +1,180 @@
+/**
+ * Report diffing: "did this slice add findings, or remove them?"
+ *
+ * The acceptance criterion of a refactoring slice is usually *not* "zero findings" —
+ * it is "no NEW findings, and none of the old ones got worse". Comparing two JSON
+ * reports by hand is how that gets fudged, so the comparison is code.
+ *
+ * A finding's identity is its machine-readable locator, never its prose:
+ * `check|code|<canonical evidence + path>`. Findings that carry neither evidence nor a
+ * path fall back to their message, because an engine that reports nothing structured
+ * has nothing stabler to match on. Two runs over the same input must produce zero
+ * added and zero removed findings.
+ *
+ * @module logicprobe-baseline
+ */
+
+import { canonicalJson, REPORT_SCHEMAS, verdictOf, type Finding, type Verdict, type VerdictSummary } from './engine.js'
+
+/** A finding as it appears in any report family, after flattening. */
+export interface ReportFinding extends Finding {
+  /** The check that emitted it (verify/datamodel: `S2`, `C1`, …); absent for flat families. */
+  check?: string
+}
+
+export interface BaselineChange {
+  identity: string
+  code: string
+  before: { severity: string; message: string }
+  after: { severity: string; message: string }
+}
+
+export interface BaselineReport {
+  ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: string
+  /** The current report's own verdict, echoed so "no new findings" cannot hide a failing run. */
+  currentVerdict: Verdict
+  added: ReportFinding[]
+  removed: ReportFinding[]
+  changed: BaselineChange[]
+  summary: {
+    baseline: number
+    current: number
+    added: number
+    removed: number
+    changed: number
+    addedErrors: number
+    addedWarnings: number
+  }
+  nextSteps: string[]
+}
+
+/**
+ * The stable identity of a finding: check + file + code + a canonical locator. Prose is
+ * excluded so a reworded message reads as `changed`, not as a new finding.
+ */
+export function findingIdentity(finding: ReportFinding): string {
+  const locator = canonicalJson({
+    ...(finding.evidence === undefined ? {} : { evidence: finding.evidence }),
+    ...(finding.path === undefined ? {} : { path: finding.path }),
+  })
+  const where = locator === '{}' ? 'message:' + finding.message : locator
+  const file = finding.file === undefined ? '' : finding.file + '|'
+  return (finding.check === undefined ? '' : finding.check + '|') + file + finding.code + '|' + where
+}
+
+/** Flatten a report of any family into one finding list (`checks[].findings` or `findings[]`). */
+export function flattenReportFindings(report: unknown): ReportFinding[] {
+  if (report === null || typeof report !== 'object') return []
+  const record = report as Record<string, unknown>
+  const flat: ReportFinding[] = []
+  if (Array.isArray(record.checks)) {
+    for (const check of record.checks as Array<Record<string, unknown>>) {
+      const id = typeof check.id === 'string' ? check.id : undefined
+      for (const finding of (Array.isArray(check.findings) ? check.findings : []) as Finding[]) {
+        flat.push(id === undefined ? finding : { ...finding, check: id })
+      }
+    }
+  }
+  if (Array.isArray(record.findings)) {
+    for (const finding of record.findings as Finding[]) flat.push(finding)
+  }
+  return flat
+}
+
+/** The report's own verdict, whatever family it came from. */
+function verdictOfReport(report: unknown): Verdict {
+  if (report === null || typeof report !== 'object') return 'fail'
+  const value = (report as Record<string, unknown>).verdict
+  return value === 'pass' || value === 'pass_with_findings' || value === 'fail' ? value : 'fail'
+}
+
+function diffOf(added: number, removed: number, addedErrors: number, firstCode?: string): VerdictSummary {
+  if (addedErrors > 0) {
+    return {
+      verdict: 'fail',
+      verdictReason: String(added) + ' new finding(s) (' + String(addedErrors) + ' error)' + (firstCode === undefined ? '' : ' (first: ' + firstCode + ')'),
+    }
+  }
+  if (added > 0) {
+    return { verdict: 'pass_with_findings', verdictReason: String(added) + ' new warning finding(s), no new errors' }
+  }
+  if (removed > 0) {
+    return { verdict: 'pass', verdictReason: 'no new findings; ' + String(removed) + ' finding(s) resolved' }
+  }
+  return { verdict: 'pass', verdictReason: 'no new findings, nothing resolved' }
+}
+
+/**
+ * Compare a baseline report with the current one. The verdict describes the *delta*
+ * (a new error fails it), while `currentVerdict` keeps the absolute result visible.
+ */
+export function diffReports(baseline: unknown, current: unknown): BaselineReport {
+  const before = flattenReportFindings(baseline)
+  const after = flattenReportFindings(current)
+  const beforeByIdentity = new Map<string, ReportFinding>()
+  for (const finding of before) beforeByIdentity.set(findingIdentity(finding), finding)
+  const seen = new Set<string>()
+  const added: ReportFinding[] = []
+  const changed: BaselineChange[] = []
+  for (const finding of after) {
+    const identity = findingIdentity(finding)
+    seen.add(identity)
+    const previous = beforeByIdentity.get(identity)
+    if (previous === undefined) {
+      added.push(finding)
+      continue
+    }
+    if (previous.severity !== finding.severity || previous.message !== finding.message) {
+      changed.push({
+        identity,
+        code: finding.code,
+        before: { severity: previous.severity, message: previous.message },
+        after: { severity: finding.severity, message: finding.message },
+      })
+    }
+  }
+  const removed = before.filter((finding) => !seen.has(findingIdentity(finding)))
+  const addedErrors = added.filter((finding) => finding.severity === 'error')
+  const addedWarnings = added.filter((finding) => finding.severity === 'warning')
+  const delta = diffOf(added.length, removed.length, addedErrors.length, addedErrors[0]?.code)
+
+  const nextSteps: string[] = []
+  if (addedErrors.length > 0) {
+    nextSteps.push('Fix or explicitly accept the ' + String(addedErrors.length) + ' new error finding(s) before calling this slice done: the baseline is what "not worse" is measured against.')
+  } else if (added.length > 0) {
+    nextSteps.push('The new warnings are not failures, but they are new: decide per finding whether the change introduced them or the baseline was incomplete.')
+  } else {
+    nextSteps.push('No new findings: re-record the baseline with this report if the slice is accepted, so the next comparison starts from it.')
+  }
+  if (changed.length > 0) nextSteps.push('Review the ' + String(changed.length) + ' changed finding(s): the same locator now reports something different, which usually means the fix moved the problem.')
+  if (removed.length > 0) nextSteps.push(String(removed.length) + ' finding(s) from the baseline are gone — confirm they were fixed rather than renamed out of the report (a renamed check or a reworded message changes the identity).')
+  if (verdictOfReport(current) === 'fail') nextSteps.push('The current report still fails on its own terms; the delta being clean does not make the run clean.')
+
+  return {
+    ok: true,
+    ran: true,
+    ...delta,
+    schema: REPORT_SCHEMAS.baseline,
+    currentVerdict: verdictOfReport(current),
+    added,
+    removed,
+    changed,
+    summary: {
+      baseline: before.length,
+      current: after.length,
+      added: added.length,
+      removed: removed.length,
+      changed: changed.length,
+      addedErrors: addedErrors.length,
+      addedWarnings: addedWarnings.length,
+    },
+    nextSteps,
+  }
+}
+
+export type { VerdictSummary }

package/src/client.js

@@ -30,7 +30,61 @@ window.__ModuleLoader__.load({
   id: 'dsh-logicprobe',
   factory: (require) => {
     const React = require('react')
-    const { Button, Switch } = require('@deepseek-ai/dsh-client-ui-primitives')
+    // The host's Switch and Button, vendored. A plain-JS client bundle must not
+    // require a Harness Client package: it changes without notice, we get no type
+    // check, and a throw blanks this slot entry. Markup, classes, token usage and
+    // the aria behaviour follow the host primitive; classes carry our own prefix.
+    const CONTROLS_CSS = [
+      '.lp-switch { box-sizing: border-box; position: relative; flex: 0 0 auto; width: 36px; height: 20px; padding: 2px; border: 0; border-radius: 999px; corner-shape: round; background: var(--dsw-alias-border-l3); cursor: pointer; }',
+      ".lp-switch[aria-checked='true'] { background: var(--dsw-alias-brand-primary); }",
+      '.lp-switch:disabled { cursor: default; opacity: 0.5; }',
+      '.lp-switch:focus-visible { outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); outline-offset: 2px; }',
+      '.lp-switch-thumb { display: block; width: 16px; height: 16px; border-radius: 50%; corner-shape: round; background: var(--dsw-alias-label-primary-foreground); transition: transform 120ms ease; }',
+      ".lp-switch[aria-checked='false'] .lp-switch-thumb { background: var(--dsw-alias-switch-thumb); }",
+      ".lp-switch[aria-checked='true'] .lp-switch-thumb { transform: translateX(16px); }",
+      '.lp-btn { box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 4px; border: none; border-radius: var(--dsw-radius-md); cursor: pointer; font-size: 14px; line-height: 22px; color: var(--dsw-alias-label-primary); background: transparent; padding: 0 14px; }',
+      '.lp-btn:disabled { cursor: not-allowed; opacity: 0.4; }',
+      '.lp-btn-sm { height: 28px; font-size: 12px; line-height: 18px; padding: 0 10px; border-radius: var(--dsw-radius-sm); }',
+      '.lp-btn-outline { border: 0.5px solid var(--dsw-alias-border-l3); background: transparent; }',
+      '.lp-btn-outline:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); }',
+    ].join('\n')
+
+    /** Rendered inside the component tree, so unmounting removes the styles. */
+    function Controls() {
+      return React.createElement('style', null, CONTROLS_CSS)
+    }
+
+    function Switch(props) {
+      return React.createElement(
+        'button',
+        {
+          type: 'button',
+          role: 'switch',
+          'aria-checked': props.checked === true,
+          'aria-label': props.label,
+          className: 'lp-switch',
+          disabled: props.disabled === true,
+          onClick: () => {
+            if (props.disabled !== true) props.onChange(!(props.checked === true))
+          },
+        },
+        React.createElement('span', { className: 'lp-switch-thumb' }),
+      )
+    }
+
+    Switch.displayName = 'dsh-logicprobe:Switch'
+    Button.displayName = 'dsh-logicprobe:Button'
+
+    function Button(props) {
+      const classes = ['lp-btn']
+      if (props.size === 'sm') classes.push('lp-btn-sm')
+      if (props.variant === 'outline') classes.push('lp-btn-outline')
+      return React.createElement(
+        'button',
+        { type: 'button', className: classes.join(' '), disabled: props.disabled === true, onClick: props.onClick },
+        props.children,
+      )
+    }
 
     /** Settings namespace: the Loader entry id this bundle's patch declares. */
     const NS = 'logicprobe'
@@ -122,6 +176,7 @@ window.__ModuleLoader__.load({
       const locked = state.writable !== true || pending
 
       const children = [
+        React.createElement(Controls, { key: 'styles' }),
         React.createElement('h4', { key: 'title', style: TITLE }, t('title')),
         React.createElement('div', { key: 'row', style: ROW }, [
           React.createElement('span', { key: 'label', style: LABEL }, t('label')),