dsh-logicprobe 0.8.1 → 1.0.0

package/skills/logicprobe/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: logicprobe
-description: "Use when reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, or mechanism feasibility. When the document contains state machines, protocol logic, or behavioral claims (≥3 states, ACK/NACK/retry sequences, 'always'/'never'/'guaranteed' assertions, or refactoring that modifies state topology), escalate into logic-primitive verification — generate and run executable models to check mathematical completeness before trusting any claim. For refactoring specifically, the pipeline compares before/after models to verify behavioral preservation and regression freedom. ALSO use when the task is to model a code flow as UML, or to audit a diagram somebody drew. That covers reverse-engineering a handler and documenting a protocol. The skill renders the model as a state, activity or sequence diagram, reads a hand-drawn diagram back into a model, and reviews the modelling: unreachable states, dead ends, ambiguous branches, documentation gaps, and diagram-versus-model fidelity. ALSO proactively SUGGEST this skill (do not require) when a user asks code-level behavioral questions — 'check this timing for bugs', 'could this state machine deadlock', 'is this retry limit safe' — since plan-level verification has usually already been done."
+description: "Use when you want to verify something about code: a design doc, spec, plan, review comment, README or refactor asserting API names, paths, enums, feasibility, state-machine or protocol behaviour, timing guarantees, or 'always/never' properties. Enumerates the claims, verifies each against the code (file:line), and escalates to executable model checks (S1-S8 + A1-A14) when behaviour is at stake. Diagrams: logicprobe-uml; concurrency: logicprobe-concurrency; data: logicprobe-datamodel."
 ---
 
 # Logic Probe
 
