dsh-logicprobe 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-logicprobe",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Verifies claims about designs and code. Facts go against the source. Behaviour goes through an executable model: state machines, protocols, composition, data models, migrations. Structure diagrams are read as dependency graphs, at one level or several. Two reports can be compared for regression. Exports UPPAAL, TLA+, PRISM and SPIN input. Ships a native DeepSeek Harness bundle that injects the verification gate into the first model step.",
   "type": "module",
   "main": "lib/index.js",

package/skills/logicprobe/SKILL.md

@@ -170,7 +170,7 @@ UML modelling variant (the task is to draw a flow, not to check a claim):
 | `logicprobe_compose_verify` | Two or more machines checked together (rendezvous handshake semantics): C1 composition deadlock, C2 rendezvous never fires. |
 | `logicprobe_concurrency_scan` | Mines concurrency claims (thread-safe, lock-free, race condition, mutex, ISR-safe) and routes them to dedicated verification. It does not prove concurrency safety. |
 | `logicprobe_export` | Emits external-checker input from a verified model: UPPAAL, TLA+, PRISM, SPIN. |
-| `logicprobe_uml` | render / parse / review for UML modelling — the diagram domain belongs to the `logicprobe-uml` skill. |
+| `logicprobe_uml` | render / parse / review / explain-labels for UML modelling — the diagram domain belongs to the `logicprobe-uml` skill. |
 
 The repository engine mirrors the same checks and carries the `compose` and `export` subcommands for hosts without the native tools.
 
@@ -189,7 +189,7 @@ Every tool report carries the same outcome contract. **`ok` says a report was pr
 | `hashes` | Every hash the report carries, in one place (a model hash, a diagram hash, before/after hashes). |
 | `nextSteps[]` | What to do next, derived from the findings; never empty, and identical for two runs over the same input. |
 | `metadataKeys[]` | Paths of the `_`-prefixed annotation keys the schema ignored, e.g. `["_source", "_verified", "states[0]._note"]` (present only when the input carried any). |
-| `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}` when the model carries a narrative — a partial narrative is valid, and this is how much is still undocumented. |
+| `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}` when the model carries a narrative — a partial narrative is valid, and this is how much is still undocumented. The gap is also a `NARRATIVE_PARTIAL` (info) finding, so a gate can read it without parsing `nextSteps` text. |
 
 Turn the verdict into an answer, never into a summary of `ok`:
 
@@ -395,7 +395,7 @@ This skill owns behavioural claims. Three neighbouring domains have their own sk
 
 | Domain | Skill |
 |---|---|
-| Drawing a code flow as UML, or auditing a diagram somebody drew (render / parse / review, round-trip fidelity, component and class diagrams refused) | `logicprobe-uml` |
+| Drawing a code flow as UML, or auditing a diagram somebody drew (render / parse / review / explain-labels, round-trip fidelity, component and class diagrams refused) | `logicprobe-uml` |
 | Reviewing architecture, module structure or a dependency diagram (isolated nodes, dangling endpoints, cycles, allowed-dependency and layer violations, missing required edges) | `logicprobe-structure` |
 | Concurrency claims — "thread-safe", "lock-free", "no data race", "ISR-safe" — mined and routed to TSan/Helgrind/CBMC/TLA+, never proven here | `logicprobe-concurrency` |
 | Entities, fields, relationships, data invariants, schema migrations (DS1-DS4, DA1-DA12, DD1-DD4) | `logicprobe-datamodel` |

package/skills/logicprobe/references/dsh-model-schema.md

