dsh-logicprobe 0.9.0 → 1.1.0

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

@@ -0,0 +1,153 @@
+# 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.
+
+**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:
+
+```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.
+
+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
+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`. |

package/skills/logicprobe/references/logic-verification-guide.md

@@ -90,288 +90,67 @@ which wastes more time than no verification at all.
 
 ## Probe Design Patterns
 
+Every probe below is implemented by `logicprobe_verify`. These patterns are here to read a finding, not to reimplement it.
+
 ### A1: Unexpected Event Injection
 
-```python
-# For each state S, list all events defined anywhere in the machine
-# For each event E not handled by S, test: what happens?
-def unexpected_event_probe(states):
-    all_events = set()
-    for trans in states.values():
-        all_events.update(trans.keys())
-    
-    findings = []
-    for state, transitions in states.items():
-        unhandled = all_events - set(transitions.keys())
-        if unhandled:
-            findings.append({
-                "state": state,
-                "unhandled_events": list(unhandled),
-                "risk": "Silent ignore or undefined behavior"
-            })
-    return findings
-```
+For every state, list the events declared anywhere in the machine that this state does not handle. An unhandled event is a silent ignore or undefined behaviour.
 
 ### A2: Race Interleaving
 
-For pairs of events that can arrive within the same tick (e.g., timer expiry + message reception):
-
-```python
-def race_interleaving(states, init, event_pairs):
-    # event_pairs = [("timeout", "ack"), ("error", "done"), ...]
-    findings = []
-    for e1, e2 in event_pairs:
-        # Path 1: e1 then e2
-        s1 = step(init, [e1, e2])
-        # Path 2: e2 then e1
-        s2 = step(init, [e2, e1])
-        if s1 != s2:
-            findings.append({
-                "events": (e1, e2),
-                "order_e1_e2_ends_in": s1,
-                "order_e2_e1_ends_in": s2,
-                "risk": "Order-dependent outcome not documented"
-            })
-    return findings
-```
+For event pairs that can arrive in the same tick, compare `e1` then `e2` against `e2` then `e1`. A different outcome is order dependence the design must state.
 
 ### A3: Order Permutation
 
-Extends A2 to N events. For small N (≤5), do full permutation. For larger N, sample:
-
-```python
-from itertools import permutations
-
-def order_permutation_probe(states, init, events, invariant_check=None):
-    findings = []
-    terminals = set()
-    for perm in permutations(events):
-        final = step(init, list(perm))
-        terminals.add(final)
-        if invariant_check and not invariant_check(final):
-            findings.append({
-                "sequence": list(perm),
-                "final_state": final,
-                "violates": "invariant"
-            })
-    if len(terminals) > 1:
-        findings.append({
-            "terminal_states": list(terminals),
-            "risk": f"Same events produce {len(terminals)} different outcomes depending on order"
-        })
-    return findings
-```
+The same question at N events. Up to 5 events permute fully; beyond that the probe samples. More than one terminal state means the outcome depends on arrival order.
 
 ### A4: Pair Symmetry
 
-```python
-# Define paired operations
-PAIRS = [
-    ("lock", "unlock"),
-    ("start", "stop"),
-    ("alloc", "free"),
-    ("enable_irq", "disable_irq"),
-    ("open", "close"),
-]
-
-def pair_symmetry_probe(states, init):
-    findings = []
-    for acquire, release in PAIRS:
-        if acquire not in all_events(states) and release not in all_events(states):
-            continue  # This pair type is not used
-        # DFS from init: every path that calls acquire must eventually call release
-        # before reaching a terminal state (or acquire again)
-        unbalanced = find_unbalanced_paths(states, init, acquire, release)
-        if unbalanced:
-            findings.append({
-                "pair": (acquire, release),
-                "unbalanced_paths": unbalanced,
-                "risk": "Resource leak or deadlock"
-            })
-    return findings
-```
+For paired operations (lock/unlock, start/stop, alloc/free, enable_irq/disable_irq, open/close), search from the initial state for a path that acquires without releasing before it terminates or acquires again. That is a leak or a deadlock.
 
 ### A5: Boundary Blast
 
