dsh-logicprobe 0.9.0 → 1.0.0

package/lib/export-tool.js

@@ -1,5 +1,13 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js';
 import { exportModel } from './exporters.js';
+/** The model hash of an export's input, when the input validates (the success path always does). */
+function exportHashes(model) {
+    const validation = validateModel(model);
+    return validation.ok
+        ? { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(validation.model) }
+        : { hashSpec: DEFAULT_HASH_SPEC };
+}
 export const LOGICPROBE_EXPORT_TOOL_NAME = 'logicprobe_export';
 /**
  * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
@@ -36,10 +44,27 @@ export const logicProbeExportTool = defineTool({
     async execute(args) {
         try {
             const result = exportModel(args.model, args.format);
-            return { ok: true, format: result.format, primary: result.primary, ...(result.extras === undefined ? {} : { extras: result.extras }), warnings: result.warnings };
+            const warnings = result.warnings ?? [];
+            const nextSteps = [];
+            if (warnings.length > 0)
+                nextSteps.push('The target notation cannot express some invariants; the warnings name each one — verify them in the target tool rather than assuming they carried over.');
+            nextSteps.push('Run the exported file through its own tool (verify/compile) before trusting the translation; logicprobe guarantees the encoding, not the target checker\'s verdict.');
+            return {
+                ok: true,
+                ran: true,
+                ...verdictOf(0, warnings.length),
+                schema: REPORT_SCHEMAS.export,
+                format: result.format,
+                primary: result.primary,
+                ...(result.extras === undefined ? {} : { extras: result.extras }),
+                hashes: exportHashes(args.model),
+                warnings,
+                nextSteps,
+            };
         }
         catch (error) {
-            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            const message = error instanceof Error ? error.message : String(error);
+            return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.export, errorCode: 'MODEL_INVALID', error: message };
         }
     },
 });

package/lib/granularity.js

@@ -0,0 +1,237 @@
+/**
+ * Multi-granularity structure review: one architecture, several levels of detail.
+ *
+ * A module diagram and the repository-wide diagram it belongs to are two views of one
+ * fact, and nothing keeps them in step — the child grows a dependency the parent never
+ * had, or the parent keeps an arrow the child quietly stopped drawing. This module
+ * checks that a child diagram is a **refinement** of its declared parent:
+ *
+ * - every dependency the child draws between two nodes the parent also has must exist in
+ *   the parent (nothing appears out of nowhere);
+ * - an edge the parent draws and the child does not must be *expanded* in the child, i.e.
+ *   a child path must connect the same two ends;
+ * - the declared parent relation must be a forest, not a cycle.
+ *
+ * Every per-diagram structural check still runs, and its findings are tagged with the
+ * diagram they came from (`file`), so one report can carry several diagrams without the
+ * findings becoming anonymous.
+ *
+ * @module logicprobe-granularity
+ */
+import { createHash } from 'node:crypto';
+import { REPORT_SCHEMAS, canonicalJson, verdictOfFindings } from './engine.js';
+import { parseStructure, reviewStructure } from './structure.js';
+/** Reachability in one diagram, ignoring edge direction? No: a dependency path is directed. */
+function reaches(graph, from, to) {
+    const adjacency = new Map();
+    for (const node of graph.nodes)
+        adjacency.set(node.id, []);
+    for (const edge of graph.edges)
+        adjacency.get(edge.from)?.push(edge.to);
+    const seen = new Set([from]);
+    const queue = [from];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const next of adjacency.get(current) ?? []) {
+            if (next === to)
+                return true;
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            queue.push(next);
+        }
+    }
+    return false;
+}
+/** The parent relation must be a forest: report the first cycle it contains, if any. */
+function parentCycle(diagrams) {
+    const byName = new Map(diagrams.map((entry) => [entry.name, entry]));
+    for (const start of diagrams) {
+        const path = [start.name];
+        const seen = new Set([start.name]);
+        let cursor = start.parent;
+        while (cursor !== undefined) {
+            if (seen.has(cursor)) {
+                path.push(cursor);
+                return path;
+            }
+            seen.add(cursor);
+            path.push(cursor);
+            cursor = byName.get(cursor)?.parent;
+        }
+    }
+    return undefined;
+}
+/**
+ * Review a set of structure diagrams with declared parent relations. Per-diagram
+ * structural checks run first; the cross-diagram refinement checks follow.
+ */
+export function reviewGranularity(options) {
+    const diagrams = options.diagrams;
+    const findings = [];
+    const warnings = [];
+    const diagramSummaries = [];
+    const graphs = new Map();
+    if (diagrams.length === 0) {
+        findings.push({ code: 'UML031_NO_DIAGRAMS', severity: 'error', message: 'no diagram was supplied, so there are no granularity levels to compare.' });
+    }
+    const cycle = parentCycle(diagrams);
+    if (cycle !== undefined) {
+        findings.push({
+            code: 'UML030_PARENT_CYCLE',
+            severity: 'error',
+            message: 'the declared parent relation has a cycle: ' + cycle.join(' → ') + '. A refinement hierarchy must be a forest, or "which level owns this dependency" has no answer.',
+            evidence: { cycle },
+        });
+    }
+    const knownNames = new Set(diagrams.map((entry) => entry.name));
+    for (const entry of diagrams) {
+        if (entry.parent !== undefined && !knownNames.has(entry.parent)) {
+            findings.push({
+                code: 'UML028_UNKNOWN_PARENT',
+                severity: 'error',
+                message: 'diagram "' + entry.name + '" declares parent "' + entry.parent + '", which is not part of this set.',
+                file: entry.name,
+                evidence: { diagram: entry.name, parent: entry.parent, known: [...knownNames].sort() },
+            });
+        }
+        const report = reviewStructure({
+            diagram: entry.diagram,
+            notation: options.notation ?? 'auto',
+            ...(options.matrix === undefined ? {} : { matrix: options.matrix }),
+        });
+        graphs.set(entry.name, report.graph);
+        // Tag every finding with the diagram it came from: with several diagrams in one
+        // report, an untagged finding is unactionable.
+        for (const finding of report.findings) {
+            findings.push({ ...finding, file: entry.name, ...(finding.evidence === undefined ? {} : {}) });
+        }
+        warnings.push(...report.warnings.map((warning) => entry.name + ': ' + warning));
+        diagramSummaries.push({
+            name: entry.name,
+            ...(entry.parent === undefined ? {} : { parent: entry.parent }),
+            notation: report.notation,
+            nodes: report.summary.nodes,
+            edges: report.summary.edges,
+            verdict: report.verdict,
+            findings: report.findings.length,
+        });
+    }
+    const pairs = [];
+    for (const child of diagrams) {
+        if (child.parent === undefined)
+            continue;
+        const parent = diagrams.find((entry) => entry.name === child.parent);
+        const parentGraph = graphs.get(child.parent);
+        const childGraph = graphs.get(child.name);
+        if (parent === undefined || parentGraph === undefined || childGraph === undefined)
+            continue;
+        const parentNodes = new Set(parentGraph.nodes.map((node) => node.id));
+        const childNodes = new Set(childGraph.nodes.map((node) => node.id));
+        const parentEdges = new Set(parentGraph.edges.map((edge) => edge.from + '\u0000' + edge.to));
+        const childEdges = new Set(childGraph.edges.map((edge) => edge.from + '\u0000' + edge.to));
+        let inheritedEdges = 0;
+        let newEdges = 0;
+        const inventedEdges = [];
+        for (const edge of childGraph.edges) {
+            const hasFrom = parentNodes.has(edge.from);
+            const hasTo = parentNodes.has(edge.to);
+            if (!hasFrom || !hasTo) {
+                newEdges += 1;
+                continue;
+            }
+            if (parentEdges.has(edge.from + '\u0000' + edge.to)) {
+                inheritedEdges += 1;
+                continue;
+            }
+            inventedEdges.push({ from: edge.from, to: edge.to, line: edge.line });
+        }
+        const expandedEdges = [];
+        const missingEdges = [];
+        for (const edge of parentGraph.edges) {
+            const key = edge.from + '\u0000' + edge.to;
+            if (childEdges.has(key))
+                continue;
+            // The child only has to answer for a parent edge whose ends it also carries; a child
+            // may legitimately cover a subtree of the parent.
+            if (!childNodes.has(edge.from) || !childNodes.has(edge.to))
+                continue;
+            if (reaches(childGraph, edge.from, edge.to))
+                expandedEdges.push({ from: edge.from, to: edge.to, line: edge.line });
+            else
+                missingEdges.push({ from: edge.from, to: edge.to, line: edge.line });
+        }
+        if (inventedEdges.length > 0) {
+            findings.push({
+                code: 'UML029_REFINEMENT_VIOLATION',
+                severity: 'error',
+                message: 'diagram "' + child.name + '" draws ' + String(inventedEdges.length) + ' dependency(ies) between nodes its parent "' + parent.name + '" also has, but the parent does not: ' + inventedEdges.map((edge) => edge.from + ' → ' + edge.to).join(', ') + '. A refinement may add detail below the parent level, never a dependency at the parent level.',
+                file: child.name,
+                evidence: { kind: 'invented-edge', parent: parent.name, edges: inventedEdges },
+            });
+        }
+        if (missingEdges.length > 0) {
+            findings.push({
+                code: 'UML029_REFINEMENT_VIOLATION',
+                severity: 'error',
+                message: 'diagram "' + child.name + '" drops ' + String(missingEdges.length) + ' dependency(ies) its parent "' + parent.name + '" draws, without expanding them into a path: ' + missingEdges.map((edge) => edge.from + ' → ' + edge.to).join(', ') + '.',
+                file: child.name,
+                evidence: { kind: 'unexpanded-edge', parent: parent.name, edges: missingEdges },
+            });
+        }
+        pairs.push({
+            parent: parent.name,
+            child: child.name,
+            parentNodes: parentNodes.size,
+            childNodes: childNodes.size,
+            parentEdges: parentGraph.edges.length,
+            childEdges: childGraph.edges.length,
+            inheritedEdges,
+            newEdges,
+            expandedEdges,
+            missingEdges,
+            inventedEdges,
+        });
+    }
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
+    const invented = pairs.reduce((sum, pair) => sum + pair.inventedEdges.length, 0);
+    const missing = pairs.reduce((sum, pair) => sum + pair.missingEdges.length, 0);
+    const expanded = pairs.reduce((sum, pair) => sum + pair.expandedEdges.length, 0);
+    const nextSteps = [];
+    if (errors > 0)
+        nextSteps.push('Fix the refinement violations first: a level that invents or drops a parent-level dependency makes the hierarchy unusable as a rule source.');
+    if (pairs.length === 0 && diagrams.length > 0)
+        nextSteps.push('Give the levels a `parent` so the refinement can be checked; a set of unrelated diagrams has no consistency property to verify.');
+    if (expanded > 0)
+        nextSteps.push(String(expanded) + ' parent edge(s) are drawn as a path in the child — that is a legitimate expansion, and it is listed per pair so a reviewer can confirm each one.');
+    nextSteps.push('Reconcile the levels with the source-side scan: the diagram pair is consistent or not, and neither says anything about the code until it is scanned.');
+    return {
+        ok: true,
+        ran: true,
+        ...verdictOfFindings(findings),
+        schema: REPORT_SCHEMAS.granularity,
+        diagrams: diagramSummaries,
+        pairs,
+        findings,
+        summary: {
+            diagrams: diagrams.length,
+            roots: diagrams.filter((entry) => entry.parent === undefined).length,
+            pairs: pairs.length,
+            nodes: diagrams.reduce((sum, entry) => sum + (graphs.get(entry.name)?.nodes.length ?? 0), 0),
+            edges: diagrams.reduce((sum, entry) => sum + (graphs.get(entry.name)?.edges.length ?? 0), 0),
+            inventedEdges: invented,
+            missingEdges: missing,
+            expandedEdges: expanded,
+            errors,
+            warnings: warningCount,
+        },
+        hashes: { diagrams: diagrams.map((entry) => ({ name: entry.name, hash: createHash('sha256').update(entry.diagram).digest('hex') })) },
+        warnings,
+        nextSteps,
+    };
+}
+/** Deterministic JSON of a granularity report's pair table, for a stable summary line. */
+export function granularityDigest(pairs) {
+    return canonicalJson(pairs);
+}