@@ -77,6 +77,13 @@ it, and the report lists it under `metadataKeys`:
 "metadataKeys": ["_extraction_caveats", "_source", "_verified", "states[0]._note"]
 ```
 
+The list echoes *this input*, it is not a memory: a `_` key the current object does not
+carry is absent, even if an earlier version of the file had it. Nested keys are spelled
+the way the walker sees them (`states[0]._note`, `invariants[0]._probe`,
+`transitions[0]._why`), and the field is absent entirely when the input carries no `_`
+key at all. Read it as "what this run ignored", never as "what this model has ever
+recorded".
+
 Why it exists: provenance, verification snapshots and extraction caveats belong *with*
 the model. Pushed into a sidecar they drift away from it — nobody can say which hash
 belongs to which note. With this exemption the archive record travels inside the file
@@ -166,7 +173,7 @@ block is valid. What must hold is that whatever is written is *right*:
 | Case | Result |
 |---|---|
 | `narrative` absent | Valid. The review reports `UML013_NO_NARRATIVE` (info); `logicprobe_verify` reports no coverage at all. |
-| One or two of `states` / `events` / `scenarios` given | Valid. The report adds `narrativeCoverage: {states: "5/5", events: "3/9", scenarios: "0/12"}` (covered/total per dimension), and `nextSteps` names the gap. A `UML027_NARRATIVE_PARTIAL` (info) finding appears in a UML review. |
+| One or two of `states` / `events` / `scenarios` given | Valid. The report adds `narrativeCoverage: {states: "5/5", events: "3/9", scenarios: "0/12"}` (covered/total per dimension), and `nextSteps` names the gap. Both sides also report it as a finding: `logicprobe_verify` carries `NARRATIVE_PARTIAL` (info) and a UML review carries `UML027_NARRATIVE_PARTIAL` (info). An `info` finding never changes `verdict`, `summary.errors`, `summary.warnings` or the check count. |
 | `narrative` present but `{}` | **Error**: an empty block claims documentation that does not exist. Give at least one dimension. |
 | Unknown state/event id, empty description, duplicate `(from, event)` scenario | **Error**: the narrative is wrong, not merely incomplete. |
 
@@ -220,6 +227,13 @@ A guard is exactly one of:
 
 ## Invariants
 
+Every invariant carries `id` and **`description`** — both required strings — plus a
+`kind` and that kind's own fields. `description` is not decoration: it is echoed into
+the finding a violation produces, and it takes part in `modelHash`, so a model that
+gains one hashes differently. An invariant without it is rejected with `MODEL_INVALID`,
+and the report's `nextSteps` names the field to add; a `_`-prefixed key is not a
+substitute for it.
+
 | Kind | Shape | Checks |
 |---|---|---|
 | `never-states` | `{ states: ["ERROR"] }` | No reachable runtime state may be in the forbidden set |
@@ -314,6 +328,13 @@ Two or more machines can be checked together with `runCompositionVerification` (
 - non-rendezvous events advance exactly one firing machine;
 - a rendezvous (handshake) event fires only when at least two machines declare it **and** every such non-terminal machine has it jointly enabled (guards held); participants advance simultaneously. A machine whose alphabet does not contain the event does not participate, and a terminal machine is stopped;
 - therefore a machine that is *waiting* for a rendezvous is not blocked from everything else: it may take any number of its own non-rendezvous steps first. That is how different rates are modelled — there is **no rate ratio** and no fairness bound, so "the 1 ms pump runs N times while the ISR waits" is expressed by the pump's own tick event, not by a tempo setting. A bound would only prune interleavings, never add behaviour; if you need to *forbid* a fast machine from overtaking, encode that in the model (a guard on a counter the slow machine resets), not in the composition options.
+- **there is no cross-machine shared state.** Each machine's `variables` are private to
+  it: machine A's `ready` and machine B's `ready` are two different
+  quantities, and no guard can read another machine's variable. Rendezvous events are
+  the *only* coupling between machines. So "two machines must agree on one predicate"
+  cannot be modelled by giving each a copy of it — model the shared condition inside a
+  single machine, or make the agreement an explicit handshake. The report names the
+  variables it saw when two or more machines each declare some, in `nextSteps`.
 
 Inputs: the DSH tool takes an array of model objects (an agent reads the files and passes them); the CLI takes any number of files directly — `compose models/*.json --rendezvous req,ack` — so nothing has to be concatenated by hand.
 
@@ -321,8 +342,8 @@ Inputs: the DSH tool takes an array of model objects (an agent reads the files a
 
 Both findings carry the *why*, not just the *what*:
 
-- **C1_COMPOSITION_DEADLOCK** — the composite state, the number of steps to reach it (**shortest**, because the search is breadth-first), and `evidence.perMachine`: for every machine, its state, whether it is terminal, and every event in its alphabet with a reason — `rendezvous-needs-partner` (fewer than two machines declare it), `rendezvous-partner-not-ready` (a declaring partner is terminal or has no enabled transition), `no-enabled-transition` (guard false or no such transition), or `enabled`. An event this machine can fire on its own is never labelled `enabled` when the handshake itself is missing.
-- **C2_RENDEZVOUS_NEVER_FIRES** — `evidence.machines` gives, per machine, whether it declares the event, whether it ever had it enabled, and the states where it did. The reason distinguishes "fewer than two machines declare it" from "machine *i* declares it but never enables it".
+- **C1_COMPOSITION_DEADLOCK** — the composite state, the number of steps to reach it (**shortest**, because the search is breadth-first), and `evidence.perMachine`: for every machine, its state, whether it is terminal, and every event in its alphabet with a reason — `rendezvous-needs-partner` (fewer than two machines declare it), `rendezvous-partner-not-ready` (a declaring partner is terminal or has no enabled transition), `no-enabled-transition` (guard false or no such transition), or `enabled`. An event this machine can fire on its own is never labelled `enabled` when the handshake itself is missing. In practice a census only ever shows the three blocked reasons: it is emitted only when no machine can move, and "can move" is decided by the same predicate that would label an event `enabled`, so that fourth label is unreachable there. Treat the three observable values as the contract, and keep tolerating the literal.
+- **C2_RENDEZVOUS_NEVER_FIRES** — an **error**, the same severity as C1: a handshake that can never fire leaves the composition unable to advance through it, so a gate that reads only `verdict` stops on it. `evidence.machines` gives, per machine, whether it declares the event, whether it ever had it enabled, and the states where it did. The reason distinguishes "fewer than two machines declare it" from "machine *i* declares it but never enables it".
 
 `maxStates` caps the product space, and the cap is **reported, never hidden**: a truncated run cannot claim "no deadlock reachable" (the C1 check detail says so), and a C2 finding gained under truncation carries "may be an artefact of the cap" in its message. Bump `maxStates` before believing a negative result on a large product. Note that a machine with an unbounded counter produces an infinite composite space and will always truncate.
 

package/skills/logicprobe/references/hash-spec.md

@@ -69,6 +69,13 @@ Round-trip reports (`logicprobe_uml action=review`, `roundTrip`) carry `hashSpec
 alongside `modelHash` and `parsedHash`, so a fidelity comparison is always
 spec-qualified.
 
+**Read `diffs`, not `ok`.** `roundTrip.ok` says only that the model was rendered and the
+result read back; it is `true` while `modelHash` and `parsedHash` legitimately differ,
+because the model hash covers what a diagram cannot carry (the `narrative` block, in
+particular) and the parsed hash covers what the diagram actually says. Fidelity is
+`roundTrip.diffs.length === 0`. Equal hashes are neither necessary nor sufficient for
+fidelity, and the two must not be forced to agree.
+
 Every report also aggregates its hashes under `hashes`, so a baseline diff or an archive
 record reads one field instead of walking the report:
 
@@ -83,6 +90,24 @@ dependency matrix was supplied. A data-model report carries `hashes.modelHash`;
 data-model hash uses the same normalization but its schema is not covered by the
 published specification.
 
+A `diagram` hash is a **text** hash, not a semantic one: `sha256` over the exact
+characters, so comments and `note` blocks change it, and so does a trailing newline.
+Two renderings that mean the same thing hash differently when their text differs, and
+that is intended — it is what makes "the diagram I reviewed" checkable. For one model
+(`modelHash` `77a43a39822147707229638515cf8f0c6bef4b08635ea6197d2181fc6c26f0b4`) four
+probe variants hash as:
+
+| Diagram text | `hashes.diagram` |
+|--------------|------------------|
+| clean | `25ee1d0b803c9477d526d92c1dbb9059e408e282e515499dba06d14630286c8d` |
+| one `%%` comment line | `8c41f046c954e1dc086eee8bd24c3d1d033b489840895520002c1e8120dda052` |
+| one `'` comment line (PlantUML style) | `5552a91a73972edb71ea98f460fa6a393c6556bd1241461f0f29cd51531e9e56` |
+| one multi-line `note … end note` block | `359182313f451713a937f5148328d238e8ea1941fbcef663c4c34e0a7f1bbcda` |
+
+Compare diagram hashes only between identical byte strings: the same diagram handed
+over without its trailing newline hashes differently (`8c41f046…` becomes
+`c8f3a41b…`). That is the specification, not drift.
+
 ## Checking an archived hash
 
 `--hash-spec` recomputes under a named specification; `--hash-check` answers whether a

package/skills/logicprobe-uml/SKILL.md

@@ -16,6 +16,7 @@ This skill covers the diagram half of the Logic Probe toolbox. The claim-verific
 | 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 |
+| Printing what the parser accepts for labels and comments | `action=explain-labels`: the accepted label spellings, the form the renderer writes, and which lines are ignored (the CLI mirror is `uml-review --explain-labels`) |
 | 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):
@@ -29,8 +30,9 @@ code flow → model (citation per element) → logicprobe_uml action=render →
 - **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?
+- **explain-labels** — the parser's own account of labels and comments: the accepted spellings, the form the renderer writes, and which lines it ignores. No diagram needed. It answers "why does my hand-drawn diagram report drift or ignored lines?" without reading the source.
 
-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 host without the tools runs the same four 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
 

package/skills/logicprobe-uml/references/uml-modeling-guide.md

@@ -227,10 +227,10 @@ Now delete the `ERROR --cooldown--> STARTING` arrow and review again. `ACTIVE` a
 ## 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.
+tools themselves: `logicprobe_uml action="explain-labels"` returns the convention (pass
+`notation: "plantuml"` for that flavour), and the CLI mirror is `uml-review
+--explain-labels` (with `--notation plantuml`). Either one 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:
@@ -254,12 +254,13 @@ directives the renderer writes (`%%logicprobe:` in Mermaid, `'logicprobe:` in Pl
 `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:
+Everything else is notation chrome (skipped silently), an ignored line, or a reported
+construct:
 
 | 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) |
+| a multi-line `note … end note` block | its body is skipped (prose is not a state meaning) and the block is reported once in `discardedConstructs` |
 | `@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 |
 

package/src/engine.ts

@@ -206,7 +206,11 @@ export interface PathStep {
 
 export interface Finding {
   code: string
-  severity: 'error' | 'warning'
+  /**
+   * `info` is a note, not a defect: it is reported so a machine-readable reader can see it,
+   * and it never contributes to `verdict`, `summary.errors` or `summary.warnings`.
+   */
+  severity: 'error' | 'warning' | 'info'
   message: string
   /** Longer explanation: the shortest-path note, the per-machine reasons, the quoted source lines. */
   detail?: string