-```python
-def boundary_blast(counters, timestamps):
-    findings = []
-    for name, val in counters.items():
-        test_values = [0, 1, val-1, val, val+1, 2**32-1, 2**32]
-        for tv in test_values:
-            if tv < 0 or tv > val:
-                findings.append({
-                    "variable": name,
-                    "value": tv,
-                    "risk": f"Counter overflow/underflow at {tv} (max defined: {val})"
-                })
-    # Timestamp wraparound (millis() / sys_tick())
-    # On 32-bit ARM: wraparound at ~49.7 days for 1ms tick
-    for name, val in timestamps.items():
-        findings.append({
-            "variable": name,
-            "risk": f"Timestamp wraparound not handled — check elapsed_ms() / elapsed_ticks() pattern"
-        })
-    return findings
-```
+Test each counter at 0, 1, max-1, max and max+1. Flag overflow and underflow. Timestamps wrap too: a 32-bit millisecond clock wraps after about 49.7 days, so check every `elapsed_*()` pattern.
 
 ### A6: Resource Injection
 
-```python
-RESOURCE_FAILURES = {
-    "malloc": "returns NULL",
-    "queue_send": "queue full",
-    "semaphore_take": "timeout",
-    "message_alloc": "pool exhausted",
-}
-
-def resource_injection_probe(states):
-    findings = []
-    for state, transitions in states.items():
-        for event in transitions:
-            for resource, failure in RESOURCE_FAILURES.items():
-                if resource in event.lower() or resource in state.lower():
-                    # Simulate: what if this resource call fails in this state?
-                    # Does the machine have a recovery transition?
-                    has_recovery = any(
-                        "error" in t.lower() or "fail" in t.lower() or "retry" in t.lower()
-                        for t in transitions.values()
-                    )
-                    if not has_recovery:
-                        findings.append({
-                            "state": state,
-                            "resource": resource,
-                            "failure_mode": failure,
-                            "risk": f"No recovery path if {resource} {failure} in state {state}"
-                        })
-    return findings
-```
+For every state and transition, ask what happens when the resource call fails: `malloc` returns NULL, a queue is full, a semaphore times out, a pool is exhausted. No error, fail or retry transition means no recovery path.
 
 ### A7: Minimal Counter-Example
 
-```python
-from collections import deque
-
-def shortest_violating_path(states, init, invariant_check):
-    """BFS to find the shortest event sequence that violates an invariant."""
-    queue = deque([(init, [])])
-    visited = set()
-    while queue:
-        state, path = queue.popleft()
-        if state in visited:
-            continue
-        visited.add(state)
-        
-        if not invariant_check(state):
-            return path  # Shortest violating path found
-        
-        for event, next_state in states.get(state, {}).items():
-            queue.append((next_state, path + [event]))
-    
-    return None  # Invariant holds for all reachable states
-```
-
-That template decides one runtime state at a time, so it only fits the state-predicate kinds. A `leads-to`, `sequence`, `atomicity`, `budget` or `probability` invariant asserts a property of a whole run: reuse the search in its own section (A9-A13) as the witness finder, or A7 will report "all invariants hold" for a model where one of them fails.
+Breadth-first search for the shortest event sequence that violates an invariant. It decides one runtime state at a time, so it fits the state-predicate kinds only. `leads-to`, `sequence`, `atomicity`, `budget` and `probability` assert a property of a whole run and use the search in their own sections (A9-A13).
 
 ### S8: Monotonic Variables
 
-For counters or progress variables that must only move in one direction, list the events that increase/decrease them. Any event that moves against the declared direction is a finding.
-
-```python
-MONOTONIC_VARS = [
-    {"name": "retry_count", "direction": "inc", "increase_events": ["retry"], "decrease_events": []},
-]
-```
+For counters that must move one way only, list the events that change them. An event that moves against the declared direction is a finding.
 
 ### A8: Idempotent Replay
 