package/lib/index.js

@@ -1,8 +1,9 @@
 /**
  * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
- * Injects the session-start gate text (claim-verification doctrine, 1% Rule,
- * Red Flags, proactive suggestion) into the first model step of every agent
- * session, mirroring the SessionStart hook the Claude Code plugin installs.
+ * Injects the session-start gate text (what this plugin checks, the 1% Rule,
+ * the Red Flags, the routing to the skills, the tool list, how to read a report)
+ * into the first model step of every agent session, mirroring the SessionStart
+ * hook the Claude Code plugin installs.
  * The skill ships in this package's `skills/` directory and is registered at
  * apply time into dsh's `ctx.skills` registry through the standard filesystem
  * provider, so it appears in every session catalog without a manual copy step.
@@ -16,11 +17,11 @@
  * reminders (skill catalog, AGENTS.md, gate plugins) simply defer this message
  * to the first step after their promotion, and the history guard re-injects it
  * there. The default gate text is the dsh-native adaptation of
- * `hooks/session-start-content.md`: behavior rules
- * (1% Rule / Red Flags / proactive suggestion) stay in sync, while
- * presentation is adapted to dsh's native skill catalog — the trigger list
- * lives in the skill description, not duplicated in the gate. Deployments
- * override via Config.
+ * `hooks/session-start-content.md`. Both are a guide to calling the tools: what
+ * this plugin checks, the 1% Rule and the Red Flags that raise the chance of a
+ * call, the routing to the five skills, the tool list, and how to read a report.
+ * They stay in sync. Method, doctrine and per-domain detail live in the skills
+ * and their references, not here. Deployments override via Config.
  *
  * @module logicprobe-dsh
  */
