dsh-logicprobe 0.8.1 → 1.0.0

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

@@ -90,284 +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
-```
+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.
-
-```python
-LEADS_TO = [
-    ("MIGRATING", "DONE"),
-]
-```
+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
 
@@ -405,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
@@ -419,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
 
@@ -438,7 +221,7 @@ The BEFORE model comes from **code, not the plan**. The plan may describe the cu
 
 **Behavioral preservation**: For each event sequence accepted by BEFORE, trace the same sequence in AFTER. If AFTER ends in a different state (or rejects the sequence), flag as BEHAVIORAL DELTA. The plan must explicitly document this delta — if it doesn't, it's a regression.
 
-**Invariant continuity**: Re-run S7 invariant checks on both models. Any invariant that passes on BEFORE but fails on AFTER is a regression — the refactoring broke an existing guarantee.
+**Invariant continuity**: Re-decide every invariant on AFTER, mapped through `stateMapping`. Any invariant that holds on BEFORE but fails on AFTER is a regression — the refactoring broke an existing guarantee. 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, so continuity agrees with the standalone verdict. A state reference that the mapping drops is reported as a mapped-state warning instead of silently changing the property.
 
 **Complexity delta**: Count objectively:
 
@@ -451,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
 
@@ -462,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
 
@@ -507,11 +290,11 @@ Manual verification is reliable for state machines with **≤ 10 states and ≤
 
 **A6 Resource Injection**: For each state that appears to allocate (names containing "alloc", "init", "start", "open", "connect", "begin"), check if there is a recovery/error path if the allocation fails. If no recovery exists, flag as RESOURCE VULNERABLE.
 
-**A7 Minimal Counter-Example**: For each invariant that failed in S7, find the SHORTEST event sequence that violates it. This is the most useful output — it gives the plan author an exact repro.
+**A7 Minimal Counter-Example**: For each invariant that failed, find the event sequence that violates it. This is the most useful output — it gives the plan author an exact repro. The searches for state predicates, `sequence`, `atomicity` and `budget` are breadth-first, so their witness is the shortest one; the `leads-to` walk and the `probability` bound report what they found without claiming minimality.
 
 ### 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
@@ -533,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
@@ -544,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, or before/after data-model equivalence. When the document contains schema changes, data migration logic, or data-behavioral assertions ('all records must have X', 'target count equals source count', 'no orphan rows', 'migration is non-breaking'), escalate into data-model verification — generate and run executable checks for structural consistency, data invariants, migration coverage, copy consistency, and breaking changes before trusting any claim. Also proactively SUGGEST this skill for code-level data/schema behavioral 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
 

package/skills/logicprobe-structure/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: logicprobe-structure
+description: "Use when reviewing architecture, module structure or a dependency diagram: parse a component, package, class or deployment diagram into a dependency graph and check isolated nodes, dangling endpoints, cycles, allowed-dependency violations, layer violations and missing required edges. Audits the diagram, not the code — reconcile it with a source-side scan. Doctrine: the logicprobe skill."
+---
+
+# Logic Probe — Structure and Dependency Review
+
+A component diagram is a model of an architecture, and a model can be wrong. This skill audits the graph the diagram actually draws — nodes and dependency arrows — against a declared dependency matrix, and says plainly what that does and does not prove.
+
+The claim-verification doctrine it inherits — cite evidence, read `verdict` and never `ok` — lives in the `logicprobe` skill. Load that one for behavioural claims (state machines, protocols, timing); load this one when the question is *where the dependencies point*.
+
+## When This Skill Applies
+
+| The task involves… | What it does |
+|---|---|
+| "Review this architecture", "are the module dependencies sound", "is the layering right" | Parse the structure diagram into a graph, then run the structural checks below |
+| A component / package / class / deployment diagram (PlantUML) or a Mermaid class diagram | `logicprobe_structure_verify` reads nodes, containers, labels and arrows; nothing is discarded |
+| A rule table of allowed dependencies (allow/deny, layers, required edges) | Every edge is judged against it and reported with the rule ids it matched |
+| One architecture drawn at several levels (repository / module / subdirectory) | `diagrams: [{name, diagram, parent}]`: each level is checked on its own, then against its declared parent, with the per-pair node/edge/expansion counts (`UML028`-`UML031`) |
+| A diagram that must be reconciled with an include/graph check over the source | The per-edge rule ids are the meeting point: a difference between the two is the finding worth chasing |
+
+A host without the tools runs the repository engine on the same diagram text, and on a `granularity` manifest for a multi-level set.
+
+## What It Checks
+
+| Code | Severity | What it means |
+|---|---|---|
+| `UML020_ISOLATED_NODE` | warning | A declared, non-container node with no edge at all. A dead entry, or a dependency the diagram forgot to draw. |
+| `UML021_DANGLING_REFERENCE` | error | An arrow endpoint that no declaration ever introduced. In a component diagram this is how a dependency on a component that does not exist stays invisible. |
+| `UML022_CYCLE` | error | A directed cycle, reported as the **shortest** cycle path. A cycle means no build order and no layering can hold. |
+| `UML023_DISALLOWED_EDGE` | error | An edge the matrix forbids — or, with `default: "deny"`, an edge no rule permits. The denying rule id is named. |
+| `UML024_LAYER_VIOLATION` | error | An edge from a lower declared layer into a higher one (a child depending on its parent). Downward edges are allowed. |
+| `UML025_MISSING_EXPECTED_EDGE` | warning | A rule with `require: true` whose edge the diagram does not draw — including the case where no node matches the source pattern at all. The matrix and the diagram disagree. |
+| `UML026_NO_NODES` | error | The text declares no node, so there is no structure to review. |
+| `UML028_UNKNOWN_PARENT` | error | A level names a parent that is not in the set. |
+| `UML029_REFINEMENT_VIOLATION` | error | Multi-level only: a child invents a dependency at the parent level, or drops a parent edge instead of expanding it into a path. |
+| `UML030_PARENT_CYCLE` | error | The declared parent relation is not a forest. |
+| `UML031_NO_DIAGRAMS` | error | Nothing was supplied to compare. |
+
+## The Dependency Matrix
+
+The matrix is the single source of truth the diagram is checked against. Keep it next to the rules it encodes, in JSON:
+
+```json
+{
+  "rules": [
+    { "id": "R1-app-may-use-hal", "source": "app.*", "allow": ["hal.*"], "deny": ["hal.internal"] },
+    { "id": "R2-adapter-owns-hal", "source": "PAY", "allow": ["DRV"], "deny": ["SVC"] },
+    { "id": "R3-no-back-edges", "source": "*", "deny": ["SVC"] },
+    { "id": "R4-persistence-required", "source": "PAY", "allow": ["DB"], "require": true }
+  ],
+  "layers": [
+    { "name": "app", "members": ["SVC", "PAY"] },
+    { "name": "hal", "members": ["DRV", "DB"] }
+  ],
+  "default": "deny"
+}
+```
+
+- `source`, `allow`, `deny` and `layers[].members` accept **node ids or globs** (`*` any run, `?` one character).
+- **`deny` wins globally.** A later rule's allow never resurrects an edge an earlier rule forbade; the result cannot depend on rule order.
+- `default: "allow"` (the default) means only the rules judge: an edge no rule mentions is `default`. `default: "deny"` closes the matrix — anything unlisted is `UML023`.
+- `require: true` turns a rule into an expectation about the diagram (`UML025`); it needs `allow` to say which edges must exist.
+- Layers are ordered **top first**: an edge from an earlier layer to a later one is allowed, the reverse is `UML024`.
+- Every edge is echoed in `edgeVerdicts` as `{from, to, line, matchedRules, allowed, basis}`, where `basis` is `allow` / `deny` / `default` / `unlisted`. That is the audit trail for the reconciliation below.
+
+## Reconciling With a Source-Side Check
+
+This tool audits the **diagram**; an include or dependency scan audits the **code**. They answer the same question from two sides, and each side can be the one that is wrong:
+
+1. Run both. Keep the rule ids identical on both sides — that is what makes a difference explainable.
+2. For every rule id, compare: does the diagram draw the edge, and does the source contain the dependency?
+3. Classify each difference instead of averaging it away:
+   - **Diagram missing an edge the code has** — the diagram is stale (`UML025` fires when the rule is `require: true`).
+   - **Diagram drawing an edge the code does not have** — either the diagram is aspirational, or the source scan's scope is narrower (different file set, generated code, conditional compilation).
+   - **Code violating an allowed dependency the diagram never showed** — the architecture defect the diagram was hiding. This is the one worth acting on.
+4. Report the difference with both citations. Never present the diagram as evidence about the code without saying which side produced which half.
+
+## Limits — Say These Out Loud
+
+- **The diagram may be wrong.** A clean `pass` means the drawn graph is internally consistent and satisfies the matrix — not that the code matches it. Only the reconciliation above touches the code.
+- **No transitive closure by default.** `A → B → C` does not report `A` reaching `C`; write the rule you mean, or add the edge the code actually has.
+- **No runtime behaviour.** Calls through function pointers, DI containers, registries, plugin loading and dynamic dispatch do not appear as edges. A missing edge is not proof of a missing dependency.
+- **Containers are not dependencies.** Package/rectangle nodes carry members, not arrows; they are exempt from `UML020`.
+- **The matrix is a claim too.** A matrix nobody maintains produces confident, wrong verdicts. Treat a rule change as a code change: review, version, cite.
+- **State machines are a different question.** For guards, deadlocks, budget, probability or deadlines, that is `logicprobe` (verification) and `logicprobe-uml` (the diagram round trip).
+
+## Rules for This Mode
+
+1. **Never read a structure diagram as a state machine.** The state-machine front end refuses such a file (`UML_NOT_A_STATE_DIAGRAM`); this skill reads it as the dependency graph it is. The two must not be mixed in one report.
+2. **Quote the rule id for every judged edge.** "Not allowed" without the rule is an opinion; `matchedRules` makes it a finding.
+3. **Run the numbers, never the impression.** An isolated node and a back edge are exactly what a reader misses by eye; that is why the check exists.
+4. **Report the diagram-code difference, not just the diagram.** A structure review that never touches the source is a review of a drawing.
+
+The full matrix schema, a worked example and the reconciliation worksheet are in [`references/structure-review-guide.md`](references/structure-review-guide.md).