-For events that must be safe to retry/replay, apply the event twice from every reachable state. If the second application changes state or is not possible, flag it.
-
-```python
-IDEMPOTENT_EVENTS = {"retry", "sync", "webhook_delivery"}
-```
+Apply each retryable event twice from every reachable state. A second application that changes state, or cannot happen, is a finding.
 
 ### A9: Leads-To
 
-For progress claims ("from MIGRATING, eventually DONE"), check every path from the source state. If a path dead-ends or loops before reaching the target, flag it. When the code has several acceptable outcomes, give the invariant a target set and check every path reaches at least one member; that is still a universal claim, so a branch that reaches none of them fails.
-
-```python
-LEADS_TO = [
-    ("MIGRATING", "DONE"),
-    # or a set of acceptable outcomes
-    ("DRAINING", ["IDLE", "FAULT"]),
-]
-```
+For a progress claim ("from MIGRATING, eventually DONE"), check every path from the source state. A path that dead-ends or loops before the target fails. A target set is still a universal claim: a branch that reaches none of its members fails.
 
 ### A10: Sequence Order
 
-For ordered event sequences ("backup before modify before commit"), search for any path where a later event occurs before an earlier one.
-
-```python
-SEQUENCES = [
-    ["backup", "modify", "commit"],
-]
-```
+For an ordered sequence ("backup, then modify, then commit"), search for a path where a later event occurs before an earlier one.
 
 ### A11: Atomicity
 
-For all-or-nothing groups, track whether an atomic event has started and whether commit/rollback has occurred. Leaving the atomic scope or reaching a terminal state before commit/rollback is a violation.
-
-```python
-ATOMIC_GROUPS = [
-    {"events": ["write"], "commit": "commit", "rollback": "rollback"},
-]
-```
+For all-or-nothing groups, track whether the atomic event started and whether commit or rollback followed. Leaving the scope, or terminating, before commit or rollback is a violation.
 
 ### A12: Budget (Worst-Case Path Cost)
 
-For performance-sensitive claims ("the dispatch path stays within 100 cycles", "worst-case latency ≤ budget"), model each transition with an execution cost and declare a budget:
-
-```python
-TRANSITION_COSTS = {  # (from, event): cost; absent entries count as 1
-    ("BOOT", "calibrate_done"): 40,
-    ("IDLE", "enable"): 5,
-    ("RUN", "watchdog_expiry"): 15,
-}
-BUDGETS = [
-    {"id": "dispatch-budget", "description": "worst-case path within budget", "budget": 100},
-]
-```
-
-Probe: find the shortest path from init whose accumulated cost exceeds the budget; report it verbatim. A reachable cycle with positive total cost means cost can grow without bound — flag it as a budget violation regardless of the declared budget.
-
-In DSH (`logicprobe_verify`), `cost` is an optional field on transitions (absent = 1) and `budget` is an invariant kind; A12 runs automatically. Cost values are modeler-provided static labels — they verify the model against the declared budget, not the real WCET, which needs binary-level timing analysis.
+Give each transition a `cost` and declare a `budget`. The probe reports the shortest path whose accumulated cost exceeds it. A reachable cycle with positive cost means cost grows without bound, which is a violation whatever the budget says. Costs are modeler labels: this checks the model against its budget, not real WCET.
 
 ### A13: Probability Reachability (DTMC)
 