@@ -34,6 +35,8 @@ import { logicProbeConcurrencyScanTool } from './concurrency-tool.js';
 import { logicProbeComposeTool } from './compose-tool.js';
 import { logicProbeExportTool } from './export-tool.js';
 import { logicProbeUmlTool } from './uml-tool.js';
+import { logicProbeStructureTool } from './structure-tool.js';
+import { logicProbeReportDiffTool } from './report-diff-tool.js';
 import { ENGINE_SCHEMA_VERSION } from './engine.js';
 export const name = 'logicprobe';
 // Skills are contributed through the registry service, which dsh-base always
@@ -46,33 +49,42 @@ const SKILLS_DIR = fileURLToPath(new URL('../skills', import.meta.url));
 const GATE_PLUGIN_ID = 'logicprobe';
 /** Producer-owned message source kind declared in `MessageSourceMap` above. */
 const GATE_SOURCE_KIND = 'plugin:logicprobe';
-const DEFAULT_GATE_CONTENT = `<EXTREMELY_IMPORTANT>
-Plugin logicprobe is active. Documents are not truth — code is. Verify every verifiable claim before accepting or acting on any design.
-
-**1% Rule**: If there is even a 1% chance the logicprobe skill applies — reviewing design documents, architecture specs, technical proposals, or refactoring plans that make claims about API names, file locations, enum values, mechanism feasibility, state machines, protocol logic, data models, schema migrations, data invariants, behavioral guarantees ("always"/"never"/"guaranteed"), worst-case path cost or declared budgets, probabilistic reachability ("≥90% of runs reach SAFE"), deadlines ("must leave within 2 ticks"), cross-machine handshakes, or concurrency guarantees ("thread-safe"/"lock-free"/"ISR-safe") — load it with the skill tool before responding. The cost of loading is trivial compared to the cost of a false claim.
-
-**Red Flags** — if you think any of these, STOP. You are rationalizing:
-
-| You think | Reality |
-|-----------|---------|
-| "This plan is too simple to verify" | The skill auto-classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED). You don't decide. |
-| "I already know the file paths are correct" | Organic verification leaves no audit trail. Run Phase 0, append the "## Plan Verification" block. |
-| "I'll verify while implementing" | Verification happens before implementation, not during. |
-| "I can check this with reasoning alone" | Behavioral claims are verified with code/models, not intuition. One counter-example refutes a universal claim. |
-
-**Native verification path** (dsh) — six model-invocable tools:
-
-- \`logicprobe_verify\` — state machines: S1-S8 structural + A1-A14 adversarial, including A12 worst-case path cost against a declared \`budget\`, A13 probabilistic reachability over a DTMC, and A14 discrete-tick deadlines. Pass \`beforeModel\` + \`stateMapping\` to add the D1-D4 before/after regression.
-- \`logicprobe_datamodel_verify\` — data models and schema migrations: DS/DA checks, migration coverage, copy consistency, rollback symmetry, DD1-DD4 data regression.
-- \`logicprobe_compose_verify\` — two or more machines checked together (rendezvous handshake semantics): C1 composition deadlock, C2 rendezvous that never fires.
-- \`logicprobe_concurrency_scan\` — mine concurrency claims (thread-safe, lock-free, race condition, mutex, ISR-safe) and route them to dedicated verification; logicprobe does not prove concurrency safety.
-- \`logicprobe_export\` — emit external-checker input from a verified model: UPPAAL, TLA+, PRISM, SPIN.
-- \`logicprobe_uml\` — model a code flow as UML (render), read a diagram back into a model (parse), or audit the modelling (review: UML001-UML019 structural defects, documentation gaps, diagram-versus-model round-trip fidelity).
-
-Python harnesses in the skill references remain the fallback for non-dsh hosts.
-
-**Proactive suggestion**: When a user asks code-level behavioral questions — "could this state machine deadlock", "is this retry limit safe", "check this timing sequence for bugs", "is this migration non-breaking", "does this copy cover all required fields" — suggest logicprobe as an optional verification pass (do not auto-escalate).
-</EXTREMELY_IMPORTANT>`;
+const DEFAULT_GATE_CONTENT = `
+<EXTREMELY_IMPORTANT>
+Plugin logicprobe is active. It checks claims about designs and code: facts against the source, behaviour as an executable model.
+
+**1% Rule**: if any claim about this code deserves a check, load the matching skill first. Loading is cheap. A false claim is not.
+
+**Unsure whether a check applies?** Load \`logicprobe\` first. It is the entry point: it owns the doctrine, the model schema, the depth rules and the routing to its siblings.
+
+**Load the skill that matches the claim**: \`logicprobe\` (entry point; claim and behaviour checks), \`logicprobe-uml\` (diagrams), \`logicprobe-structure\` (architecture, dependencies), \`logicprobe-concurrency\` (concurrency claims), \`logicprobe-datamodel\` (data models, migrations).
+
+**Tools** (dsh):
+
+- \`logicprobe_verify\` — state machines: structural checks, adversarial probes, budgets, deadlines, before/after regression.
+- \`logicprobe_datamodel_verify\` — data models and migrations: structure, migration coverage, copy consistency, rollback, before/after data.
+- \`logicprobe_compose_verify\` — two or more machines: deadlock, and a rendezvous that never fires.
+- \`logicprobe_concurrency_scan\` — finds concurrency claims and routes them. It proves nothing about concurrency.
+- \`logicprobe_export\` — UPPAAL, TLA+, PRISM and SPIN input from a verified model.
+- \`logicprobe_uml\` — render, parse or review a UML diagram.
+- \`logicprobe_structure_verify\` — dependency review of a structure diagram, at one level or several.
+- \`logicprobe_report_diff\` — baseline against current: what a change added, removed or changed.
+
+**Read a report**: gate on \`verdict\` (\`pass\`, \`pass_with_findings\`, \`fail\`), never on \`ok\`. Reports carry \`verdictReason\`, \`hashes\` and \`nextSteps\`. Keys starting with \`_\` are notes: ignored, and left out of the model hash.
+
+**Red Flags** — if you think any of these, stop:
+
+| You think | Reality |
+|-----------|---------|
+| "Too simple to check" | The check is cheap. The silent skip is not. |
+| "I read the code, so I know" | Knowing is not evidence. Cite \`file:line\`, or run the model, or call the claim unverified. |
+| "The spec or the diagram says so" | Both are claims about the code. Reconcile them with a source-side scan. |
+| "I'll check while implementing" | Check before the decision, not after. |
+| "Reasoning is enough" | Reasoning is not a run. One counter-example kills a universal claim. |
+| "The report passed, so the code is fine" | The report covers the model you gave it. Reconcile it, and say what you did not check. |
+
+</EXTREMELY_IMPORTANT>
+`;
 /**
  * Declare a field as live where this host's schemastery can — `.volatile()`
  * arrived in 3.18.3 — and leave it an ordinary field where it cannot.
@@ -155,8 +167,8 @@ function resolveInteraction(config, session) {
 function modeContextText(config, session) {
     const interaction = resolveInteraction(config, session);
     const lines = [
-        'logicprobe: native tools — `logicprobe_verify` (state machines: S1-S8 + A1-A14, incl. A12 budget/worst-case path cost, A13 probabilistic reachability, A14 deadlines; `beforeModel` adds D1-D4 regression), `logicprobe_datamodel_verify` (data models and schema migrations: DS/DA, migration coverage, copy consistency, rollback symmetry, DD1-DD4), `logicprobe_compose_verify` (two or more machines: C1 composition deadlock, C2 rendezvous never fires), `logicprobe_concurrency_scan` (mine concurrency claims — it does not prove concurrency safety), `logicprobe_export` (UPPAAL, TLA+, PRISM, SPIN input from a verified model).',
-        'logicprobe: use `logicprobe_uml` to model a code flow as UML (render), to read a UML diagram back into a model (parse), or to audit the modelling (review: structural defects, documentation gaps, diagram-vs-model round-trip fidelity).',
+        'logicprobe: tools — `logicprobe_verify` (state machines), `logicprobe_datamodel_verify` (data models, migrations), `logicprobe_compose_verify` (two or more machines), `logicprobe_concurrency_scan` (finds concurrency claims, proves nothing), `logicprobe_export` (UPPAAL, TLA+, PRISM, SPIN), `logicprobe_uml` (render, parse, review UML), `logicprobe_structure_verify` (dependency diagrams, one or several levels), `logicprobe_report_diff` (baseline vs current).',
+        'logicprobe: gate on `verdict`, never on `ok`. Reports carry `verdictReason`, `hashes` and `nextSteps`.',
         interaction === 'auto'
             ? 'logicprobe interaction=auto: do NOT call ask_user_question for model confirmation; run round-trip validation of the extracted transition table and mark the result UNCONFIRMED.'
             : 'logicprobe interaction=ask: show the extracted transition table and get user confirmation before running verification.',
@@ -171,11 +183,11 @@ function modeContextText(config, session) {
  * lets the model read this plugin's runtime status without guessing. Mirrors
  * the registration pattern of the official dsh-tool-cordis host providers.
  */