@@ -286,6 +290,20 @@ function verificationNextSteps(checks: CheckResult[], coverage: NarrativeCoverag
   return steps
 }
 
+/**
+ * Repair guidance for a rejected model. A refusal reports the offending path and the rule
+ * it broke, but not what to write instead; for fields whose absence is a documented trap,
+ * that is the difference between "fix it" and "guess again". Derived only from the
+ * validation messages, so the list stays deterministic.
+ */
+function refusalGuidance(errors: string[]): string[] {
+  const steps: string[] = []
+  if (errors.some((message) => message.includes('.description'))) {
+    steps.push('Add the required "description" string to every invariant (for example "description": "what this invariant guarantees"); a `_`-prefixed key is not a substitute, and the value takes part in `modelHash`.')
+  }
+  return steps
+}
+
 export interface ComparisonSummary {
   beforeModelHash: string
   afterModelHash: string
@@ -366,6 +384,7 @@ export const REPORT_SCHEMAS = {
   umlRender: 'logicprobe/uml/render/v1',
   umlParse: 'logicprobe/uml/parse/v1',
   umlReview: 'logicprobe/uml/review/v1',
+  umlExplainLabels: 'logicprobe/uml/explain-labels/v1',
   structure: 'logicprobe/structure/v1',
   granularity: 'logicprobe/granularity/v1',
   baseline: 'logicprobe/baseline/v1',
@@ -1060,7 +1079,9 @@ function checkResult(id: string, name: string, findings: Finding[], detail: stri
   return {
     id,
     name,
-    status: findings.length === 0 ? 'pass' : 'fail',
+    // An info finding is a note, not a defect: it must not flip a check to `fail`, or the
+    // check would be dragged into the "resolve the failing checks" list for a remark.
+    status: errors + warnings === 0 ? 'pass' : 'fail',
     detail: detail + (errors > 0 ? ' (' + errors + ' errors' + (warnings > 0 ? ', ' + warnings + ' warnings' : '') + ')' : warnings > 0 ? ' (' + warnings + ' warnings)' : ''),
     findings,
   }
@@ -2893,7 +2914,7 @@ export function runVerification(input: unknown, options: VerificationOptions = {
       ...metadata,
       summary: { states: 0, transitions: 0, errors: validation.errors.length, warnings: 0, checksRun: 0 },
       checks: [modelCheck],
-      nextSteps: verificationNextSteps([modelCheck], undefined),
+      nextSteps: [...refusalGuidance(validation.errors), ...verificationNextSteps([modelCheck], undefined)],
     }
   }
   const model = validation.model
@@ -2973,6 +2994,16 @@ export function runVerification(input: unknown, options: VerificationOptions = {
   const warnings = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'warning').length, 0)
   const coverageNotes = computeCoverageNotes(model)
   const narrativeCoverage = narrativeCoverageOf(model)
+  // R3: a partial narrative is valid, but the gap must be machine-readable instead of only a
+  // sentence in `nextSteps`. It rides on S5 — the check that already reports undocumented
+  // (state, event) combinations — so the documented check count stays 22.
+  if (narrativeCoverage !== undefined && !narrativeComplete(narrativeCoverage)) {
+    checks.find((check) => check.id === 'S5')?.findings.push({
+      code: 'NARRATIVE_PARTIAL',
+      severity: 'info',
+      message: 'Narrative coverage is partial (states ' + narrativeCoverage.states + ', events ' + narrativeCoverage.events + ', scenarios ' + narrativeCoverage.scenarios + '): the checks still run over the whole model, but the undocumented symbols have to be re-derived by the reader.',
+    })
+  }
   return {
     ok: true,
     ran: true,
@@ -3223,11 +3254,21 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
         .map((machine) => 'machine ' + String(machine.index) + ' at ' + machine.state + ': ' + (machine.blocked.length === 0
           ? 'empty event alphabet'
           : machine.blocked.map((entry) => entry.event + ' (' + entry.reason + ')').join(', ')))
+      // A non-terminal state with no outgoing transition anywhere in its own model is a
+      // modelling gap, not a design defect: without this note the census reads as
+      // "the architecture deadlocks" when the model was simply left unfinished.
+      const gaps = node.runtimes
+        .map((runtime, index) => ({ index, state: runtime.state }))
+        .filter((entry) => !isTerminal(models[entry.index], entry.state)
+          && !models[entry.index].transitions.some((transition) => transition.from === entry.state))
+      const gapNote = gaps.length === 0
+        ? ''
+        : ' Modelling note: ' + gaps.map((gap) => 'machine ' + String(gap.index) + ' state ' + gap.state).join(', ') + ' has no outgoing transition in its own model, so this deadlock may be a modelling gap rather than a design defect.'
       c1Findings.push({
         code: 'C1_COMPOSITION_DEADLOCK',
         severity: 'error',
         message: 'Composition deadlock: no machine can advance from (' + node.runtimes.map((runtime) => runtime.state).join(', ') + ') while at least one is not terminal.',
-        detail: 'Shortest counterexample (breadth-first): ' + String(node.path.length) + ' step(s) to reach it. ' + reasons.join(' | '),
+        detail: 'Shortest counterexample (breadth-first): ' + String(node.path.length) + ' step(s) to reach it. ' + reasons.join(' | ') + gapNote,
         evidence: { steps: node.path, states: node.runtimes.map((runtime) => runtime.state), depth: node.path.length, perMachine, reasons },
       })
       continue
@@ -3269,7 +3310,7 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
       const caveat = truncated ? ' The search was truncated at ' + String(maxStates) + ' composite states, so this may be an artefact of the cap rather than a property of the model.' : ''
       c2Findings.push({
         code: 'C2_RENDEZVOUS_NEVER_FIRES',
-        severity: 'warning',
+        severity: 'error',
         message: 'Rendezvous event ' + event + ' can never fire: ' + reason + '.' + caveat,
         detail: machines.map((machine) => 'machine ' + String(machine.index) + (machine.declares ? ' declares' : ' does not declare')
           + (machine.everEnabled ? ', enabled at ' + (machine.enabledAt.length === 0 ? 'no visited state' : machine.enabledAt.join('/')) : ', never enabled')).join(' | '),
@@ -3277,15 +3318,18 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
       })
     }
   }
-  const errors = c1Findings.length
-  const warnings = c2Findings.length
+  // C2 is an error, not a warning: a rendezvous that can never fire means the composition
+  // cannot advance through that handshake — the same "stuck forever" outcome C1 reports,
+  // so a gate that only reads `verdict` must be able to stop on it.
+  const errors = c1Findings.length + c2Findings.length
+  const warnings = 0
   const c1Detail = c1Findings.length > 0
     ? 'Composition deadlocks: ' + String(c1Findings.length)
     : truncated
       ? 'No composition deadlock found, but the search was truncated at ' + String(maxStates) + ' composite states: absence is not proven'
       : 'No composition deadlock reachable'
   const c2Detail = c2Findings.length > 0
-    ? 'Rendezvous warnings: ' + String(c2Findings.length)
+    ? 'Rendezvous errors: ' + String(c2Findings.length)
     : truncated
       ? 'All rendezvous events fired, but the search was truncated at ' + String(maxStates) + ' composite states'
       : 'All rendezvous events can fire'
@@ -3294,8 +3338,21 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
     checkResult('C2', 'Rendezvous Sync', c2Findings, c2Detail),
   ]
   const nextSteps: string[] = []
-  if (errors > 0) nextSteps.push('Resolve the error findings first: the composition deadlocks at a reachable state, so at least one machine is missing an exit or a handshake partner.')
-  if (warnings > 0) nextSteps.push('Review the warning findings: a rendezvous event that can never fire means the handshake is declared but unreachable.')
+  if (errors > 0) {
+    const why = c1Findings.length > 0
+      ? 'the composition deadlocks at a reachable state, so at least one machine is missing an exit or a handshake partner'
+      : 'a rendezvous event can never fire, so the composition cannot advance through that handshake'
+    nextSteps.push('Resolve the error findings first: ' + why + '.')
+  }
+  // Composition couples machines only through rendezvous: each machine's `variables` are
+  // private to it, so two machines cannot share one predicate. Name them when the input
+  // looks like it is trying to (two or more machines each declare variables).
+  const owners = models
+    .map((entry, index) => ({ index, names: (entry.variables ?? []).map((variable) => variable.name) }))
+    .filter((entry) => entry.names.length > 0)
+  if (owners.length >= 2) {
+    nextSteps.push('Each machine\'s variables are private to it (' + owners.map((entry) => 'machine ' + String(entry.index) + ': ' + entry.names.join(', ')).join('; ') + '): composition couples machines only through rendezvous, so a value two machines must agree on has to be modelled as a handshake, or inside a single machine.')
+  }
   nextSteps.push('Re-run the composition after the change; every machine must be able to advance, or explain why it is terminal.')
   return {
     ok: errors === 0,

package/src/uml-tool.ts

@@ -2,7 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createHash } from 'node:crypto'
 import type { JsonValue } from './json-value.js'
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings, type VerdictSummary } from './engine.js'
-import { renderUml, parseUml, parseFindings, reviewUml, UmlError, type UmlDiagram, type UmlFinding, type UmlNotation, type UmlParseResult } from './uml.js'
+import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, UmlError, type UmlDiagram, type UmlFinding, type UmlNotation, type UmlParseResult } from './uml.js'
 
 export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 