-For claims with a reliability/probability flavor ("at least 90% of runs reach SAFE", "P(broke first) ≥ 0.75"), attach a relative weight to each branch and declare the bound. Absent weight = 1; weight 0 means the branch never fires probabilistically.
-
-```python
-TRANSITION_WEIGHTS = {  # (from_state, event): weight; absent entries count as 1
-    ("RUN", "ok"): 9,
-    ("RUN", "bad"): 1,
-}
-PROBABILITY_INVARIANTS = [
-    {"id": "reliability", "target": "SAFE", "op": ">=", "p": 0.9},
-]
-```
-
-Probe: solve P(ever reaching `target`) from INIT by value iteration over the reachable absorbing chain; compare against the bound. In DSH (`logicprobe_verify`), `weight` on transitions plus a `probability` invariant runs A13 automatically. This is a qualitative DTMC check of the modeler's weights — real MTBF/failure-rate numbers need PRISM/Storm or fault-tree analysis.
+Give each branch a relative `weight` and declare a `probability` bound. The probe solves P(ever reaching the target) by value iteration and compares it with the bound. Absent weight is 1; weight 0 never fires. This is a qualitative check of the weights, not a measured failure rate.
 
 ### A14: Deadline (Discrete Tick Clock)
 
-For real-time-sounding claims ("must leave BUSY within 3 ticks", "watchdog resets before deadline"), declare which events advance the clock and cap per-state residency:
-
-```python
-TICK_EVENTS = {"tick"}
-STATE_MAX_TICKS = {"BUSY": 3}
-```
-
-Probe: explore residency — a `tick` step that keeps the machine resident past `maxTicks` is a deadline miss; report the over-residency path. In DSH (`logicprobe_verify`), state `maxTicks` plus top-level `tickEvents` run A14 automatically. This checks the model's declared deadlines, not real execution time (see Known Limitations below; hard real-time semantics route to UPPAAL).
-
-### Standalone engine (non-DSH, JSON models)
-
-`references/logicprobe-engine.py` is an exact Python mirror of the DSH tools: `verify model.json` runs all 22 checks + D1-D4 with a `--before-model`/optional `--state-mapping`; `compose m1.json m2.json ... --rendezvous a,b` runs C1/C2 composition; `export model.json --format uppaal|tla|prism|spin` reproduces the four exporters byte-for-byte. It reads the same LogicModelV1 JSON as DSH, so a model verified in one host verifies identically in the other (checked by tests/python/run.mjs).
+Declare which events advance the clock (`tickEvents`) and cap per-state residency with `maxTicks`. A tick that keeps the machine resident past its cap is a deadline miss, and the probe reports the over-residency path. This checks declared deadlines, not execution time.
 
 ## Counter-Example Interpretation
 
@@ -409,7 +188,7 @@ When a probe finds a counter-example, classify it:
 ### What This Method CANNOT Detect
 
 - **Implementation bugs**: The C code may have errors not present in the model
-- **Timing-dependent bugs**: Python model does not simulate real-time constraints
+- **Timing-dependent bugs**: the model does not simulate real-time constraints
 - **Compiler/optimization issues**: Volatile omission, reordering, inlining effects
 - **Hardware-specific behavior**: Memory-mapped I/O timing, DMA races, cache coherency
 - **Undocumented behavior**: If the plan doesn't describe a transition, the model can't either
@@ -423,7 +202,7 @@ When a probe finds a counter-example, classify it:
 
 ### Model Fidelity Warning
 
-The Python model is an APPROXIMATION. It models state transitions, not execution semantics. A model that passes all 22 checks (S1-S8 structural, A1-A14) means the plan's LOGIC is consistent — NOT that the implementation will work. Always follow logic verification with code-level review.
+The model is an APPROXIMATION. It models state transitions, not execution semantics. A model that passes all 22 checks (S1-S8 structural, A1-A14) means the plan's LOGIC is consistent — NOT that the implementation will work. Always follow logic verification with code-level review.
 
 ## Refactoring Verification
 
@@ -455,7 +234,7 @@ If the plan claims "simplification" but the numbers don't decrease, flag as UNSU
 
 **Deadlock regression**: A refactoring that splits one state into two should not introduce a deadlock path that didn't exist before. Run S2 on AFTER and compare to BEFORE's deadlock report.
 