-function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcurrencyToolRegistered, isComposeToolRegistered, isExportToolRegistered, isUmlToolRegistered) {
+function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcurrencyToolRegistered, isComposeToolRegistered, isExportToolRegistered, isUmlToolRegistered, isStructureToolRegistered, isReportDiffToolRegistered) {
     return {
         manifest: {
             id: 'logicprobe',
-            description: 'Session-start gate injection and native verification tooling for the Logic Probe toolbox — folds the claim-verification doctrine (1% Rule / Red Flags / proactive suggestion) into the first model step of every agent session and registers the logicprobe_verify tool.',
+            description: 'Session-start gate injection and native verification tooling for the Logic Probe toolbox. The gate is a guide to calling the tools: what the plugin checks, the 1% Rule and Red Flags, the routing to the five skills, the tool list, and how to read a report. Doctrine and per-domain detail live in the skills.',
             methods: [
                 {
                     name: 'status',
@@ -198,10 +210,12 @@ function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcu
                             composeToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_compose_verify tool is registered on ctx.tools.' },
                             exportToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_export tool is registered on ctx.tools.' },
                             umlToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_uml tool (UML modelling + modelling review) is registered on ctx.tools.' },
+                            structureToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_structure_verify tool (structure-diagram / dependency review) is registered on ctx.tools.' },
+                            reportDiffToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_report_diff tool (baseline report comparison) is registered on ctx.tools.' },
                             engineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled state-machine verification engine accepts.' },
                             dataEngineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled data-model verification engine accepts.' },
                         },
-                        required: ['enabled', 'gateContentLength', 'interaction', 'toolRegistered', 'dataToolRegistered', 'concurrencyToolRegistered', 'composeToolRegistered', 'exportToolRegistered', 'umlToolRegistered', 'engineSchemaVersion', 'dataEngineSchemaVersion'],
+                        required: ['enabled', 'gateContentLength', 'interaction', 'toolRegistered', 'dataToolRegistered', 'concurrencyToolRegistered', 'composeToolRegistered', 'exportToolRegistered', 'umlToolRegistered', 'structureToolRegistered', 'reportDiffToolRegistered', 'engineSchemaVersion', 'dataEngineSchemaVersion'],
                         additionalProperties: false,
                     },
                 },
@@ -219,6 +233,8 @@ function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcu
                     composeToolRegistered: isComposeToolRegistered(),
                     exportToolRegistered: isExportToolRegistered(),
                     umlToolRegistered: isUmlToolRegistered(),
+                    structureToolRegistered: isStructureToolRegistered(),
+                    reportDiffToolRegistered: isReportDiffToolRegistered(),
                     engineSchemaVersion: ENGINE_SCHEMA_VERSION,
                     dataEngineSchemaVersion: DATA_ENGINE_SCHEMA_VERSION,
                 };
@@ -238,6 +254,8 @@ export function apply(ctx, config) {
     let composeToolRegistered = false;
     let exportToolRegistered = false;
     let umlToolRegistered = false;
+    let structureToolRegistered = false;
+    let reportDiffToolRegistered = false;
     let modeContextRegistered = false;
     const registerProvider = () => {
         if (providerRegistered)
@@ -246,7 +264,7 @@ export function apply(ctx, config) {
         if (inspect === undefined)
             return;
         try {
-            ctx.effect(() => inspect.register(inspectProvider(config, () => toolRegistered, () => dataToolRegistered, () => concurrencyToolRegistered, () => composeToolRegistered, () => exportToolRegistered, () => umlToolRegistered)), 'logicprobe: inspect provider');
+            ctx.effect(() => inspect.register(inspectProvider(config, () => toolRegistered, () => dataToolRegistered, () => concurrencyToolRegistered, () => composeToolRegistered, () => exportToolRegistered, () => umlToolRegistered, () => structureToolRegistered, () => reportDiffToolRegistered)), 'logicprobe: inspect provider');
             providerRegistered = true;
         }
         catch (err) {
@@ -266,12 +284,16 @@ export function apply(ctx, config) {
             ctx.effect(() => tools.register(logicProbeComposeTool), 'logicprobe: compose tool');
             ctx.effect(() => tools.register(logicProbeExportTool), 'logicprobe: export tool');
             ctx.effect(() => tools.register(logicProbeUmlTool), 'logicprobe: uml tool');
+            ctx.effect(() => tools.register(logicProbeStructureTool), 'logicprobe: structure tool');
+            ctx.effect(() => tools.register(logicProbeReportDiffTool), 'logicprobe: report diff tool');
             toolRegistered = true;
             dataToolRegistered = true;
             concurrencyToolRegistered = true;
             composeToolRegistered = true;
             exportToolRegistered = true;
             umlToolRegistered = true;
+            structureToolRegistered = true;
+            reportDiffToolRegistered = true;
         }
         catch (err) {
             console.warn('[logicprobe] logicprobe_verify/logicprobe_datamodel_verify tool registration failed', err);

package/lib/report-diff-tool.js

@@ -0,0 +1,39 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { diffReports } from './baseline.js';
+export const LOGICPROBE_REPORT_DIFF_TOOL_NAME = 'logicprobe_report_diff';
+/**
+ * Model-visible DSH tool that compares two reports of the same family — the accepted
+ * "violations must not increase" acceptance criterion, computed instead of eyeballed.
+ * A finding's identity is its check + code + machine-readable locator, so a reworded
+ * message reads as `changed`, and two runs over the same input add nothing.
+ */
+export const logicProbeReportDiffTool = defineTool({
+    name: LOGICPROBE_REPORT_DIFF_TOOL_NAME,
+    description: 'Compare two logicprobe reports of the same family: `baseline` (earlier) against `current` (newer). Use it to accept a slice by "no new findings". Findings match on a stable identity: check id, code, and a locator built from `evidence` and `path`. Reworded prose counts as `changed`, not as new. Returns added, removed and changed findings, plus `summary`. The `verdict` is about the delta: a newly added error finding fails it. `currentVerdict` keeps the run\'s own verdict, so a clean delta over a failing report still shows as failing. Two runs over the same input add nothing.',
+    parameters: {
+        baseline: {
+            type: 'json',
+            required: true,
+            description: 'The earlier report (any family: verify, compose, datamodel, uml review, structure, concurrency).',
+        },
+        current: {
+            type: 'json',
+            required: true,
+            description: 'The current report to compare against the baseline.',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'Baseline diff report: added/removed/changed findings, delta verdict, current verdict, summary and next steps.',
+        },
+        render(_args, value) {
+            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        return diffReports(args.baseline, args.current);
+    },
+});

package/lib/structure-tool.js

@@ -0,0 +1,64 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { REPORT_SCHEMAS } from './engine.js';
+import { reviewStructure } from './structure.js';
+import { reviewGranularity } from './granularity.js';
+export const LOGICPROBE_STRUCTURE_TOOL_NAME = 'logicprobe_structure_verify';
+/**
+ * Model-visible DSH tool that audits a *structure* diagram — components, packages,
+ * classes, deployment nodes and the dependency arrows between them — against an
+ * optional dependency matrix. A structure diagram is not a state machine: this tool
+ * reads the graph the diagram actually draws, instead of refusing it (which is what
+ * `logicprobe_uml action=parse` does) or pretending the arrows are state transitions
+ * (which is what a false `ok` used to hide).
+ */
+export const logicProbeStructureTool = defineTool({
+    name: LOGICPROBE_STRUCTURE_TOOL_NAME,
+    description: 'Audit a structure diagram as a dependency graph. Takes PlantUML component, package, class or deployment text, or a Mermaid class diagram. Reports UML020 isolated node, UML021 dangling reference, UML022 cycle (shortest path), UML023 disallowed edge and UML024 layer violation against a matrix, UML025 missing required edge, and UML026 when no node is declared. The matrix is {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Ids and members accept globs (`*`, `?`). Deny beats allow, and layers run top-first, so downward edges pass and upward ones are UML024. With a matrix, every edge appears in `edgeVerdicts` with the rules it matched. Pass `diagrams` instead of `diagram` to check several levels at once: each child must refine its parent. This audits the diagram, not the code: reconcile it with a source-side scan. Read `verdict`, not `ok`. For state or activity diagrams use `logicprobe_uml` and `logicprobe_verify`.',
+    parameters: {
+        diagram: {
+            type: 'string',
+            description: 'Structure-diagram source text: PlantUML component/package/class/deployment, or a Mermaid class diagram. Omit when `diagrams` is given.',
+        },
+        diagrams: {
+            type: 'json',
+            description: 'Multi-granularity mode: an array of {name, diagram, parent?} levels. Each diagram is checked on its own AND against its declared parent (UML028 unknown parent, UML029 refinement violation, UML030 parent cycle), with per-pair node/edge counts.',
+        },
+        notation: {
+            type: 'string',
+            enum: ['auto', 'plantuml', 'mermaid'],
+            description: 'Diagram language. Default auto (detected from the text).',
+        },
+        matrix: {
+            type: 'json',
+            description: 'Optional dependency matrix: {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Every edge is judged against it and the matched rule ids are reported.',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'Structure review report: graph (nodes/edges), findings UML020-UML026, per-edge matrix verdicts, summary and next steps.',
+        },
+        render(_args, value) {
+            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        },
+    },
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        if (args.diagrams !== undefined) {
+            return reviewGranularity({
+                diagrams: args.diagrams,
+                notation: (args.notation ?? 'auto'),
+                ...(args.matrix === undefined ? {} : { matrix: args.matrix }),
+            });
+        }
+        if (args.diagram === undefined) {
+            return { ok: false, ran: false, verdict: 'fail', verdictReason: 'the tool did not run: pass `diagram` (one structure diagram) or `diagrams` (several levels with parents)', schema: REPORT_SCHEMAS.structure, errorCode: 'UML_INPUT', error: 'structure review needs `diagram` or `diagrams`' };
+        }
+        return reviewStructure({
+            diagram: args.diagram,
+            notation: (args.notation ?? 'auto'),
+            ...(args.matrix === undefined ? {} : { matrix: args.matrix }),
+        });
+    },
+});