dsh-logicprobe 0.9.0 → 1.0.0

package/src/export-tool.ts

@@ -1,48 +1,73 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from './json-value.js'
-import { exportModel, type ExportFormat } from './exporters.js'
-
-export const LOGICPROBE_EXPORT_TOOL_NAME = 'logicprobe_export'
-
-/**
- * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
- * native input for the tool logicprobe routes to (UPPAAL / TLA+ / PRISM / SPIN).
- * v1 translates the core machine; unrepresentable invariants become warnings.
- */
-export const logicProbeExportTool = defineTool({
-  name: LOGICPROBE_EXPORT_TOOL_NAME,
-  description:
-    'Export a LogicModelV1 state machine into native input for an external verification tool (logicprobe routing). format is one of uppaal (.xta + queries), tla (TLC spec + safety property), prism (.pm + .pctl), spin (Promela + ltl). Booleans are exported as 0/1 integers; invariants the target cannot express are returned as warnings, never silently dropped. Returns { ok, format, primary, extras?, warnings? } or { ok: false, error } when the model is invalid or the PRISM enumeration is too large.',
-  parameters: {
-    model: {
-      type: 'json',
-      required: true,
-      description: 'LogicModelV1 state-machine model to export.',
-    },
-    format: {
-      type: 'string',
-      required: true,
-      enum: ['uppaal', 'tla', 'prism', 'spin'],
-      description: 'Target tool format.',
-    },
-  },
-  output: {
-    schema: {
-      type: 'json',
-      description: 'Export result with generated file content.',
-    },
-    render(_args, value) {
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
-    },
-  },
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    try {
-      const result = exportModel(args.model, args.format as ExportFormat)
-      return { ok: true, format: result.format, primary: result.primary, ...(result.extras === undefined ? {} : { extras: result.extras }), warnings: result.warnings } as unknown as JsonValue
-    } catch (error) {
-      return { ok: false, error: error instanceof Error ? error.message : String(error) } as unknown as JsonValue
-    }
-  },
-})
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js'
+import { exportModel, type ExportFormat } from './exporters.js'
+
+/** The model hash of an export's input, when the input validates (the success path always does). */
+function exportHashes(model: unknown): { hashSpec: typeof DEFAULT_HASH_SPEC; modelHash?: string } {
+  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
+ * native input for the tool logicprobe routes to (UPPAAL / TLA+ / PRISM / SPIN).
+ * v1 translates the core machine; unrepresentable invariants become warnings.
+ */
+export const logicProbeExportTool = defineTool({
+  name: LOGICPROBE_EXPORT_TOOL_NAME,
+  description:
+    'Export a LogicModelV1 state machine into native input for an external verification tool (logicprobe routing). format is one of uppaal (.xta + queries), tla (TLC spec + safety property), prism (.pm + .pctl), spin (Promela + ltl). Booleans are exported as 0/1 integers; invariants the target cannot express are returned as warnings, never silently dropped. Returns { ok, format, primary, extras?, warnings? } or { ok: false, error } when the model is invalid or the PRISM enumeration is too large.',
+  parameters: {
+    model: {
+      type: 'json',
+      required: true,
+      description: 'LogicModelV1 state-machine model to export.',
+    },
+    format: {
+      type: 'string',
+      required: true,
+      enum: ['uppaal', 'tla', 'prism', 'spin'],
+      description: 'Target tool format.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Export result with generated file content.',
+    },
+    render(_args, value) {
+      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      const result = exportModel(args.model, args.format as ExportFormat)
+      const warnings = result.warnings ?? []
+      const nextSteps: string[] = []
+      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,
+      } as unknown as JsonValue
+    } catch (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 } as unknown as JsonValue
+    }
+  },
+})

package/src/granularity.ts