-In the Python harness, set `BEFORE_STATES`, `BEFORE_INIT`, `BEFORE_TERMINALS`, and `STATE_MAPPING` to run D1-D4 automatically after the standard checks.
+For before/after comparison, pass the earlier model as `beforeModel` and an optional `stateMapping`; the D1-D4 checks then run after the standard ones.
 
 ### Common Refactoring Bugs Caught by This Method
 
@@ -466,20 +245,20 @@ In the Python harness, set `BEFORE_STATES`, `BEFORE_INIT`, `BEFORE_TERMINALS`, a
 
 ## Manual Verification Mode
 
-When Python is NOT available (air-gapped embedded dev machine, locked-down Windows), execute each check manually. The agent performs the verification using its own reasoning — the methodology is identical, only the execution engine changes.
+When no engine can run (air-gapped machine, locked-down host), execute each check manually. The agent performs the verification using its own reasoning — the methodology is identical, only the execution engine changes.
 
 ### Size Limit
 
-Manual verification is reliable for state machines with **≤ 10 states and ≤ 30 transitions**. For larger machines, manual BFS and cycle detection become error-prone. If the machine exceeds this threshold and Python is unavailable, either:
+Manual verification is reliable for state machines with **≤ 10 states and ≤ 30 transitions**. For larger machines, manual BFS and cycle detection become error-prone. If the machine exceeds this threshold and no engine can run, either:
 
 - Decompose the machine into sub-machines and verify each independently, then check cross-machine contracts manually
-- Flag the size limitation as a finding and recommend the user run the Python harness offline
+- Flag the size limitation as a finding and recommend running the engine offline from the repository
 
 ### Prerequisites
 
 - Transition table and model narrative have been extracted and confirmed with the user
 - You have the full table in context (from Phase 2 extraction step)
-- **Harness validation** (Python mode only): After filling in `verification-harness.py`, translate the Python `STATES` dict BACK into a transition table and compare it against the confirmed extraction table. If they differ, fix the harness. This catches typo and whitespace errors in manual dict construction.
+- **Model validation**: when a host with an engine becomes available, run the extracted model there and compare its findings with the hand-checked ones.
 
 ### Phase 2a — Manual Structural Checks
 
@@ -515,7 +294,7 @@ Manual verification is reliable for state machines with **≤ 10 states and ≤
 
 ### Manual Mode Output Format
 
-For each finding, output the same structured format as the Python harness:
+For each finding, output the engine structured format:
 
 ```text
 [CHECK] S1 Reachability
@@ -537,9 +316,7 @@ Manual verification takes longer but produces identical-quality findings. The ke
 2. Read plan → Phase 1 (enumerate claims)
 3. Detect behavioral claims → trigger logic-primitive escalation
 4. Load this guide
-5. Check Python: `python3 --version` or `python --version`
-6a. Python ≥ 3.6 → load verification-harness.py → fill in MODEL → run
-6b. No Python → use Manual Verification Mode (see above) — execute each check step by step
+5. Run the checks: the native tool when the host has it, otherwise Manual Verification Mode (see above), step by step
 7. Extract model → show transition table → GET USER CONFIRMATION
 8. Run Phase 2a (8 structural primitives) → log results
 9. Run Phase 2b (14 adversarial probes) → log results
@@ -548,4 +325,4 @@ Manual verification takes longer but produces identical-quality findings. The ke
 12. Include in Phase 5 (structured output)
 ```
 
-Never skip step 5. A verified model based on wrong extraction is worse than no verification — it creates false confidence.
+Never skip the check. A verified model based on wrong extraction is worse than no verification — it creates false confidence.