@@ -21,13 +21,13 @@ export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 export const logicProbeUmlTool = defineTool({
   name: LOGICPROBE_UML_TOOL_NAME,
   description:
-    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Read `verdict`, not `ok`: error findings mean a failed review.',
+    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Read `verdict`, not `ok`: error findings mean a failed review.',
   parameters: {
     action: {
       type: 'string',
       required: true,
-      enum: ['render', 'parse', 'review'],
-      description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model).',
+      enum: ['render', 'parse', 'review', 'explain-labels'],
+      description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model); explain-labels = print the label and comment conventions this parser accepts.',
     },
     model: {
       type: 'json',
@@ -107,6 +107,19 @@ export const logicProbeUmlTool = defineTool({
           warnings: result.warnings,
         } as unknown as JsonValue
       }
+      // R9: the label contract was documented in the library and in `explainLabels()`, but no
+      // tool exposed it, so it was reachable only by reading the source or the docs.
+      if (args.action === 'explain-labels') {
+        const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation
+        return {
+          ok: true,
+          ran: true,
+          ...verdictOf(0, 0),
+          schema: REPORT_SCHEMAS.umlExplainLabels,
+          action: 'explain-labels',
+          ...explainLabels(notation),
+        } as unknown as JsonValue
+      }
       const report = reviewUml({
         model: args.model,
         diagram: args.diagram,

package/src/uml.ts

@@ -870,19 +870,23 @@ function declaredIdentifier(text: string): string | undefined {
  * file, which is a false guarantee of exactly the kind this plugin exists to prevent.
  */
 export function parseFindings(parsed: UmlParseResult): UmlFinding[] {
-  if (parsed.discardedConstructs.length === 0) return []
+  // A note block is reported in `discardedConstructs` for transparency, but it does not make
+  // the text "not a state diagram": the rest of the file still is one, so only the constructs
+  // that actually replace a state declaration count towards the refusal.
+  const unsupported = parsed.discardedConstructs.filter((entry) => entry.construct !== 'note')
+  if (unsupported.length === 0) return []
   const counts = new Map<string, number>()
-  for (const entry of parsed.discardedConstructs) counts.set(entry.construct, (counts.get(entry.construct) ?? 0) + 1)
+  for (const entry of unsupported) counts.set(entry.construct, (counts.get(entry.construct) ?? 0) + 1)
   const summary = [...counts.entries()]
     .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
     .map(([construct, count]) => construct + ' ×' + String(count))
     .join(', ')
-  const shown = parsed.discardedConstructs.slice(0, 12).map((entry) => 'line ' + String(entry.line) + ': ' + entry.text).join(' | ')
+  const shown = unsupported.slice(0, 12).map((entry) => 'line ' + String(entry.line) + ': ' + entry.text).join(' | ')
   return [{
     code: 'UML_NOT_A_STATE_DIAGRAM',
     severity: 'error',
-    message: 'the text is not a state or activity diagram: ' + String(parsed.discardedConstructs.length) + ' declaration(s) of unsupported construct(s) (' + summary + ') and ' + String(parsed.discardedEdges) + ' arrow(s) between them were read as states and transitions, so the parsed model is not this diagram.',
-    detail: shown + (parsed.discardedConstructs.length > 12 ? ' | … ' + String(parsed.discardedConstructs.length - 12) + ' more' : ''),
+    message: 'the text is not a state or activity diagram: ' + String(unsupported.length) + ' declaration(s) of unsupported construct(s) (' + summary + ') and ' + String(parsed.discardedEdges) + ' arrow(s) between them were read as states and transitions, so the parsed model is not this diagram.',
+    detail: shown + (unsupported.length > 12 ? ' | … ' + String(unsupported.length - 12) + ' more' : ''),
   }]
 }
 
@@ -916,7 +920,16 @@ function parseStateDiagram(text: string, notation: UmlNotation): UmlParseResult
     // A multi-line note body is prose, not a statement: skip it silently rather than
     // reporting one ignored line per line of text.
     if (inNote) return
-    if (noteStart && !/:\s*.+$/.test(line)) { inNote = true; return }
+    if (noteStart && !/:\s*.+$/.test(line)) {
+      // R7: a multi-line note block is prose the notation carries and LogicModelV1 does not.
+      // Its body is still skipped line by line, but the block itself is NOT silent: it is
+      // reported once, like any other unsupported construct, so "the diagram hash changed and
+      // the report said nothing" cannot happen. It stays out of `warnings` (no per-line noise)
+      // and `parseFindings` keeps it out of the "not a state diagram" verdict.
+      raw.discarded.push({ construct: 'note', line: index + 1, text: line })
+      inNote = true
+      return
+    }
     const note = /^note\s+(?:over|right of|left of)\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.+)$/i.exec(line)
     if (note !== null) {
       declare(note[1])
@@ -1084,7 +1097,7 @@ export function explainLabels(notation: UmlNotation = 'mermaid'): LabelExplanati
     renderedForm: 'state "ID（meaning）" as ID',
     ignoredLines: [
       { pattern: 'a `' + prefix + '` comment line that is not a `logicprobe:` directive', behaviour: 'UML_PARSE_IGNORED_LINE warning: it carries no state-machine statement' },
-      { pattern: 'a `note …` block written over several lines', behaviour: 'skipped silently (a block is not a state meaning)' },
+      { pattern: 'a `note …` block written over several lines', behaviour: 'its body is skipped line by line (prose, not a statement) and the block itself is reported once in discardedConstructs' },
       { pattern: 'notation chrome: @startuml/@enduml, stateDiagram-v2, direction, classDef/style/linkStyle/click, scale, skinparam, title, hide, autonumber', behaviour: 'skipped silently' },
       { pattern: 'anything else the parser cannot read', behaviour: 'UML_PARSE_IGNORED_LINE warning, and the model is built from what it did read' },
     ],