dsh-logicprobe 0.9.0 → 1.0.0

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
 

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).