package/skills/logicprobe-concurrency/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: logicprobe-concurrency
+description: "Use when a design or plan claims concurrency safety (thread-safe, lock-free, no data race, ISR-safe) or names shared state, mutexes, atomics or interrupts. Mines the claims and routes each to dedicated verification (TSan, Helgrind, CBMC, TLA+); it does not prove concurrency safety. Doctrine: the logicprobe skill."
+---
+
+# Logic Probe — Concurrency Claims
+
+This skill does **not** prove concurrency safety, and no report from it should ever be read as a proof. It mines a document, plan or code review for concurrency claims, marks them `UNVERIFIED`, and routes each one to the tool that can actually decide it.
+
+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 behavioural verification of a state machine rather than a judgement about concurrency claims.
+
+## When This Skill Applies
+
+**Only after confirming the target actually has concurrency requirements or behaviour** — multiple threads, async tasks, interrupts, shared state, or parallel execution. If the target is purely sequential, do not invoke concurrency mining; there is nothing to mine.
+
+| The claim | How it is treated |
+|---|---|
+| Absolute: "thread-safe", "lock-free", "no data race", "interrupt-safe", "ISR-safe" | error / `UNVERIFIED` unless dedicated evidence is provided |
+| Risk keyword: "race condition", "shared variable", "mutex", "atomic", "shared memory", "critical section", `ISR`, `IRQ`, `NMI`, `disable_irq` / `enable_irq` | warning — review whether the plan actually addresses it |
+| Lock/unlock, alloc/free, start/stop pairing where ordering matters | routed to `logicprobe` model verification (A4 pair symmetry), which can decide balance inside the modelled machine |
+
+In DSH, run the `logicprobe_concurrency_scan` tool. For manual review, follow [`references/concurrency-risk-guide.md`](references/concurrency-risk-guide.md).
+
+## Routing: What Decides Each Claim
+
+Mining a claim is not verifying it. Hand each one to a tool that can:
+
+| Dimension | Tool that decides it |
+|---|---|
+| Data races, lock-ordering, lock-free algorithms | ThreadSanitizer, Helgrind, or a model checker over the real code (CBMC) |
+| Interrupt/ISR races, critical sections | RTOS-aware interrupt analysis, or a TLA+ model of the ISR/task interleaving |
+| Protocol-level interleaving of discrete events | `logicprobe_verify` (S1-S8 / A1-A14) and `logicprobe_compose_verify` (C1/C2) |
+| Hard real time: deadlines, periods, preemption | Scheduling analysis (RMA/EDF) and a timing tool — not logicprobe |
+| Probability or reliability claims | PRISM/Storm, fault-tree analysis |
+
+The full routing table, including hard-real-time, hybrid-control and execution-cost dimensions, is [`../logicprobe/references/gap-routing-guide.md`](../logicprobe/references/gap-routing-guide.md). `logicprobe_verify` reports carry the same routing as informational `coverageNotes` on matching models.
+
+## Rules for This Mode
+
+1. **Mining, not proof.** Report a concurrency claim as `UNVERIFIED` with the routing target; never as passing.
+2. **No absolute language in the answer.** "This is thread-safe" is exactly the claim being mined, not a result this skill can produce.
+3. **One counterexample is enough to refute.** If a race is suspected, the deliverable is the interleaving that breaks it plus the harness that demonstrates it (TSan/Helgrind output), not an argument.
+4. **Sequential targets are out of scope.** If nothing runs concurrently, say so and stop.

package/skills/{logicprobe → logicprobe-concurrency}/references/concurrency-risk-guide.md

@@ -53,4 +53,4 @@ Manual checklist:
 - General: TLA+, SPIN, Alloy
 - Rust: loom, Shuttle
 
-Other semantic dimensions (hard real time, hybrid control, probability/reliability, execution cost) route through the same pattern — see `references/gap-routing-guide.md`.
+Other semantic dimensions (hard real time, hybrid control, probability/reliability, execution cost) route through the same pattern — see the full table in the `logicprobe` skill: `../logicprobe/references/gap-routing-guide.md`.