-Documents are not truth — code is. Verify every verifiable claim before accepting or acting on any design.
+For an unverified design, failure is only a matter of time. Complex code becomes clear once you model it and run it. Check every claim before you act on it.
+
+## When This Skill Applies
+
+**This is the entry point.** If you have any thought of checking whether something about the code is actually true — however small, however informal the claim — load this skill. It owns the doctrine (enumerate the claims, verify each against the code, cite `file:line`, read `verdict` and never `ok`) and the executable verification for behaviour. When the task lands in a neighbouring domain, its routing table below hands it over rather than stretching the doctrine to cover it.
+
+| The task involves… | What it does |
+|---|---|
+| Any claim about code you want to check — a design doc, spec, plan, review comment, README, commit message, refactor proposal, or a "this is safe / this always holds / this can't deadlock" assertion | Enumerate the verifiable claims (Phase 1), verify each against the codebase with `file:line` evidence (Phase 2), classify the gaps (Phase 3) |
+| A state machine or protocol — ≥3 states, guards, ACK/NACK/retry, lock/unlock, start/stop ordering | Build an executable model: S1-S8 structural checks, A1-A14 adversarial probes |
+| A quantitative or temporal guarantee — worst-case path cost ≤ budget, "≥90% of runs reach SAFE", "must leave within 2 ticks" | A12 budget, A13 probabilistic reachability, A14 deadlines, each with a counterexample path |
+| A handshake or power-up sequencing across two or more components | `logicprobe_compose_verify`: C1 composition deadlock, C2 rendezvous that never fires |
+| A refactoring that changes state topology or guard conditions | BEFORE/AFTER models compared for behavioral preservation, invariant continuity and deadlock regression (D1-D4) |
+| Explicit request to prove code correct, formally verify a module, or check a migration for breakage | Route by domain — the table under [Routing to the Sibling Skills](#routing-to-the-sibling-skills) — and keep the doctrine |
+| An architecture or dependency question about a component/package/class diagram | `logicprobe-structure`: parse the diagram into a dependency graph and judge every edge against the dependency matrix |
+
+**Catalog budget**: DSH renders only the frontmatter `description`, and truncates it at 500 characters (`dsh-tool-skill`, `DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH`). Every description in this plugin is written to fit that budget, and the triggers that do not fit live in this table. `tests/skills/run.mjs` fails when any skill's catalog line would be cut, or would lose one of its use-case triggers.
 
 <HARD-GATE>
 
@@ -131,9 +147,7 @@ When Phase 2 triggers escalation, do NOT proceed to Phase 3 until the verificati
 ```text
 Document claims → Extract model → Runtime check:
   ├── DSH + `logicprobe_verify` tool available → build Model schema v1 (references/dsh-model-schema.md) → call the tool → structured report
-  ├── Python available + LogicModelV1 JSON at hand → references/logicprobe-engine.py verify model.json (S1-S8/A1-A14/D1-D4; subcommands compose / export add C1-C2 and UPPAAL/TLA+/PRISM/SPIN output)
-  ├── Python available + model only as extracted dicts → fill in references/verification-harness.py → run → report
-  └── No Python → Manual Verification Mode (see references/logic-verification-guide.md#manual-verification-mode)
+  └── No engine available → Manual Verification Mode (see references/logic-verification-guide.md#manual-verification-mode)
 
 Refactoring variant:
   Old code + Refactoring plan → Extract BEFORE model + AFTER model
@@ -147,6 +161,69 @@ UML modelling variant (the task is to draw a flow, not to check a claim):
     → logicprobe_verify → the behavioural checks (S1-S8 / A1-A14)
 ```
 
+### Native dsh Tools
+
+| Tool | Covers |
+|------|--------|
+| `logicprobe_verify` | S1-S8 structural + A1-A14 adversarial, including A12 budget / worst-case path cost, A13 probabilistic reachability over a DTMC, and A14 discrete-tick deadlines. `beforeModel` + `stateMapping` add the D1-D4 before/after regression. |
+| `logicprobe_datamodel_verify` | Data models and schema migrations: DS/DA checks plus the DD1-DD4 data regression. See the `logicprobe-datamodel` skill. |
+| `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. |
+
+The repository engine mirrors the same checks and carries the `compose` and `export` subcommands for hosts without the native tools.
+
+### Reading a Report: `ok` Is Not a Verdict
+
+Every tool report carries the same outcome contract. **`ok` says a report was produced; `verdict` says how the review went.** A report may be `ok: true` and still be a failed review — gating on `ok` is how a failing verification gets read as a passing one.
+
+| Field | Meaning |
+|-------|---------|
+| `schema` | The versioned report contract (`logicprobe/verify/v1`, `logicprobe/uml/review/v1`, …). Branch on this instead of sniffing fields. |
+| `ran` | The tool executed and produced this report. `false` only when the tool refused the request before running (see `errorCode`/`error`). |
+| `verdict` | `pass` \| `pass_with_findings` \| `fail`. **This is the outcome you act on.** |
+| `verdictReason` | Why, e.g. `2 error finding(s) (first: S2_NO_TRANSITIONS)` or `no error findings; 3 warning finding(s)`. |
+| `findings[]` | `{code, severity, message, detail?, evidence?, path?}`. Any `severity: "error"` forces `verdict: "fail"`. |
+| `hashSpec` | Which published model-hash specification `modelHash` follows — see `references/hash-spec.md`. |
+| `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. |
+
+Turn the verdict into an answer, never into a summary of `ok`:
+
+- `verdict: "pass"` — no error and no warning finding. Safe to report as verified, still with the scope the model covered.
+- `verdict: "pass_with_findings"` — verification ran clean, but warnings exist (e.g. `S5` implicit-ignore events, `UML012_NO_TERMINAL`). Report the pass **and** the warnings; do not silently upgrade it to "no issues".
+- `verdict: "fail"` — an error-severity finding exists, or the input was rejected (`MODEL_INVALID`). Say plainly that the claim is **not** verified, quote the counterexample path the finding carries, and only then propose a correction. Never describe a `fail` as "the tool ran successfully".
+
+Exit codes: `0` for `pass` / `pass_with_findings`, `2` for `fail`, a refusal, or an unreadable input. In DSH the native tools return the report as data — read `verdict`, and treat `errorCode`/`error` as the refusal path.
+
+### Slice Acceptance: Baseline Diffs
+
+The acceptance criterion for a refactoring slice is usually "no **new** findings", not
+"zero findings". Do not compare two JSON reports by eye — run the comparison:
+
+- DSH: `logicprobe_report_diff { baseline: <earlier report>, current: <new report> }`
+- Any host without the tools: run the repository engine against the same JSON.
+  (also available on `compose`, `structure` and `uml-review`)
+
+A finding's identity is its **check id + code + canonical locator** (built from
+`evidence`/`path`; the message only when a finding carries neither), so a reworded
+message reads as `changed`, never as a new finding. The diff's `verdict` describes the
+**delta** — a newly added error finding fails it — while `currentVerdict` keeps the
+absolute result visible, and a clean delta over a still-failing report says so in
+`nextSteps` rather than passing quietly. Two runs over the same input add zero findings:
+run that self-check before trusting any baseline.
+
+### Archiving a Model: `_`-Prefixed Metadata
+
+Keep provenance with the model instead of in a sidecar that drifts:
+
+- Any key starting with `_` at any level (`_source`, `_verified`, `_uml`, `_extraction_caveats`, `states[0]._note`) is **annotation metadata**: the schema ignores it, `modelHash` excludes it, and the report echoes it as `metadataKeys`.
+- Everything else stays closed — a mistyped `sttes` is still a validation error, and that is deliberate.
+- Because the hash ignores `_` keys, "the model as archived" and "the model with metadata stripped" hash identically; record the reported `hashSpec` next to the hash so a later reader can reproduce it (`verify model.json --hash-check <hex>` answers whether a recorded hash belongs to a published spec at all).
+
 ### Refactoring Verification Mode
 
 When the document under review is a refactoring plan (modifying existing state machine logic, not designing from scratch), adapt the pipeline:
@@ -169,15 +246,7 @@ When the document under review is a refactoring plan (modifying existing state m
 
 6. **Flag any behavioral delta not documented in the plan** — the most common refactoring bug is an unintended side effect that the plan doesn't acknowledge
 
-**Detection step**: Before generating any verification code, run `python3 --version 2>&1` or `python --version 2>&1`. Check the output:
-
-- Returns `Python 3.x.y` with x ≥ 6 → use Python harness
-- Returns anything else (command not found, "Python was not found" Windows stub, version < 3.6) → fall back to Manual Verification Mode
-- On Windows, if `python` launches the Microsoft Store, treat as unavailable
-
-Do NOT attempt to install Python — the user's embedded development machine may be air-gapped or locked down.
-
-In DSH, prefer the native `logicprobe_verify` tool (model JSON, structured guard DSL, path-aware invariants) — see `references/dsh-model-schema.md`. For non-DSH hosts: when the model is already a LogicModelV1 JSON, run the standalone JSON engine `references/logicprobe-engine.py` (verify | compose | export — an exact Python mirror of the DSH tools, cross-checked byte-for-byte by tests/python/run.mjs); when the model exists only as extracted dicts, fill in the reusable template `references/verification-harness.py`. For detailed probe patterns, model extraction methodology, and manual verification procedures, load `references/logic-verification-guide.md`.
+Run the checks with the native `logicprobe_verify` tool (model JSON, structured guard DSL, path-aware invariants) — see `references/dsh-model-schema.md`. A host without the tools can run the repository engine against the same JSON. For probe patterns, extraction methodology and manual procedures, load `references/logic-verification-guide.md`.
 
 ### Phase 2a: Structural Primitives (8 Checks)
 
@@ -206,9 +275,9 @@ Run these SECOND. Each probe actively tries to BREAK the model. If any probe suc
 | A4 | **Pair symmetry** | Match every `start/stop`, `lock/unlock`, `alloc/free` pair. Flag if any state allows a path where a pair is unbalanced (start without stop, lock without unlock). State `onEntry`/`onExit` actions are treated as implicit acquire/release. | "Resources are always released" |
 | A5 | **Boundary blast** | Probe counters at 0, 1, max-1, max, max+1. Probe timestamps at 0, tick_wraparound. Flag overflow, underflow, or undefined behavior. | "Handles all counter/timer values" |
 | A6 | **Resource injection** | Simulate `malloc→NULL`, `queue→full`, `semaphore→timeout` at each state that calls them. Flag if any state has no recovery path. | "Graceful degradation under resource pressure" |
-| A7 | **Minimal counter-example** | For any invariant that fails, find the SHORTEST event sequence that violates it (BFS from init to violating state). Output the exact path. | "This invariant holds" → refuted by shortest path |
+| A7 | **Counter-example witness** | For any invariant that fails, find the event sequence that violates it and output the exact path. Breadth-first searches (state predicates, sequence, atomicity, budget) yield the shortest witness; the leads-to walk and the probability bound report the witness they found without claiming minimality. | "This invariant holds" → refuted by a concrete path |
 | A8 | **Idempotent replay** | For each event declared in `idempotentEvents`, apply it twice from every reachable state. Flag if the second application changes state or is not replayable. | "This event is safe to retry/replay" |
-| A9 | **Leads-to** | From a declared source state, every path must eventually reach the target state. | "This state always progresses to completion" |
+| A9 | **Leads-to** | From a declared source state, every path must eventually reach the target state, or reach one member of a declared target set. | "This state always progresses to completion" |
 | A10 | **Sequence order** | Events declared in a sequence must occur in the specified order. | "backup before modify before commit" |
 | A11 | **Atomicity** | Once an atomic event starts, the machine must commit or roll back before leaving the scope or terminating. | "all-or-nothing transaction" |
 | A12 | **Budget (worst-case path cost)** | With `cost` on transitions (absent = 1) and a `budget` invariant, every reachable path must stay within budget; reports the shortest over-budget counterexample and flags reachable positive-cost cycles as unbounded. | "Worst-case path cost ≤ budget" |
@@ -312,35 +381,6 @@ If the user says yes, extract the model from the existing code (not a plan docum
 
 This covers the gap where behavioral verification is useful even when no design document is being reviewed.
 
-## UML Modelling and Modelling Review
-
-Use this when the task is to **draw** a code flow rather than to check a claim. Typical cases are reverse-engineering a handler, documenting a protocol exchange, and auditing a diagram somebody else drew.
-
-A diagram is a model, and a model can be wrong. A tidy flow chart is not evidence about the code. A diagram that disagrees with its own model is worse than no diagram, because a reader will believe it.
-
-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. A sequence diagram is refused, because a trace cannot reconstruct a machine.
-- **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?
-
-The review reports structural defects and documentation gaps. The structural defects are unreachable states, dead ends, ambiguous or non-exhaustive branches, self-loops with no exit, and duplicate transitions. The documentation gaps are a missing narrative, unbounded variables, states the reader cannot map back to code, and label drift. 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. **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.
-4. **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`), the directive format generated diagrams carry, a worked example, and the limits of each view are in `references/uml-modeling-guide.md`.
-
 ### When NOT to Escalate
 
 Skip logic-primitive verification when:
@@ -349,19 +389,16 @@ Skip logic-primitive verification when:
 - The state machine has ≤2 states, no guards, and trivial transitions (IDLE↔ACTIVE)
 - The claim is purely structural (file paths, type names, numeric constants) — Phase 2 grep verification is sufficient
 
-## Concurrency Risk Mining
-
-**Only use this after confirming the verification target actually has concurrency requirements or behavior** — e.g., multiple threads, async tasks, interrupts, shared state, or parallel execution. If the target is purely sequential, do not invoke concurrency mining.
-
-logicprobe does **not** prove concurrency safety. It mines documents and plans for concurrency-related claims and flags them for dedicated verification.
-
-- Absolute claims ("thread-safe", "lock-free", "no data race") → error / `UNVERIFIED` unless dedicated evidence is provided.
-- Risk keywords ("race condition", "shared variable", "mutex", "atomic", "shared memory") → warning; review whether the plan addresses them.
-- Interrupt safety is included: `interrupt-safe` / `ISR-safe` are absolute claims; `ISR`, `IRQ`, `NMI`, `critical section`, `disable_irq` / `enable_irq` are risk keywords.
+### Routing to the Sibling Skills
 
-In DSH, use the `logicprobe_concurrency_scan` tool. For manual review, follow `references/concurrency-risk-guide.md`.
+This skill owns behavioural claims. Three neighbouring domains have their own skill, and loading the wrong one wastes the verification:
 
-For routing claims in dimensions logicprobe does not verify — hard real time (deadlines/periods), preemptive concurrency, hybrid control stability, probabilistic reliability, and execution-cost budgets — to dedicated tools, see `references/gap-routing-guide.md`. In `logicprobe_verify` reports, matching models carry informational `coverageNotes` with the same routing.
+| 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` |
+| 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` |
 
 ---
 
@@ -373,5 +410,7 @@ For routing claims in dimensions logicprobe does not verify — hard real time (
 4. Don't fix during review — point the way, let implementation happen after approval.
 5. **For behavioral claims: verify with code, not reasoning.** If a plan says "always", "never", or "guaranteed", generate and run a model. One counter-example is enough to refute a universal claim.
 6. **Confirm the model before running it** — unless the runtime reports `logicprobe interaction=auto`. Extraction errors are the dominant failure mode of formal verification. In auto mode, substitute evidence-cited extraction + round-trip validation and mark the report `UNCONFIRMED`.
-7. **Don't verify what the code already checks.** If the existing codebase has compile-time assertions, static analysis, or runtime checks for a property, cite those — don't re-verify in a Python model.
-8. **A diagram is a model, not evidence.** When you model a code flow as UML, cite the source for every state, event, guard and action. Run `logicprobe_uml` with `action=review` before you show the diagram. A diagram that does not read back as the model it was drawn from is mis-modelled, however tidy it looks.
+7. **Don't verify what the code already checks.** If the existing codebase has compile-time assertions, static analysis, or runtime checks for a property, cite those — don't re-verify in a model.
+8. **Hand a neighbouring domain to its own skill.** A diagram is a model, not evidence: modelling or auditing one belongs to `logicprobe-uml`. A concurrency claim is mined and routed, never proven here: that is `logicprobe-concurrency`. Schema, data invariants and migrations are `logicprobe-datamodel`. This skill keeps the doctrine and the behavioural checks.
+9. **Say what this does not prove.** For dimensions logicprobe does not verify — hard real time (deadlines, periods), preemptive concurrency, hybrid-control stability, probabilistic reliability, execution-cost budgets — route to the dedicated tool named in `references/gap-routing-guide.md`. `logicprobe_verify` reports carry the same routing as informational `coverageNotes` on matching models.
+10. **Write-site analysis is out of scope, and stays there.** "Only the ISR writes this flag", "one owner per register" — logicprobe verifies models and diagrams, not *who writes what in the source*. That claim needs a source-side AST/rule check or a static analyzer; this plugin's contribution is to flag the claim as unverified and route it (`logicprobe_concurrency_scan` does exactly that). Do not imply the diagram or the model settled it.

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

@@ -56,6 +56,60 @@ Declared keys per part:
 
 `boundaryChecks` is the one place where two schemas share a field name: `logicprobe_verify` uses `{ variable, values }` (a variable's boundary values for A5), while `logicprobe_datamodel_verify` uses `{ entity, field, values }` (a field's boundary values for DA2). Each validator enforces its own shape, so an `(entity, field)` check passed to the state-machine engine is rejected rather than half-understood.
 
+### `_`-prefixed keys are annotation metadata (the one exception)
+
+A key whose name starts with `_` is **not** part of the model. At any level — on the
+model, a state, a transition, inside `narrative` — the schema skips it, the hash ignores
+it, and the report lists it under `metadataKeys`:
+
+```json
+{
+  "schemaVersion": 1,
+  "init": "IDLE",
+  "states": [{ "id": "IDLE", "_note": "power-on, not ready" }],
+  "_source": "docs/uml/order-service.model.json",
+  "_verified": { "modelHash": "0000000000000000…", "at": "2026-10-09" },
+  "_extraction_caveats": ["guard thresholds read from the ISR, not the task"]
+}
+```
+
+```json
+"metadataKeys": ["_extraction_caveats", "_source", "_verified", "states[0]._note"]
+```
+
+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
+and still cannot change the model's identity: `modelHash` excludes `_` keys, so the
+model as archived and the model with the metadata stripped hash identically.
+
+The exemption is namespaced, not a loosening of the closed schema. `_` keys are never
+*read* by any check, so ignoring them cannot produce a false result; a mistyped
+non-prefixed key (`sttes`, `gaurd`, `maximum`) is still a validation error, which is
+the whole point of the closed schema.
+
+### Reading a report: `ran`, `verdict`, `ok`
+
+`logicprobe_verify` (and `logicprobe_compose_verify`) reports separate "the tool ran"
+from "the review passed":
+
+| Field | Meaning |
+|---|---|
+| `schema` | The versioned report contract, e.g. `logicprobe/verify/v1` — branch on this instead of sniffing fields. |
+| `ok` | The engine produced a report. For `verify` this is `false` only when model *validation* failed. It is **not** a verdict. |
+| `ran` | The tool executed. `false` only for a tool-level refusal (`errorCode`/`error` present). |
+| `verdict` | `pass` \| `pass_with_findings` \| `fail`. Any `severity: "error"` finding — or a validation failure — makes this `fail`. |
+| `verdictReason` | e.g. `1 error finding(s) (first: S2_NO_TRANSITIONS)`, `no error findings; 3 warning finding(s)`, `no error or warning findings`. |
+| `hashSpec` | The published hash specification `modelHash` follows — see [hash-spec.md](hash-spec.md). |
+| `hashes` | Every hash the report carries, in one place (`modelHash`, `beforeModelHash`/`afterModelHash` for a comparison). |
+| `metadataKeys` | Present only when the input carried `_` keys (see above). |
+| `narrativeCoverage` | Present only when the input carried a narrative: `covered/total` per dimension. |
+| `nextSteps` | What to do next, derived from the findings; never empty, and identical for two runs over the same model. |
+
+A caller that reads `ok` sees `true` for a model with a deadlock; the verdict is what
+says so. Report the verdict, quote the counterexample path from the finding, and never
+describe a `fail` as "the tool ran fine".
+
 ### References must resolve
 
 The same reasoning applies to every id a check names. A reference to a state, event, or variable that the model does not declare cannot be satisfied, and because the engine copies each check's target into its findings (`"target": "DONE"`), an unresolvable id reads as authoritative in the report:
@@ -68,7 +122,8 @@ The same reasoning applies to every id a check names. A reference to a state, ev
 | `transitions[].guard` variables | a declared variable |
 | `resourcePairs[].acquireEvent` / `.releaseEvent` / `.failEvent` | a declared event |
 | `invariants[].event` (`event-before-state`) | a declared event |
-| `invariants[].state` / `.states[]` / `.from` / `.to` / `.target` / `.when.state` | a declared state |
+| `invariants[].state` / `.states[]` / `.from` / `.target` / `.when.state` | a declared state |
+| `invariants[].to` and every member of `invariants[].to[]` (`leads-to`) | a declared state |
 
 A vacuous check is worse than a rejected one: a `leads-to` invariant whose `to` state is misspelled can never be violated, and a `never-states` list holding a nonexistent id can never be reached, so both report "pass" for a model that was never actually checked.
 
@@ -104,13 +159,21 @@ so findings can be read against real scenarios instead of bare ids.
 }
 ```
 
-**Completeness contract**: when `narrative` is present, all three parts are
-required and must fully cover the model — every declared state needs a
-`narrative.states` entry, every event used in `transitions` needs a
-`narrative.events` entry, and every distinct `(from, event)` group needs a
-`narrative.scenarios` entry. Keys must reference declared ids; unknown
-references, missing coverage, and duplicate scenario keys are model validation
-errors. The report's `narrative` field echoes the block unchanged.
+**Coverage contract**: a narrative may cover **part** of the model — writing the states
+first, then the events, then the scenarios is the natural authoring order, and a partial
+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. |
+| `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. |
+
+Totals are the model's own: states = declared states, events = distinct transition
+events, scenarios = distinct `(from, event)` groups (so two guarded transitions of one
+event need one scenario, not two). The report's `narrative` field echoes the block
+unchanged.
 
 **Presenting the model**: when showing the extracted model for confirmation, render
 the natural language INLINE in the model presentation, not as a separate block.
@@ -162,13 +225,13 @@ A guard is exactly one of:
 | `never-states` | `{ states: ["ERROR"] }` | No reachable runtime state may be in the forbidden set |
 | `var-in-range` | `{ variable, min?, max?, when? }` | Every reachable runtime state selected by `when` keeps the variable in range (at least one of `min`/`max` is required) |
 | `event-before-state` | `{ event: "power_ready", state: "ACTIVE" }` | Every path entering `state` must have passed through `event` first |
-| `leads-to` | `{ from: "MIGRATING", to: "DONE" }` | Every path from `from` must eventually reach `to` |
+| `leads-to` | `{ from: "MIGRATING", to: "DONE" }`, or `to: ["DONE", "FAILED"]` | Every path from `from` must eventually reach `to`. With a target set, every path must reach at least one member. The set must be non-empty and free of duplicates |
 | `sequence` | `{ events: ["backup", "modify", "commit"] }` | Events must occur in the given order |
 | `atomicity` | `{ events: ["write"], commit: "commit", rollback?: "rollback" }` | Atomic group must end with commit/rollback before leaving scope |
 | `budget` | `{ budget: n }` | No reachable path may accumulate transition cost greater than n (A12). Costs are non-negative; a transition without `cost` counts 1, so legacy machines keep step-count semantics |
 | `probability` | `{ target, op: one of >= <= > <, p }` | P(ever hitting target) must satisfy the bound (A13, DTMC from transition `weight`, default 1; value iteration) |
 
-A7 reports the shortest violating path for each failed invariant. An empty path means the initial state already violates it.
+A7 reports a violating path for each failed invariant, and an empty path means the initial state already violates it. The state-predicate kinds, `sequence`, `atomicity` and `budget` are breadth-first, so their witness is the shortest one; `leads-to` and `probability` report a witness without claiming minimality.
 
 ### Scoping a range to a state (`when`)
 
@@ -249,10 +312,19 @@ Actions never change state or variables. Checks that care about resource discipl
 Two or more machines can be checked together with `runCompositionVerification` (DSH tool `logicprobe_compose_verify`):
 
 - 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 terminal machine is stopped and does not participate.
+- 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.
+
+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.
+
+### Reading C1 and C2
+
+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".
 
-Checks: `C1_COMPOSITION_DEADLOCK` (a reachable composite state with no move while at least one machine is not terminal) and `C2_RENDEZVOUS_NEVER_FIRES`. This is a product-space BFS, so composite state count is the product of the machines; keep `maxStates` in mind.
+`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.
 
 ## Minimal example
 
@@ -281,7 +353,7 @@ When `beforeModel` is passed to `logicprobe_verify`, the engine treats `model` a
 | Check | Purpose |
 |---|---|
 | D1 Behavioral Preservation | Every BEFORE (state, event) that could fire must still be fireable from the mapped AFTER state |
-| D2 Invariant Continuity | Every BEFORE invariant (mapped through `stateMapping`) must still hold in AFTER |
+| D2 Invariant Continuity | Every BEFORE invariant (mapped through `stateMapping`) must still hold in AFTER. State predicates go through the same reachability search as S7; `leads-to`, `sequence`, `atomicity`, `budget` and `probability` are re-decided by the searches their own probes (A9-A13) use |
 | D3 Regression Delta | Lists added/removed states, events, and transitions |
 | D4 Deadlock/Liveness Regression | New deadlock states or closed SCCs not present in BEFORE |
 
@@ -306,7 +378,7 @@ List events that must be idempotent in `idempotentEvents`. For every reachable s
 ## Advanced constraints (S8, A9-A14)
 
 - **S8 Monotonic Variables**: declare `monotonic: "inc"|"dec"` on a variable; updates must not move in the opposite direction.
-- **A9 Leads-To**: `{ kind: "leads-to", from, to }` — every path from `from` must eventually reach `to`.
+- **A9 Leads-To**: `{ kind: "leads-to", from, to }` — every path from `from` must eventually reach `to`. `to` is one state id or a non-empty array of state ids for "reach any one of these"; a duplicated member is a validation error rather than a shorthand. Either way the property stays universal: one branch that loops forever, or that stops before every target, refutes it.
 - **A10 Sequence**: `{ kind: "sequence", events }` — events must appear in order.
 - **A11 Atomicity**: `{ kind: "atomicity", events, commit, rollback? }` — once an atomic event starts, the machine must reach commit/rollback before leaving the atomic scope or terminating.
 - **A12 Budget**: `{ kind: "budget", budget }` — no reachable path may accumulate transition cost above the budget; reports the shortest over-budget path and flags reachable positive-cost cycles as unbounded.

package/skills/logicprobe/references/gap-routing-guide.md

@@ -1,36 +1,37 @@
-# Gap Routing Guide
-
-logicprobe is a design-time, qualitative model checker. For semantic dimensions it does
-not model, it does not stay silent: it routes claims to dedicated tools. This reference
-is the routing table shared by the verification report (`coverageNotes`), the
-concurrency scanner (`suggestions` on absolute claims), and manual review.
-
-Routing is a hint, not a proof. A note never verifies the claim — it marks the dimension
-as outside this engine and points at tooling that can handle it.
-
-| Dimension | What logicprobe covers today | Claim examples | Dedicated tooling | Why not here |
-|---|---|---|---|---|
-| Hard real time (timing) | Order, counts, path budgets (A12); time modeled only as counters + events | "500 ms to SAFE", "no deadline miss", "period ≤ 1 ms" | UPPAAL, IMITATOR (timed automata); binary-level timing analysis for WCET | No clocks, deadlines, or period semantics |
-| Preemptive concurrency | Event-order interleavings (A2/A3), resource pairing (A4), idempotent replay (A8) | "thread-safe", "interrupt-safe", "no priority inversion" | TSan/Helgrind (runtime), CBMC (proof), TLA+ (interleaving model), RTOS-aware analysis | Single-threaded event model; no preemption, IRQ nesting, or atomics at instruction level |
-| Hybrid control (continuous plant) | Discrete transitions and modes only | "switching is stable", "no chattering", "settling within T" | SpaceEx, Flow* (hybrid reachability), Simulink/Stateflow verification | No continuous dynamics; stability is not expressible |
-| Probabilistic / reliability | Qualitative reachability and invariants | "MTBF ≥ X", "failure rate ≤ p", "availability ≥ 99.9%" | PRISM, Storm (stochastic model checking), fault-tree / FMEA | No probability semantics |
-| Execution cost / performance | A12 budget checks over declared transition `cost` (absent = 1) | "worst-case dispatch ≤ 100 cycles" | aiT, RapiTime (real WCET at binary level) | `cost` is a modeler label, not measured execution time |
-| Multi-machine composition | Single machine verified; cross-machine contract must be documented separately | "A sends E, B always handles E" | CSP (FDR), mCRL2, TLA+ (compositional models) | No composition semantics between machines |
-| Nested/hierarchical statecharts | Flat models only; flatten before verification | parent/child states, orthogonal regions | SCXML / Stateflow (native hierarchy) | Flat state list only — flatten manually and re-confirm |
-
-## Where the routing surfaces
-
-- `logicprobe_verify` report: a model whose state/event/action names match the timing,
-  preemption, hybrid, or probability vocabulary gets informational `coverageNotes`
-  with the same routing as above.
-- A12 advisory: transitions declaring `cost` without a `budget` invariant produce
-  `A12_COST_WITHOUT_BUDGET`, pointing at the budget check.
-- `logicprobe_concurrency_scan`: absolute concurrency claims (thread-safe, lock-free,
-  interrupt-safe, ...) carry `suggestions` naming dedicated tools.
-- Manual review: when reading a plan, match its claims against the table above and
-  require dedicated evidence before accepting "always"/"never"/"guaranteed" language
-- Generators: `exportModel(model, format)` emits native inputs for UPPAAL (.xta + queries),
-  TLA+ (TLC spec + safety), PRISM (.pm + .pctl), and SPIN (Promela + ltl) from a
-  LogicModelV1 — v1 translates the core machine (guards/updates/weights; booleans as
-  integers) and leaves unrepresentable invariants as explicit warnings.
-  Self-tests: tests/exporters/run.mjs.
+# Gap Routing Guide
+
+logicprobe is a design-time, qualitative model checker. For semantic dimensions it does
+not model, it does not stay silent: it routes claims to dedicated tools. This reference
+is the routing table shared by the verification report (`coverageNotes`), the
+concurrency scanner (`suggestions` on absolute claims), and manual review.
+
+Routing is a hint, not a proof. A note never verifies the claim — it marks the dimension
+as outside this engine and points at tooling that can handle it.
+
+| Dimension | What logicprobe covers today | Claim examples | Dedicated tooling | Why not here |
+|---|---|---|---|---|
+| Hard real time (timing) | Order, counts, path budgets (A12); time modeled only as counters + events | "500 ms to SAFE", "no deadline miss", "period ≤ 1 ms" | UPPAAL, IMITATOR (timed automata); binary-level timing analysis for WCET | No clocks, deadlines, or period semantics |
+| Preemptive concurrency | Event-order interleavings (A2/A3), resource pairing (A4), idempotent replay (A8) | "thread-safe", "interrupt-safe", "no priority inversion" | TSan/Helgrind (runtime), CBMC (proof), TLA+ (interleaving model), RTOS-aware analysis | Single-threaded event model; no preemption, IRQ nesting, or atomics at instruction level |
+| Hybrid control (continuous plant) | Discrete transitions and modes only | "switching is stable", "no chattering", "settling within T" | SpaceEx, Flow* (hybrid reachability), Simulink/Stateflow verification | No continuous dynamics; stability is not expressible |
+| Probabilistic / reliability | Qualitative reachability and invariants | "MTBF ≥ X", "failure rate ≤ p", "availability ≥ 99.9%" | PRISM, Storm (stochastic model checking), fault-tree / FMEA | No probability semantics |
+| Execution cost / performance | A12 budget checks over declared transition `cost` (absent = 1) | "worst-case dispatch ≤ 100 cycles" | aiT, RapiTime (real WCET at binary level) | `cost` is a modeler label, not measured execution time |
+| Multi-machine composition | Single machine verified; cross-machine contract must be documented separately | "A sends E, B always handles E" | CSP (FDR), mCRL2, TLA+ (compositional models) | No composition semantics between machines |
+| Nested/hierarchical statecharts | Flat models only; flatten before verification | parent/child states, orthogonal regions | SCXML / Stateflow (native hierarchy) | Flat state list only — flatten manually and re-confirm |
+| Write-site / single-owner analysis | **Not covered, and not planned.** logicprobe reviews the diagram and the model; it does not read the source to see *who writes* a variable, a register or a field | "only the ISR writes this", "one owner per flag", "no double write to the CAN mailbox" | A source-side AST/rule check (e.g. the project's own include/arch checker), a static analyzer (clang-tidy, PC-lint, Coverity), or a model checker over the real code (CBMC) | It needs the source and a rule table about statements — a different input than a model or a diagram. `logicprobe_concurrency_scan` will flag the *claim* as unverified and route it here, which is the honest part of this plugin's answer |
+
+## Where the routing surfaces
+
+- `logicprobe_verify` report: a model whose state/event/action names match the timing,
+  preemption, hybrid, or probability vocabulary gets informational `coverageNotes`
+  with the same routing as above.
+- A12 advisory: transitions declaring `cost` without a `budget` invariant produce
+  `A12_COST_WITHOUT_BUDGET`, pointing at the budget check.
+- `logicprobe_concurrency_scan`: absolute concurrency claims (thread-safe, lock-free,
+  interrupt-safe, ...) carry `suggestions` naming dedicated tools.
+- Manual review: when reading a plan, match its claims against the table above and
+  require dedicated evidence before accepting "always"/"never"/"guaranteed" language
+- Generators: `exportModel(model, format)` emits native inputs for UPPAAL (.xta + queries),
+  TLA+ (TLC spec + safety), PRISM (.pm + .pctl), and SPIN (Promela + ltl) from a
+  LogicModelV1 — v1 translates the core machine (guards/updates/weights; booleans as
+  integers) and leaves unrepresentable invariants as explicit warnings.
+  Self-tests: tests/exporters/run.mjs.

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

@@ -0,0 +1,128 @@
+# Model Hash Specification
+
+`modelHash` is how a report, an archive record and a CI comparison agree on *which*
+model was verified. A hash nobody can recompute is decoration, so the algorithm, the
+normalization rules and the excluded keys are published here — and pinned by golden
+tests (`tests/engine/run.mjs`, and the parity test).
+
+## Published specifications
+
+| Spec | Since | Normalization |
+|------|-------|---------------|
+| `v1` | 1.0.0 | sorted keys, no insignificant whitespace, UTF-8 with non-ASCII preserved, **every `_`-prefixed key removed at every level** |
+| `v0` | never published | the same normalization **without** metadata filtering — the pre-1.0 behaviour, kept only so an archived hash can be checked against the old engine |
+
+`v0` was never a specification; it is the behaviour that existed before this document
+did. Do not record new hashes with it.
+
+For a model that carries no `_`-prefixed key, `v0` and `v1` produce the *identical*
+hash. That is why adopting `v1` does not invalidate any hash recorded before it.
+
+## The algorithm (`v1`)
+
+1. Take the model as JSON.
+2. Remove every key whose name starts with `_`, at every level — including objects
+   nested inside arrays.
+3. Serialize deterministically:
+   - object keys sorted by code-unit order,
+   - tokens separated by `,` and `:` with no whitespace,
+   - strings escaped as JSON, non-ASCII preserved (`réussi` stays `réussi`, not `r\u00e9ussi`),
+   - numbers written the way JavaScript `JSON.stringify` writes them,
+   - `null`, `true`, `false` spelled as JSON.
+4. `sha256` of the UTF-8 bytes, lower-case hex.
+
+In other words, with `strip_metadata` removing `_`-prefixed keys at every level:
+
+```text
+sha256(json.dumps(strip_metadata(model), sort_keys=True, separators=(',', ':'), ensure_ascii=False))
+```
+
+The TypeScript engine does not call `json.dumps`; it implements the same serialization
+directly (`stableStringify`), and the parity test compares the two engines
+byte-for-byte on every fixture. The specification, not either implementation, is the
+contract.
+
+Nothing else is normalized: no key renaming, no default filling, no unit conversion,
+no ordering of `states` or `transitions` arrays. Two models that differ only in array
+order hash differently — that is intended, because the order is part of the input.
+
+## Recomputing a hash
+
+Both commands below reproduce the engine's value exactly.
+
+```bash
+# Node
+node -e "const m=JSON.parse(require('fs').readFileSync('model.json','utf8'));const s=(v)=>Array.isArray(v)?v.map(s):v&&typeof v==='object'?Object.fromEntries(Object.keys(v).sort().filter((k)=>!k.startsWith('_')).map((k)=>[k,s(v[k])])):v;console.log(require('crypto').createHash('sha256').update(JSON.stringify(s(m))).digest('hex'))"
+
+# Node.js
+node -e "const c=require('node:crypto'),f=require('node:fs');const s=v=>Array.isArray(v)?'['+v.map(s).join(',')+']':(v&&typeof v==='object'?'{'+Object.keys(v).filter(k=>!k.startsWith('_')).sort().map(k=>JSON.stringify(k)+':'+s(v[k])).join(',')+'}':JSON.stringify(v));console.log(c.createHash('sha256').update(s(JSON.parse(f.readFileSync('model.json','utf8')))).digest('hex'))"
+```
+
+The reports carry the specification next to the value, e.g. `"hashSpec": "v1"`, so an
+archive record does not need to guess:
+
+```json
+{ "hashSpec": "v1", "modelHash": "f583202888b827922ac512a312758fa2d8cf9055b102205ecad18f81a0a7d539" }
+```
+
+Round-trip reports (`logicprobe_uml action=review`, `roundTrip`) carry `hashSpec`
+alongside `modelHash` and `parsedHash`, so a fidelity comparison is always
+spec-qualified.
+
+Every report also aggregates its hashes under `hashes`, so a baseline diff or an archive
+record reads one field instead of walking the report:
+
+```json
+{ "hashes": { "hashSpec": "v1", "modelHash": "f5832028…", "afterModelHash": "f5832028…" } }
+```
+
+A structure review hashes its inputs under the same rule but with its own keys:
+`hashes.diagram` (sha256 of the diagram text) and `hashes.matrix` (sha256 of the
+canonical — key-sorted — matrix JSON, so key order does not change the hash) when a
+dependency matrix was supplied. A data-model report carries `hashes.modelHash`; the
+data-model hash uses the same normalization but its schema is not covered by the
+published specification.
+
+## Checking an archived hash
+
+`--hash-spec` recomputes under a named specification; `--hash-check` answers whether a
+recorded value belongs to any published specification *at all*:
+
+```bash
+# verify under a named spec
+The repository CLI takes the same flag: `verify model.json --hash-spec v0`
+
+# ask about a recorded hash: prints {checked, matches, published[], verdict, verdictReason}
+The repository CLI reports which spec reproduces an archived hash: `verify model.json --hash-check 0000…deadbeef`
+```
+
+`--hash-check` exits `0` when a published spec reproduces the value and `2` when none
+does, with the explicit answer `no published hash spec reproduces <hex>`. It never
+guesses a spec to make a number match.
+
+The in-process equivalents are `modelHash(model, spec)` (TypeScript,
+`lib/engine.js`) and `model_hash(model, spec)` in the mirror, plus `hashPayload(model, spec)`
+and `hash_payload(model, spec)` for the exact bytes that are hashed.
+
+## When the hash changes
+
+A change that alters the bytes alters the hash, and that is a compatibility event:
+
+- Adding, removing or renaming an *excluded* key (`_`-prefixed): no hash change by
+  construction.
+- Adding a declared model field that a model actually uses: that model's hash changes.
+  The change must be named in the release note, and it is covered by the golden tests
+  rather than discovered by a user comparing snapshots.
+- Changing any normalization rule (separator, escaping, key order, exclusion set): a
+  **new** specification, never a silent change to `v1`. The old spec keeps its name and
+  its behaviour so archived hashes stay checkable.
+
+`--hash-spec` changes the reported `modelHash` only. The `beforeModelHash` /
+`afterModelHash` pair inside a `comparison` block is a diagnostic of one run and always
+uses `v1`.
+
+### Version history
+
+| Release | Hash change | Affected models |
+|---------|-------------|-----------------|
+| 1.0.0 | `hashSpec: "v1"` published; `_`-prefixed keys are now excluded from the hash (and accepted by the schema) | **None.** Before 1.0.0 a model carrying `_` keys was rejected outright, so no accepted model's hash moves. `v0` reproduces the old behaviour for archived values, and the two specs are byte-identical for a model without `_` keys — pinned by golden tests on `happy-path.json` and `narrative-complete.json`. |