@@ -0,0 +1,312 @@
+/**
+ * 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, type Finding, type ReportSchema, type Verdict, type VerdictSummary } from './engine.js'
+import { parseStructure, reviewStructure, type StructureGraph, type StructureNotation } from './structure.js'
+
+export interface GranularityDiagram {
+  /** Name of this level, e.g. `L2/motion` or `repo`. Referenced by a child's `parent`. */
+  name: string
+  /** Diagram source text. */
+  diagram: string
+  /** Name of the diagram this one refines; absent for a root. */
+  parent?: string
+}
+
+export interface GranularityOptions {
+  diagrams: GranularityDiagram[]
+  notation?: 'auto' | StructureNotation
+  /** Optional dependency matrix, applied to every diagram. */
+  matrix?: unknown
+}
+
+export interface GranularityEdgeRef {
+  from: string
+  to: string
+  line?: number
+}
+
+export interface GranularityPairSummary {
+  parent: string
+  child: string
+  parentNodes: number
+  childNodes: number
+  parentEdges: number
+  childEdges: number
+  /** Child edges whose endpoints both exist in the parent and which the parent also draws. */
+  inheritedEdges: number
+  /** Child edges with at least one endpoint the parent does not have (the refinement's own detail). */
+  newEdges: number
+  /** Parent edges with no direct child counterpart, but a child path connects the same ends. */
+  expandedEdges: GranularityEdgeRef[]
+  /** Parent edges with no direct counterpart and no connecting path — the refinement lost them. */
+  missingEdges: GranularityEdgeRef[]
+  /** Child edges between two parent nodes that the parent does not draw — invented dependencies. */
+  inventedEdges: GranularityEdgeRef[]
+}
+
+export interface GranularityDiagramSummary {
+  name: string
+  parent?: string
+  notation: StructureNotation
+  nodes: number
+  edges: number
+  verdict: Verdict
+  findings: number
+}
+
+export interface GranularityReport {
+  ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  schema: ReportSchema
+  diagrams: GranularityDiagramSummary[]
+  pairs: GranularityPairSummary[]
+  findings: Finding[]
+  summary: {
+    diagrams: number
+    roots: number
+    pairs: number
+    nodes: number
+    edges: number
+    inventedEdges: number
+    missingEdges: number
+    expandedEdges: number
+    errors: number
+    warnings: number
+  }
+  hashes: { diagrams: Array<{ name: string; hash: string }> }
+  warnings: string[]
+  nextSteps: string[]
+}
+
+/** Reachability in one diagram, ignoring edge direction? No: a dependency path is directed. */
+function reaches(graph: StructureGraph, from: string, to: string): boolean {
+  const adjacency = new Map<string, string[]>()
+  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<string>([from])
+  const queue: string[] = [from]
+  while (queue.length > 0) {
+    const current = queue.shift() as string
+    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: GranularityDiagram[]): string[] | undefined {
+  const byName = new Map(diagrams.map((entry) => [entry.name, entry]))
+  for (const start of diagrams) {
+    const path: string[] = [start.name]
+    const seen = new Set<string>([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: GranularityOptions): GranularityReport {
+  const diagrams = options.diagrams
+  const findings: Finding[] = []
+  const warnings: string[] = []
+  const diagramSummaries: GranularityDiagramSummary[] = []
+  const graphs = new Map<string, StructureGraph>()
+
+  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: GranularityPairSummary[] = []
+  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: GranularityEdgeRef[] = []
+    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: GranularityEdgeRef[] = []
+    const missingEdges: GranularityEdgeRef[] = []
+    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: string[] = []
+  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: GranularityPairSummary[]): string {
+  return canonicalJson(pairs)
+}
+
+export type { VerdictSummary }

package/src/index.ts

@@ -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
  */
@@ -40,6 +41,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'
 
 // DSH 0.1.7-alpha.1 (session format v4) retires the shared
@@ -72,33 +75,42 @@ const GATE_SOURCE_KIND: 'plugin:logicprobe' = 'plugin:logicprobe'
 
 export type InteractionMode = 'ask' | 'auto' | 'follow-approval'
 
-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>
+`
 
 /** A schemastery field that may or may not carry `.volatile()`. */
 interface LiveField {
@@ -220,8 +232,8 @@ function resolveInteraction(config: Config, session: Session): 'ask' | 'auto' {
 function modeContextText(config: Config, session: Session): string {
   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.',
@@ -245,11 +257,11 @@ interface SystemPromptLike {
  * 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: Config, isToolRegistered: () => boolean, isDataToolRegistered: () => boolean, isConcurrencyToolRegistered: () => boolean, isComposeToolRegistered: () => boolean, isExportToolRegistered: () => boolean, isUmlToolRegistered: () => boolean): HostCordisInspectProviderRegistration {
+function inspectProvider(config: Config, isToolRegistered: () => boolean, isDataToolRegistered: () => boolean, isConcurrencyToolRegistered: () => boolean, isComposeToolRegistered: () => boolean, isExportToolRegistered: () => boolean, isUmlToolRegistered: () => boolean, isStructureToolRegistered: () => boolean, isReportDiffToolRegistered: () => boolean): HostCordisInspectProviderRegistration {
   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',
@@ -272,10 +284,12 @@ function inspectProvider(config: Config, isToolRegistered: () => boolean, isData
               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,
           },
         },
@@ -293,6 +307,8 @@ function inspectProvider(config: Config, isToolRegistered: () => boolean, isData
           composeToolRegistered: isComposeToolRegistered(),
           exportToolRegistered: isExportToolRegistered(),
           umlToolRegistered: isUmlToolRegistered(),
+          structureToolRegistered: isStructureToolRegistered(),
+          reportDiffToolRegistered: isReportDiffToolRegistered(),
           engineSchemaVersion: ENGINE_SCHEMA_VERSION,
           dataEngineSchemaVersion: DATA_ENGINE_SCHEMA_VERSION,
         }
@@ -313,13 +329,15 @@ export function apply(ctx: Context, config: Config): void {
   let composeToolRegistered = false
   let exportToolRegistered = false
   let umlToolRegistered = false
+  let structureToolRegistered = false
+  let reportDiffToolRegistered = false
   let modeContextRegistered = false
   const registerProvider = (): void => {
     if (providerRegistered) return
     const inspect = ctx.get('cordisInspect')
     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) {
       console.warn('[logicprobe] inspect provider registration failed', err)
@@ -336,12 +354,16 @@ export function apply(ctx: Context, config: Config): void {
       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)
     }