dsh-logicprobe 1.0.0 → 1.2.0

package/lib/engine.js

@@ -53,6 +53,19 @@ function verificationNextSteps(checks, coverage) {
     steps.push('Re-run with beforeModel/stateMapping after the change to prove the behaviour did not regress (D1-D4).');
     return steps;
 }
+/**
+ * Repair guidance for a rejected model. A refusal reports the offending path and the rule
+ * it broke, but not what to write instead; for fields whose absence is a documented trap,
+ * that is the difference between "fix it" and "guess again". Derived only from the
+ * validation messages, so the list stays deterministic.
+ */
+function refusalGuidance(errors) {
+    const steps = [];
+    if (errors.some((message) => message.includes('.description'))) {
+        steps.push('Add the required "description" string to every invariant (for example "description": "what this invariant guarantees"); a `_`-prefixed key is not a substitute, and the value takes part in `modelHash`.');
+    }
+    return steps;
+}
 const DEFAULT_MAX_STATES = 10_000;
 const DEFAULT_MAX_PERMUTATION_EVENTS = 5;
 function stableStringify(value) {
@@ -90,6 +103,7 @@ export const REPORT_SCHEMAS = {
     umlRender: 'logicprobe/uml/render/v1',
     umlParse: 'logicprobe/uml/parse/v1',
     umlReview: 'logicprobe/uml/review/v1',
+    umlExplainLabels: 'logicprobe/uml/explain-labels/v1',
     structure: 'logicprobe/structure/v1',
     granularity: 'logicprobe/granularity/v1',
     baseline: 'logicprobe/baseline/v1',
@@ -889,7 +903,9 @@ function checkResult(id, name, findings, detail) {
     return {
         id,
         name,
-        status: findings.length === 0 ? 'pass' : 'fail',
+        // An info finding is a note, not a defect: it must not flip a check to `fail`, or the
+        // check would be dragged into the "resolve the failing checks" list for a remark.
+        status: errors + warnings === 0 ? 'pass' : 'fail',
         detail: detail + (errors > 0 ? ' (' + errors + ' errors' + (warnings > 0 ? ', ' + warnings + ' warnings' : '') + ')' : warnings > 0 ? ' (' + warnings + ' warnings)' : ''),
         findings,
     };
@@ -2716,7 +2732,7 @@ export function runVerification(input, options = {}) {
             ...metadata,
             summary: { states: 0, transitions: 0, errors: validation.errors.length, warnings: 0, checksRun: 0 },
             checks: [modelCheck],
-            nextSteps: verificationNextSteps([modelCheck], undefined),
+            nextSteps: [...refusalGuidance(validation.errors), ...verificationNextSteps([modelCheck], undefined)],
         };
     }
     const model = validation.model;
@@ -2791,6 +2807,16 @@ export function runVerification(input, options = {}) {
     const warnings = checks.reduce((sum, check) => sum + check.findings.filter((finding) => finding.severity === 'warning').length, 0);
     const coverageNotes = computeCoverageNotes(model);
     const narrativeCoverage = narrativeCoverageOf(model);
+    // R3: a partial narrative is valid, but the gap must be machine-readable instead of only a
+    // sentence in `nextSteps`. It rides on S5 — the check that already reports undocumented
+    // (state, event) combinations — so the documented check count stays 22.
+    if (narrativeCoverage !== undefined && !narrativeComplete(narrativeCoverage)) {
+        checks.find((check) => check.id === 'S5')?.findings.push({
+            code: 'NARRATIVE_PARTIAL',
+            severity: 'info',
+            message: 'Narrative coverage is partial (states ' + narrativeCoverage.states + ', events ' + narrativeCoverage.events + ', scenarios ' + narrativeCoverage.scenarios + '): the checks still run over the whole model, but the undocumented symbols have to be re-derived by the reader.',
+        });
+    }
     return {
         ok: true,
         ran: true,
@@ -3004,11 +3030,21 @@ export function runCompositionVerification(machinesInput, options = {}) {
                 .map((machine) => 'machine ' + String(machine.index) + ' at ' + machine.state + ': ' + (machine.blocked.length === 0
                 ? 'empty event alphabet'
                 : machine.blocked.map((entry) => entry.event + ' (' + entry.reason + ')').join(', ')));
+            // A non-terminal state with no outgoing transition anywhere in its own model is a
+            // modelling gap, not a design defect: without this note the census reads as
+            // "the architecture deadlocks" when the model was simply left unfinished.
+            const gaps = node.runtimes
+                .map((runtime, index) => ({ index, state: runtime.state }))
+                .filter((entry) => !isTerminal(models[entry.index], entry.state)
+                && !models[entry.index].transitions.some((transition) => transition.from === entry.state));
+            const gapNote = gaps.length === 0
+                ? ''
+                : ' Modelling note: ' + gaps.map((gap) => 'machine ' + String(gap.index) + ' state ' + gap.state).join(', ') + ' has no outgoing transition in its own model, so this deadlock may be a modelling gap rather than a design defect.';
             c1Findings.push({
                 code: 'C1_COMPOSITION_DEADLOCK',
                 severity: 'error',
                 message: 'Composition deadlock: no machine can advance from (' + node.runtimes.map((runtime) => runtime.state).join(', ') + ') while at least one is not terminal.',
-                detail: 'Shortest counterexample (breadth-first): ' + String(node.path.length) + ' step(s) to reach it. ' + reasons.join(' | '),
+                detail: 'Shortest counterexample (breadth-first): ' + String(node.path.length) + ' step(s) to reach it. ' + reasons.join(' | ') + gapNote,
                 evidence: { steps: node.path, states: node.runtimes.map((runtime) => runtime.state), depth: node.path.length, perMachine, reasons },
             });
             continue;
@@ -3057,7 +3093,7 @@ export function runCompositionVerification(machinesInput, options = {}) {
             const caveat = truncated ? ' The search was truncated at ' + String(maxStates) + ' composite states, so this may be an artefact of the cap rather than a property of the model.' : '';
             c2Findings.push({
                 code: 'C2_RENDEZVOUS_NEVER_FIRES',
-                severity: 'warning',
+                severity: 'error',
                 message: 'Rendezvous event ' + event + ' can never fire: ' + reason + '.' + caveat,
                 detail: machines.map((machine) => 'machine ' + String(machine.index) + (machine.declares ? ' declares' : ' does not declare')
                     + (machine.everEnabled ? ', enabled at ' + (machine.enabledAt.length === 0 ? 'no visited state' : machine.enabledAt.join('/')) : ', never enabled')).join(' | '),
@@ -3065,15 +3101,18 @@ export function runCompositionVerification(machinesInput, options = {}) {
             });
         }
     }
-    const errors = c1Findings.length;
-    const warnings = c2Findings.length;
+    // C2 is an error, not a warning: a rendezvous that can never fire means the composition
+    // cannot advance through that handshake — the same "stuck forever" outcome C1 reports,
+    // so a gate that only reads `verdict` must be able to stop on it.
+    const errors = c1Findings.length + c2Findings.length;
+    const warnings = 0;
     const c1Detail = c1Findings.length > 0
         ? 'Composition deadlocks: ' + String(c1Findings.length)
         : truncated
             ? 'No composition deadlock found, but the search was truncated at ' + String(maxStates) + ' composite states: absence is not proven'
             : 'No composition deadlock reachable';
     const c2Detail = c2Findings.length > 0
-        ? 'Rendezvous warnings: ' + String(c2Findings.length)
+        ? 'Rendezvous errors: ' + String(c2Findings.length)
         : truncated
             ? 'All rendezvous events fired, but the search was truncated at ' + String(maxStates) + ' composite states'
             : 'All rendezvous events can fire';
@@ -3082,10 +3121,21 @@ export function runCompositionVerification(machinesInput, options = {}) {
         checkResult('C2', 'Rendezvous Sync', c2Findings, c2Detail),
     ];
     const nextSteps = [];
-    if (errors > 0)
-        nextSteps.push('Resolve the error findings first: the composition deadlocks at a reachable state, so at least one machine is missing an exit or a handshake partner.');
-    if (warnings > 0)
-        nextSteps.push('Review the warning findings: a rendezvous event that can never fire means the handshake is declared but unreachable.');
+    if (errors > 0) {
+        const why = c1Findings.length > 0
+            ? 'the composition deadlocks at a reachable state, so at least one machine is missing an exit or a handshake partner'
+            : 'a rendezvous event can never fire, so the composition cannot advance through that handshake';
+        nextSteps.push('Resolve the error findings first: ' + why + '.');
+    }
+    // Composition couples machines only through rendezvous: each machine's `variables` are
+    // private to it, so two machines cannot share one predicate. Name them when the input
+    // looks like it is trying to (two or more machines each declare variables).
+    const owners = models
+        .map((entry, index) => ({ index, names: (entry.variables ?? []).map((variable) => variable.name) }))
+        .filter((entry) => entry.names.length > 0);
+    if (owners.length >= 2) {
+        nextSteps.push('Each machine\'s variables are private to it (' + owners.map((entry) => 'machine ' + String(entry.index) + ': ' + entry.names.join(', ')).join('; ') + '): composition couples machines only through rendezvous, so a value two machines must agree on has to be modelled as a handshake, or inside a single machine.');
+    }
     nextSteps.push('Re-run the composition after the change; every machine must be able to advance, or explain why it is terminal.');
     return {
         ok: errors === 0,

package/lib/export-tool.js

@@ -1,6 +1,7 @@
 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';
+import { renderReportText } from './report-view.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);
@@ -29,14 +30,19 @@ export const logicProbeExportTool = defineTool({
             enum: ['uppaal', 'tla', 'prism', 'spin'],
             description: 'Target tool format.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the generated file verbatim; full prints the structured result as JSON.',
+        },
     },
     output: {
         schema: {
             type: 'json',
             description: 'Export result with generated file content.',
         },
-        render(_args, value) {
-            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,

package/lib/index.js

@@ -1,7 +1,7 @@
 /**
  * logicprobe — DeepSeek Harness native plugin for the Logic Probe toolbox.
- * 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)
+ * Injects the session-start gate text (what this plugin checks, 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
@@ -18,8 +18,9 @@
  * 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`. 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.
+ * this plugin checks, the routing to the sibling skills, the tool list, and how to
+ * read a report. The Red Flags table is enforcement scaffolding and lives in the
+ * skill body instead, where a session that needs it can load it.
  * They stay in sync. Method, doctrine and per-domain detail live in the skills
  * and their references, not here. Deployments override via Config.
  *
@@ -49,41 +50,28 @@ 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. 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>
+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.
+
+**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. A tool prints the report body: passing checks stay in the inventory line, repeated facts are grouped, and warning evidence is omitted — pass \`reportView: "full"\` only when you need the structured report itself, which \`logicprobe_report_diff\` consumes.
+
+</EXTREMELY_IMPORTANT>
 `;
 /**
  * Declare a field as live where this host's schemastery can — `.volatile()`
@@ -187,7 +175,7 @@ function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcu
     return {
         manifest: {
             id: 'logicprobe',
-            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.',
+            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 routing to the sibling skills, the tool list, and how to read a report. Doctrine and per-domain detail live in the skills.',
             methods: [
                 {
                     name: 'status',

package/lib/report-diff-tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { diffReports } from './baseline.js';
+import { renderReportText } from './report-view.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
@@ -21,14 +22,19 @@ export const logicProbeReportDiffTool = defineTool({
             required: true,
             description: 'The current report to compare against the baseline.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured diff report.',
+        },
     },
     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) }];
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,

package/lib/report-view.js

@@ -0,0 +1,295 @@
+const DEFAULTS = { maxFindingsPerCheck: 24, maxEvidenceChars: 160, includePassing: false, full: false };
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+const array = (value) => (Array.isArray(value) ? value : []);
+const text = (value) => (typeof value === 'string' ? value : undefined);
+const count = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+/** Normalize one raw finding. Unknown fields are ignored; a missing message renders as the code. */
+export function toViewFinding(value, check) {
+    const raw = record(value) ?? {};
+    const code = text(raw.code) ?? 'FINDING';
+    const file = text(raw.file);
+    const line = count(raw.line);
+    return {
+        code,
+        severity: text(raw.severity) ?? 'warning',
+        message: text(raw.message) ?? code,
+        ...(record(raw.evidence) === undefined ? {} : { evidence: record(raw.evidence) }),
+        ...(file === undefined ? {} : { file }),
+        ...(line === undefined ? {} : { line }),
+        ...(check === undefined ? {} : { check }),
+    };
+}
+/**
+ * The fact a finding states, as a comparable key. The verify/datamodel families report the
+ * same (state, event) fact from more than one check, so the key ignores which check said it;
+ * anything else falls back to code + message.
+ */
+export function factKey(finding) {
+    const stateEvent = /^(\S+) silently ignores event (\S+)/.exec(finding.message);
+    if (stateEvent !== null)
+        return `event-in-state|${stateEvent[1] ?? ''}|${stateEvent[2] ?? ''}`;
+    const eventState = /^Event (\S+) in state (\S+) /.exec(finding.message);
+    if (eventState !== null)
+        return `event-in-state|${eventState[2] ?? ''}|${eventState[1] ?? ''}`;
+    return `message|${finding.code}|${finding.message}`;
+}
+/** `[severity/CODE] message` plus, for errors, a compact evidence tail. */
+function findingLine(finding, options) {
+    const where = finding.file === undefined ? '' : ` (${finding.file}${finding.line === undefined ? '' : ':' + String(finding.line)})`;
+    const evidence = finding.evidence === undefined || finding.severity !== 'error'
+        ? ''
+        : ' evidence=' + truncate(JSON.stringify(finding.evidence), options.maxEvidenceChars);
+    return `  [${finding.severity}/${finding.code}] ${finding.message}${where}${evidence}`;
+}
+function truncate(value, limit) {
+    return value.length <= limit ? value : value.slice(0, limit - 1) + '…';
+}
+/** Collapse identical lines into `line (xN)`, keeping first-seen order. */
+function collapse(lines) {
+    const order = [];
+    const seen = new Map();
+    for (const line of lines) {
+        if (!seen.has(line))
+            order.push(line);
+        seen.set(line, (seen.get(line) ?? 0) + 1);
+    }
+    return order.map((line) => (seen.get(line) === 1 ? line : `${line} (x${String(seen.get(line))})`));
+}
+/**
+ * Body lines for one group of findings. Findings that restate a fact an earlier check already
+ * reported are dropped (only their count survives), because re-reading them is pure cost;
+ * `error` findings are never dropped.
+ */
+function findingLines(findings, options, seenFacts) {
+    const lines = [];
+    let repeats = 0;
+    const fresh = [];
+    const addedHere = new Set();
+    for (const finding of findings) {
+        const key = factKey(finding);
+        // A fact another check already reported is dropped here (only its count survives), but a
+        // fact repeated inside this same group is not a cross-check repeat: it collapses below
+        // into one line with a multiplier, which keeps the count visible where it belongs.
+        if (finding.severity !== 'error' && seenFacts.has(key) && !addedHere.has(key)) {
+            repeats += 1;
+            continue;
+        }
+        addedHere.add(key);
+        seenFacts.add(key);
+        fresh.push(finding);
+    }
+    const stateGroups = new Map();
+    const singles = [];
+    for (const finding of fresh) {
+        const match = /^(\S+) silently ignores event (\S+)/.exec(finding.message) ?? /^Event (\S+) in state (\S+) /.exec(finding.message);
+        if (match === null) {
+            singles.push(finding);
+            continue;
+        }
+        // `event in state` puts the state second; `state ignores event` puts it first.
+        const state = / silently ignores event /.test(finding.message) ? match[1] ?? '' : match[2] ?? '';
+        const event = / silently ignores event /.test(finding.message) ? match[2] ?? '' : match[1] ?? '';
+        const group = stateGroups.get(state) ?? { severity: finding.severity, code: finding.code, events: [] };
+        group.events.push(event);
+        stateGroups.set(state, group);
+    }
+    for (const [state, group] of stateGroups) {
+        lines.push(`  ${state} (${String(group.events.length)}) [${group.severity}/${group.code}]: ${group.events.join(', ')}`);
+    }
+    const rendered = collapse(singles.map((finding) => findingLine(finding, options)));
+    const budget = options.maxFindingsPerCheck;
+    const kept = [];
+    let dropped = 0;
+    for (const line of [...lines, ...rendered]) {
+        if (kept.length < budget || line.includes('/error]'))
+            kept.push(line);
+        else
+            dropped += 1;
+    }
+    if (dropped > 0)
+        kept.push(`  +${String(dropped)} more warning line(s) — ask for this check by id to see them all`);
+    if (repeats > 0)
+        kept.push(`  (${String(repeats)} finding(s) here repeat facts already reported above)`);
+    return kept;
+}
+/** `ok`/`verdict` header fields, shared by every report family. */
+function headerLines(report, options) {
+    const schema = text(report.schema) ?? 'logicprobe/report';
+    const verdict = text(report.verdict);
+    const ok = report.ok;
+    const summary = record(report.summary) ?? {};
+    const lines = [];
+    const bits = [
+        `${schema}`,
+        verdict === undefined ? `ok=${String(ok)}` : `verdict=${verdict}`,
+        text(report.verdictReason) ?? '',
+        ok === undefined || verdict === undefined ? '' : `ok=${String(ok)}`,
+    ].filter((bit) => bit !== '');
+    lines.push(bits.join('  '));
+    const hash = text(report.modelHash) ?? text(record(report.hashes)?.modelHash);
+    const counts = ['states', 'transitions', 'errors', 'warnings', 'checksRun']
+        .map((key) => (count(summary[key]) === undefined ? '' : `${key}=${String(count(summary[key]))}`))
+        .filter((bit) => bit !== '');
+    if (counts.length > 0 || hash !== undefined)
+        lines[0] += '  ' + [...(hash === undefined ? [] : [`modelHash=${hash.slice(0, 12)}…`]), ...counts].join(' ');
+    if (report.ran === false)
+        lines.push('note: the tool did not run (the engine refused the input) — the fields below describe the refusal.');
+    const coverage = record(report.narrativeCoverage);
+    if (coverage !== undefined) {
+        const parts = Object.entries(coverage)
+            .filter(([, value]) => count(value) !== undefined)
+            .map(([key, value]) => `${key} ${String(count(value))}`);
+        if (parts.length > 0)
+            lines.push(`NARRATIVE  ${parts.join(' / ')} documented`);
+    }
+    void options;
+    return lines;
+}
+/** Trailing lines: notes about what was not checked, then the next steps. */
+function footerLines(report) {
+    const lines = [];
+    const notes = array(report.coverageNotes).map(String).filter((note) => note !== '');
+    if (notes.length > 0)
+        lines.push(`COVERAGE  ${notes.join(' ')}`);
+    const steps = array(report.nextSteps).map(String).filter((step) => step !== '');
+    for (const step of steps)
+        lines.push(`NEXT  ${step}`);
+    const comparison = record(report.comparison);
+    if (comparison !== undefined) {
+        const parts = Object.entries(comparison)
+            .filter(([, value]) => count(value) !== undefined || typeof value === 'string')
+            .map(([key, value]) => `${key}=${String(value)}`);
+        if (parts.length > 0)
+            lines.push(`COMPARISON  ${parts.join(' ')}`);
+    }
+    return lines;
+}
+/** A `checks[]` report (verify, compose, datamodel): silence pass, expand the rest. */
+function renderChecksReport(report, options) {
+    const checks = array(report.checks).map((value) => record(value) ?? {});
+    const byStatus = (status) => checks.filter((check) => text(check.status) === status).map((check) => text(check.id) ?? '?');
+    const inventory = [
+        ['pass', byStatus('pass')],
+        ['fail', byStatus('fail')],
+        ['skip', byStatus('skip')],
+    ]
+        .filter(([, ids]) => ids.length > 0)
+        .map(([status, ids]) => `${String(status)} ${ids.join(' ')}`)
+        .join(' | ');
+    const lines = [...headerLines(report, options), `CHECKS  ${inventory}`];
+    const seenFacts = new Set();
+    for (const check of checks) {
+        const status = text(check.status) ?? 'skip';
+        const findings = array(check.findings).map((finding) => toViewFinding(finding, text(check.id)));
+        if (status === 'pass' && !options.includePassing)
+            continue;
+        const body = findingLines(findings, options, seenFacts);
+        if (status !== 'fail' && body.length === 0)
+            continue;
+        lines.push('');
+        lines.push(`${status.toUpperCase()} ${text(check.id) ?? '?'} ${text(check.name) ?? ''} — ${text(check.detail) ?? ''} (${String(findings.length)} finding(s))`.replace(/ +— +$/, ''));
+        lines.push(...body);
+    }
+    return [...lines, ...wrapFooter(report)];
+}
+/** A flat `findings[]` report (uml review, structure, granularity, concurrency). */
+function renderFindingsReport(report, options) {
+    const findings = array(report.findings).map((finding) => toViewFinding(finding));
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warnings = findings.length - errors;
+    const byCode = new Map();
+    for (const finding of findings)
+        byCode.set(finding.code, (byCode.get(finding.code) ?? 0) + 1);
+    const lines = [
+        ...headerLines(report, options),
+        `FINDINGS  ${String(findings.length)} total (${String(errors)} error, ${String(warnings)} warning): ${[...byCode].map(([code, n]) => `${code} x${String(n)}`).join(' | ')}`,
+    ];
+    const body = findingLines(findings, options, new Set());
+    if (body.length > 0)
+        lines.push('', ...body);
+    return [...lines, ...wrapFooter(report)];
+}
+/** A baseline diff report: what a change added, removed or changed. */
+function renderDeltaReport(report, options) {
+    const lines = headerLines(report, options);
+    const delta = record(report.delta) ?? report;
+    const section = (key) => array(delta[key]).map((finding) => toViewFinding(finding));
+    for (const key of ['added', 'removed', 'changed']) {
+        const findings = section(key);
+        if (findings.length === 0)
+            continue;
+        lines.push('', `${key.toUpperCase()} (${String(findings.length)})`);
+        lines.push(...findingLines(findings, options, new Set()));
+    }
+    const current = text(report.currentVerdict) ?? text(record(report.current)?.verdict);
+    if (current !== undefined)
+        lines.push(`CURRENT  verdict=${current}`);
+    return [...lines, ...wrapFooter(report)];
+}
+/** A payload result (a rendered diagram, an exported file): print the payload, not JSON of it. */
+function renderPayloadReport(report, options) {
+    const lines = headerLines(report, options);
+    const primary = text(report.diagram) ?? text(report.primary);
+    if (primary !== undefined)
+        lines.push('', primary.trimEnd());
+    const extras = record(report.extras);
+    for (const [name, content] of Object.entries(extras ?? {})) {
+        const body = text(content);
+        if (body !== undefined)
+            lines.push('', `--- ${name} ---`, body.trimEnd());
+    }
+    const warnings = array(report.warnings).map(String).filter((warning) => warning !== '');
+    for (const warning of warnings)
+        lines.push(`WARNING  ${warning}`);
+    return [...lines, ...wrapFooter(report)];
+}
+function wrapFooter(report) {
+    const footer = footerLines(report);
+    return footer.length === 0 ? [] : ['', ...footer];
+}
+/**
+ * A refusal, or a shape this module does not recognize: state the reason first, then the
+ * remaining fields compactly so nothing is lost, without paying for indentation.
+ */
+function renderFallbackReport(report, options) {
+    const lines = headerLines(report, options);
+    const message = text(report.error);
+    if (message !== undefined) {
+        const code = text(report.errorCode);
+        lines.push(`ERROR  ${message}${code === undefined ? '' : ` [${code}]`}`);
+    }
+    const rest = { ...report };
+    delete rest.error;
+    delete rest.errorCode;
+    lines.push('', JSON.stringify(rest));
+    return [...lines, ...wrapFooter(report)];
+}
+/**
+ * Render any logicprobe result as the text a model reads.
+ *
+ * Order of recognition: a `checks[]` report, a flat `findings[]` report, a baseline delta,
+ * a payload result (`diagram`/`primary`), and finally compact JSON so an unrecognized shape
+ * is still readable rather than silently empty.
+ */
+export function renderReportText(value, options = {}) {
+    const resolved = { ...DEFAULTS, ...options };
+    if (resolved.full)
+        return JSON.stringify(value, null, 2);
+    const report = record(value);
+    if (report === undefined)
+        return JSON.stringify(value) ?? String(value);
+    const hasChecks = array(report.checks).some((check) => record(check) !== undefined);
+    const hasFindings = array(report.findings).length > 0;
+    const isDelta = array(report.added).length + array(report.removed).length + array(report.changed).length > 0;
+    const isPayload = typeof report.diagram === 'string' || typeof report.primary === 'string';
+    const lines = hasChecks
+        ? renderChecksReport(report, resolved)
+        : isDelta
+            ? renderDeltaReport(report, resolved)
+            : hasFindings
+                ? renderFindingsReport(report, resolved)
+                : isPayload
+                    ? renderPayloadReport(report, resolved)
+                    : renderFallbackReport(report, resolved);
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+}

package/lib/structure-tool.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { REPORT_SCHEMAS } from './engine.js';
 import { reviewStructure } from './structure.js';
 import { reviewGranularity } from './granularity.js';
+import { renderReportText } from './report-view.js';
 export const LOGICPROBE_STRUCTURE_TOOL_NAME = 'logicprobe_structure_verify';
 /**
  * Model-visible DSH tool that audits a *structure* diagram — components, packages,
@@ -32,14 +33,19 @@ export const logicProbeStructureTool = defineTool({
             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.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured report, which logicprobe_report_diff needs.',
+        },
     },
     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) }];
+        render(args, value) {
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,