package/skills/logicprobe-datamodel/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: logicprobe-datamodel
-description: "Use when reviewing design documents, architecture specs, technical proposals, schema changes, data contracts, or refactoring plans that make claims about entities, fields, constraints, relationships, data invariants, migration coverage, copy consistency, rollback symmetry, or before/after data-model equivalence. When the document contains schema changes, data migration logic, or data-behavioural assertions ('all records must have X', 'target count equals source count', 'no orphan rows', 'ids never move backwards', 'exactly one row per event', 'rollback restores the old shape', 'migration is non-breaking'), escalate into data-model verification — generate and run executable checks for structural consistency (DS1-DS4), data invariants and adversarial probes (DA1-DA12: null/boundary injection, uniqueness, referential integrity, migration coverage, copy consistency, rollback symmetry, idempotency, monotonicity, ordering, leads-to, atomicity), and before/after data regression (DD1-DD4) before trusting any claim. Behavioural, state-machine, protocol and concurrency claims belong to the sibling logicprobe skill. Also proactively SUGGEST this skill for code-level data/schema behavioural questions."
+description: "Use when reviewing design docs, specs, plans or migrations claiming entities, fields, constraints, relationships, data invariants, or before/after data-model equivalence: schema changes, migration logic, or data guarantees ('all records must have X', 'no orphan rows', 'ids unique') want executable data-model verification (migration coverage, copy consistency, rollback symmetry, DD1-DD4 regression). State machines and protocols: logicprobe; diagrams: logicprobe-uml."
 ---
 
 # Logic Probe Data
 
-Documents are not truth — data models are. Verify every verifiable data claim before accepting or acting on a design.
+An unverified data model fails later. Model the schema and the migration, run them, and it becomes clear. Check every data claim before you act on it.
 
 ## Methodology
 
@@ -44,8 +44,7 @@ Escalate immediately if the document contains ANY of:
 ```text
 Document claims → Extract DataModelV1 → Runtime check:
   ├── DSH + `logicprobe_datamodel_verify` tool available → build DataModelV1 → call tool → structured report
-  ├── Python available → fill references/data-model-harness.py → run → report
-  └── No Python → Manual Verification Mode (references/data-model-guide.md)
+  └── No engine available → Manual Verification Mode (references/data-model-guide.md)
 
 Refactoring variant:
   Extract BEFORE DataModelV1 + AFTER DataModelV1
@@ -54,6 +53,8 @@ Refactoring variant:
     → Flag any invariant that held in BEFORE but fails in AFTER
 ```
 
+The **DataModelV1 shape** is in [`references/data-model-schema.md`](references/data-model-schema.md): entities, fields, keys, relationships, invariants, boundary checks, and the optional before/mapping/copy/migration/backup blocks. Those field names are the tool contract. A hand-written model that disagrees with them is rejected, not guessed at.
+
 ## Checks
 
 ### DS — Data structure

package/skills/logicprobe-datamodel/references/data-model-guide.md

@@ -1,6 +1,6 @@
 # Data Model Manual Verification Mode
 
-Use this when neither the DSH `logicprobe_datamodel_verify` tool nor Python is available. It mirrors the automated DS/DA/DD checks as a structured checklist.
+Use this when the DSH `logicprobe_datamodel_verify` tool is not available. It mirrors the automated DS/DA/DD checks as a structured checklist.
 
 ## 1. Extract the DataModelV1 table
 

package/skills/logicprobe-datamodel/references/data-model-schema.md

@@ -1,6 +1,6 @@
 # DataModelV1 — logicprobe-datamodel Schema
 
-The `logicprobe_datamodel_verify` tool accepts a structured JSON data model. The engine runs DS/DA checks, and DD1-DD4 when `beforeModel` is supplied. It is host-agnostic; DSH uses the native tool, non-DSH hosts use `data-model-harness.py`.
+The `logicprobe_datamodel_verify` tool accepts a structured JSON data model. The engine runs DS/DA checks, and DD1-DD4 when `beforeModel` is supplied. The schema is host-agnostic: the native tool and the repository engine take the same JSON.
 
 ## Top-level model