dsh-logicprobe 1.1.0 → 1.3.0

package/lib/uml-tool.js

@@ -1,7 +1,8 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { createHash } from 'node:crypto';
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings } from './engine.js';
-import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, UmlError } from './uml.js';
+import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError } from './uml.js';
+import { renderReportText } from './report-view.js';
 export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml';
 /**
  * DSH tool wrapping the UML front end: model a code flow as a UML diagram
@@ -17,7 +18,7 @@ export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml';
  */
 export const logicProbeUmlTool = defineTool({
     name: LOGICPROBE_UML_TOOL_NAME,
-    description: 'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Read `verdict`, not `ok`: error findings mean a failed review.',
+    description: 'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Declare `intent` (present, verify, fidelity) to say what the artifact is for: a view that cannot serve it is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes. Read `verdict`, not `ok`: error findings mean a failed review.',
     parameters: {
         action: {
             type: 'string',
@@ -43,6 +44,11 @@ export const logicProbeUmlTool = defineTool({
             enum: ['state', 'activity', 'sequence'],
             description: 'Diagram kind to render. Default state. sequence is one BFS trace, not the whole machine. PlantUML activity is refused (its structured-flowchart syntax cannot faithfully carry a graph with merges or cycles) — use mermaid for that view.',
         },
+        intent: {
+            type: 'string',
+            enum: ['present', 'verify', 'fidelity'],
+            description: 'What the artifact is for, declared up front: present = a human will read the diagram (any view), verify = it must be parseable into a LogicModelV1 for the engine (state or activity), fidelity = the point is the render-and-reparse proof (review only, state or activity). A view that cannot serve the intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes: a sequence view is still rendered, and review still reports UML019.',
+        },
         roundTrip: {
             type: 'boolean',
             description: 'review only: render and re-parse the model to prove the diagram carries it. Default true.',
@@ -51,23 +57,21 @@ export const logicProbeUmlTool = defineTool({
             type: 'integer',
             description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.',
         },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the diagram or report body; full prints the structured result as JSON.',
+        },
     },
     output: {
         schema: {
             type: 'json',
             description: 'Render result (diagram source), parse result (LogicModelV1 + labels), or the modelling review report with findings, round-trip diff and next steps.',
         },
-        render(_args, value) {
-            const record = value;
-            // A rendered diagram is source text: print it verbatim so it can be copied
-            // into a file, then the structured result (warnings, notation, kind).
-            if (typeof record.diagram === 'string') {
-                return [
-                    { type: 'text', text: record.diagram },
-                    { type: 'text', text: JSON.stringify(value, null, 2) },
-                ];
-            }
-            return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+        render(args, value) {
+            // A rendered diagram is source text: the report body prints it verbatim, once.
+            // Echoing the whole result as JSON printed the same diagram a second time, escaped.
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
         },
     },
     timeoutMs: 10_000,
@@ -77,12 +81,13 @@ export const logicProbeUmlTool = defineTool({
             if (args.action === 'render') {
                 if (args.model === undefined)
                     return errorResult('action=render needs `model` (a LogicModelV1 object)');
-                const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation), (args.kind ?? 'state'), args.maxSteps);
+                const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation), (args.kind ?? 'state'), args.maxSteps, args.intent);
                 return { ok: true, ran: true, ...verdictOf(0, result.warnings.length), schema: REPORT_SCHEMAS.umlRender, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, hashes: { diagram: createHash('sha256').update(result.primary).digest('hex') }, warnings: result.warnings };
             }
             if (args.action === 'parse') {
                 if (args.diagram === undefined)
                     return errorResult('action=parse needs `diagram` (Mermaid or PlantUML text)');
+                checkUmlIntent(args.intent, 'parse');
                 const result = parseUml(args.diagram, args.notation ?? 'auto');
                 // A diagram from another family still parses into *something*. `parseFindings`
                 // says so, and the verdict is what stops that something from being trusted:
@@ -108,6 +113,7 @@ export const logicProbeUmlTool = defineTool({
             // R9: the label contract was documented in the library and in `explainLabels()`, but no
             // tool exposed it, so it was reachable only by reading the source or the docs.
             if (args.action === 'explain-labels') {
+                checkUmlIntent(args.intent, 'labels');
                 const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation);
                 return {
                     ok: true,
@@ -125,6 +131,7 @@ export const logicProbeUmlTool = defineTool({
                 diagramKind: (args.kind ?? 'state'),
                 roundTrip: args.roundTrip,
                 maxSteps: args.maxSteps,
+                intent: args.intent,
             });
             return report;
         }

package/lib/uml.js

@@ -33,6 +33,7 @@
 import { REPORT_SCHEMAS, validateModel, modelHash, metadataKeysOf, narrativeComplete, narrativeCoverageOf, verdictOfFindings, DEFAULT_HASH_SPEC } from './engine.js';
 export const UML_NOTATIONS = ['mermaid', 'plantuml'];
 export const UML_DIAGRAMS = ['state', 'activity', 'sequence'];
+export const UML_INTENTS = ['present', 'verify', 'fidelity'];
 /** Marker every generated diagram carries; renderers ignore it, the parser uses it. */
 const DIRECTIVE_NAMESPACE = 'logicprobe:';
 /** State id / event name characters that would break the generated label syntax. */
@@ -286,28 +287,90 @@ function renderSequence(context, notation, maxSteps) {
         lines.push('@enduml');
     return { text: lines.join('\n') + '\n', truncated };
 }
+/** What each action hands back, so a declared intent can be matched against it. */
+const ACTION_PRODUCES = {
+    render: 'a diagram',
+    parse: 'a LogicModelV1 read out of a diagram',
+    review: 'an audit of the modelling',
+    labels: 'the label and comment conventions the parser accepts',
+};
 /**
- * Render a LogicModelV1 as UML.
+ * The intents each action can serve.
  *
- * PlantUML has no faithful activity view here: its activity syntax is a
- * structured flowchart language, so a graph with merges or cycles needs a
- * while/if reconstruction this module does not perform. Refusing is the honest
- * outcome — quietly emitting a state diagram under an "activity" request would
- * mislabel the model. Mermaid covers all three views.
+ * `fidelity` is a review job: render produces a diagram, and a diagram nothing has
+ * compared back to its model proves nothing about it.
+ */
+const ACTION_INTENTS = {
+    render: ['present', 'verify'],
+    parse: ['verify'],
+    review: ['present', 'verify', 'fidelity'],
+    labels: [],
+};
+/**
+ * The `(notation, view)` cells this module can draw.
  *
- * @param input - candidate LogicModelV1.
- * @param notation - `mermaid` (default) or `plantuml`.
- * @param diagram - `state` (default), `activity`, or `sequence`.
- * @param maxSteps - cap on the sequence trace length.
+ * PlantUML activity is the cell that does not exist: its activity syntax is a
+ * structured flowchart language, so a graph with merges or cycles needs a while/if
+ * reconstruction this module does not perform. Refusing is the honest outcome —
+ * quietly emitting a state diagram under an "activity" request would mislabel the
+ * model.
  */
-export function renderUml(input, notation = 'mermaid', diagram = 'state', maxSteps = 60) {
+export function assertUmlView(notation, diagram) {
     if (!UML_NOTATIONS.includes(notation))
         throw new UmlError('unknown notation "' + String(notation) + '"; expected ' + UML_NOTATIONS.join(' | '));
     if (!UML_DIAGRAMS.includes(diagram))
         throw new UmlError('unknown diagram "' + String(diagram) + '"; expected ' + UML_DIAGRAMS.join(' | '));
     if (notation === 'plantuml' && diagram === 'activity') {
-        throw new UmlError('plantuml has no faithful activity view here (its activity syntax is a structured flowchart language; a graph with merges or cycles needs a while/if reconstruction logicprobe does not perform) — use notation "mermaid" for the activity view, or diagram "state"');
+        throw new UmlError('plantuml has no faithful activity view here (its activity syntax is a structured flowchart language; a graph with merges or cycles needs a while/if reconstruction logicprobe does not perform) — use notation "mermaid" for the activity view, or diagram "state"', 'UML_VIEW_UNREPRESENTABLE');
     }
+}
+/**
+ * Refuse, before any work, a request whose declared purpose the view cannot serve.
+ *
+ * Without an intent this changes nothing: the review still reports `UML019` when the
+ * fidelity check does not apply to the view it was given. With one, an impossible
+ * pairing is an error carrying a code, instead of a report about the wrong artifact —
+ * which is the failure this check exists to prevent.
+ *
+ * @param intent - the declared purpose, or `undefined` to leave the behaviour unchanged.
+ * @param action - which action is about to run.
+ * @param view - the requested `(notation, diagram)`, for the actions that have one.
+ */
+export function checkUmlIntent(intent, action, view) {
+    if (intent === undefined)
+        return;
+    if (!UML_INTENTS.includes(intent))
+        throw new UmlError('unknown intent "' + String(intent) + '"; expected ' + UML_INTENTS.join(' | '));
+    const served = ACTION_INTENTS[action];
+    if (!served.includes(intent)) {
+        throw new UmlError('intent "' + intent + '" cannot be served by action=' + action + ', which returns ' + ACTION_PRODUCES[action] + '; it serves ' +
+            (served.length === 0 ? 'no intent — leave `intent` off' : served.join(' | ')), 'UML_INTENT_MISMATCH');
+    }
+    if (view === undefined)
+        return;
+    assertUmlView(view.notation, view.diagram);
+    if (intent === 'present' || view.diagram !== 'sequence')
+        return;
+    throw new UmlError('intent "' + intent + '" needs a machine, and a sequence view is one BFS trace: ' +
+        (intent === 'fidelity'
+            ? 'the render/parse fidelity check does not apply to a trace, so nothing would be proven. Review kind "state" or "activity" to have the diagram checked against the model, and render the trace separately with intent "present".'
+            : '`parse` refuses a trace because it cannot reconstruct a machine, so the diagram cannot feed verification. Model the machine as a state or activity diagram, and render the trace separately with intent "present".'), 'UML_INTENT_UNSERVABLE');
+}
+/**
+ * Render a LogicModelV1 as UML.
+ *
+ * Mermaid covers all three views; PlantUML covers state and sequence (see
+ * `assertUmlView` for why activity is refused).
+ *
+ * @param input - candidate LogicModelV1.
+ * @param notation - `mermaid` (default) or `plantuml`.
+ * @param diagram - `state` (default), `activity`, or `sequence`.
+ * @param maxSteps - cap on the sequence trace length.
+ * @param intent - what the diagram is for; a view that cannot serve it is refused first.
+ */
+export function renderUml(input, notation = 'mermaid', diagram = 'state', maxSteps = 60, intent) {
+    assertUmlView(notation, diagram);
+    checkUmlIntent(intent, 'render', { notation, diagram });
     const context = prepareRender(input);
     const warnings = [...context.warnings];
     let primary;
@@ -1563,6 +1626,7 @@ export function reviewUml(options) {
         throw new UmlError('review needs `model`, `diagram`, or both');
     let notation = options.notation === undefined || options.notation === 'auto' ? 'mermaid' : options.notation;
     const kind = options.diagramKind ?? 'state';
+    checkUmlIntent(options.intent, 'review', { notation, diagram: kind });
     let model;
     let labels;
     let parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-logicprobe",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Verifies claims about designs and code. Facts go against the source. Behaviour goes through an executable model: state machines, protocols, composition, data models, migrations. Structure diagrams are read as dependency graphs, at one level or several. Two reports can be compared for regression. Exports UPPAAL, TLA+, PRISM and SPIN input. Ships a native DeepSeek Harness bundle that injects the verification gate into the first model step.",
   "type": "module",
   "main": "lib/index.js",
@@ -79,7 +79,7 @@
     "build": "tsc -p tsconfig.json && node scripts/build-client.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "bump": "node scripts/bump-version.mjs",
-    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/dsh-client-half.test.mjs && node tests/dsh-volatile-fallback.test.mjs && node tests/claude-session-start-hook.test.mjs && node tests/skills/run.mjs && node tests/structure/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/external/run.mjs && node tests/python/run.mjs",
+    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/dsh-client-half.test.mjs && node tests/dsh-volatile-fallback.test.mjs && node tests/claude-session-start-hook.test.mjs && node tests/skills/run.mjs && node tests/structure/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/external/run.mjs && node tests/python/run.mjs",
     "test:full": "npm run build && node tests/full-suite.mjs",
     "test:python": "npm run build && node tests/python/run.mjs"
   },

package/skills/logicprobe/SKILL.md

@@ -60,7 +60,7 @@ This step is NOT skippable — it creates an explicit, auditable record of what
 |-------|----------|
 | LIGHTWEIGHT | All 5 checklist items (file paths, API/type names, line numbers, behavioral claims, mechanism feasibility) answered in context with explicit results per item |
 | STANDARD | Phase 1-2: enumerate every verifiable claim → verify each against codebase with evidence |
-| ESCALATED | Full pipeline: Phase 1-5 including Logic Primitive Verification (Phase 2a + 2b, 22 checks) |
+| ESCALATED | Full pipeline: Phase 1-5 including Logic Primitive Verification (Phase 2a structural, Phase 2b adversarial) |
 
 ### Plan Verification Block
 
@@ -151,7 +151,7 @@ Document claims → Extract model → Runtime check:
 
 Refactoring variant:
   Old code + Refactoring plan → Extract BEFORE model + AFTER model
-    → Run pipeline on AFTER model (22 checks)
+    → Run the pipeline on the AFTER model (the same checks)
     → Compare BEFORE vs AFTER: behavioral preservation, regression, complexity delta
     → Flag any invariant that held in BEFORE but fails in AFTER
 
@@ -171,8 +171,10 @@ UML modelling variant (the task is to draw a flow, not to check a claim):
 | `logicprobe_concurrency_scan` | Mines concurrency claims (thread-safe, lock-free, race condition, mutex, ISR-safe) and routes them to dedicated verification. It does not prove concurrency safety. |
 | `logicprobe_export` | Emits external-checker input from a verified model: UPPAAL, TLA+, PRISM, SPIN. |
 | `logicprobe_uml` | render / parse / review / explain-labels for UML modelling — the diagram domain belongs to the `logicprobe-uml` skill. |
+| `logicprobe_structure_verify` | Reviews a structure diagram as a dependency graph. It reports isolated nodes, dangling endpoints, cycles, disallowed edges, layer violations and missing required edges, and it checks refinement across declared levels. The diagram domain belongs to the `logicprobe-structure` skill. |
+| `logicprobe_report_diff` | Compares two reports of the same family. A finding's identity is its check, its code and its machine-readable locator, so reworded prose reads as changed rather than new. This is slice acceptance computed instead of eyeballed. Without the tool, `verify --baseline REPORT` prints the same diff. |
 
-The repository engine mirrors the same checks and carries the `compose` and `export` subcommands for hosts without the native tools.
+The repository engine mirrors the same checks for hosts without the native tools, and its `--help` lists the subcommands. Two capabilities have no mirror. Data-model verification takes the data harness or the manual mode there. The concurrency claim scan is the same story: `logicprobe-concurrency` routes the claims instead. That engine prints the report JSON, not the body — the body is the dsh tools' rendering.
 
 ### Reading a Report: `ok` Is Not a Verdict
 
@@ -191,6 +193,8 @@ Every tool report carries the same outcome contract. **`ok` says a report was pr
 | `metadataKeys[]` | Paths of the `_`-prefixed annotation keys the schema ignored, e.g. `["_source", "_verified", "states[0]._note"]` (present only when the input carried any). |
 | `narrativeCoverage` | `{states: "5/5", events: "3/9", scenarios: "0/12"}` when the model carries a narrative — a partial narrative is valid, and this is how much is still undocumented. The gap is also a `NARRATIVE_PARTIAL` (info) finding, so a gate can read it without parsing `nextSteps` text. |
 
+A tool prints a body, not JSON. Passing checks stay in the `CHECKS` inventory line, and a fact that several checks report is listed once. Only error findings inline their evidence. Pass `reportView: "full"` when you need the structured report itself, for example to hand it to `logicprobe_report_diff`.
+
 Turn the verdict into an answer, never into a summary of `ok`:
 
 - `verdict: "pass"` — no error and no warning finding. Safe to report as verified, still with the scope the model covered.
@@ -199,6 +203,25 @@ Turn the verdict into an answer, never into a summary of `ok`:
 
 Exit codes: `0` for `pass` / `pass_with_findings`, `2` for `fail`, a refusal, or an unreadable input. In DSH the native tools return the report as data — read `verdict`, and treat `errorCode`/`error` as the refusal path.
 
+### Writing the Answer: Name the Finding, Not Its Code
+
+`S2_NO_TRANSITIONS`, `UML019`, `DA2` are values of `findings[].code`, not names. A reader
+who has not memorized the schema learns nothing from one, and cannot tell whether their
+machine is sound or stuck.
+
+- **Say what it means**, in the user's language and in the terms of their own code:
+  「启动超时后 ERROR 没有任何出口迁移，机器会停在那里」, not 「S2 命中」. The finding's
+  `message` is written for the report; the sentence for the user is written from it.
+- **Keep the identifier where the identifier is the subject**: a report field quoted
+  verbatim, a baseline diff, a test name, or a question about the check itself.
+- **Name the property, not the checking.** "This path locks without unlocking" beats
+  "A4 failed". A check's name earns its place when the reader asked about the checking.
+- **Carry the verdict in words.** "Not verified" or "verified, within the scope of this
+  model" — never a bare pass, and never a warning presented without its label.
+
+A reader who cannot tell what failed will either trust a report they cannot read, or
+ignore one they should act on.
+
 ### Slice Acceptance: Baseline Diffs
 
 The acceptance criterion for a refactoring slice is usually "no **new** findings", not
@@ -231,7 +254,7 @@ When the document under review is a refactoring plan (modifying existing state m
 1. **Extract the BEFORE model** from the existing codebase (not the plan — verify what the code actually does, not what the plan claims it does)
 2. **Extract the AFTER model** from the refactoring plan
 3. **Show both tables AND their model narratives** to the user side by side and confirm the delta is intentional
-4. **Run Phase 2a + 2b on the AFTER model** — same 22 checks as new design
+4. **Run Phase 2a + 2b on the AFTER model** — the same checks a new design gets
 5. **Compare BEFORE vs AFTER**:
 
    | Check | Method | Severity if Violated |
@@ -248,7 +271,7 @@ When the document under review is a refactoring plan (modifying existing state m
 
 Run the checks with the native `logicprobe_verify` tool (model JSON, structured guard DSL, path-aware invariants) — see `references/dsh-model-schema.md`. A host without the tools can run the repository engine against the same JSON. For probe patterns, extraction methodology and manual procedures, load `references/logic-verification-guide.md`.
 
-### Phase 2a: Structural Primitives (8 Checks)
+### Phase 2a: Structural Primitives
 
 Run these FIRST. They establish basic well-formedness before adversarial probing.
 
@@ -263,7 +286,7 @@ Run these FIRST. They establish basic well-formedness before adversarial probing
 | S7 | **Invariant validity** | Does every reachable state satisfy the plan's stated "always/never/guaranteed" assertions? | Error — plan claim is false |
 | S8 | **Monotonic variables** | If a variable is declared `monotonic: inc/dec`, do all updates respect that direction? | Error — counter can move backwards |
 
-### Phase 2b: Adversarial Probes (14 Attacks)
+### Phase 2b: Adversarial Probes
 
 Run these SECOND. Each probe actively tries to BREAK the model. If any probe succeeds (finds a violation), the plan has a behavior gap.
 
@@ -402,6 +425,19 @@ This skill owns behavioural claims. Three neighbouring domains have their own sk
 
 ---
 
+## Red Flags
+
+If you catch yourself thinking 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. |
+
 ## Rules
 
 1. Never trust a document's claim without codebase verification.

package/skills/logicprobe/references/dsh-model-schema.md

@@ -1,6 +1,6 @@
 # DSH Model Schema v1 — logicprobe_verify
 
-The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The engine runs 22 checks (S1-S8 structural, A1-A14) and returns a JSON report. When `beforeModel` is supplied, it also runs D1-D4 before/after regression checks. Guards and updates are structured data — no code strings, no arbitrary execution.
+The dsh-native `logicprobe_verify` tool accepts a structured JSON model. The engine runs the structural and adversarial checks (S1-S8, A1-A14) and returns a JSON report. When `beforeModel` is supplied, it also runs D1-D4 before/after regression checks. Guards and updates are structured data — no code strings, no arbitrary execution.
 
 ## Top-level model
 

package/skills/logicprobe/references/gap-routing-guide.md

@@ -10,14 +10,15 @@ as outside this engine and points at tooling that can handle it.
 
 | Dimension | What logicprobe covers today | Claim examples | Dedicated tooling | Why not here |
 |---|---|---|---|---|
-| Hard real time (timing) | Order, counts, path budgets (A12); time modeled only as counters + events | "500 ms to SAFE", "no deadline miss", "period ≤ 1 ms" | UPPAAL, IMITATOR (timed automata); binary-level timing analysis for WCET | No clocks, deadlines, or period semantics |
+| Hard real time (timing) | Order, counts, path budgets (A12), and deadlines over discrete ticks (A14). Time otherwise appears as counters and events | "500 ms to SAFE", "no deadline miss", "period ≤ 1 ms" | UPPAAL, IMITATOR (timed automata); binary-level timing analysis for WCET | No continuous clocks. A deadline that is not a tick count cannot be expressed |
 | Preemptive concurrency | Event-order interleavings (A2/A3), resource pairing (A4), idempotent replay (A8) | "thread-safe", "interrupt-safe", "no priority inversion" | TSan/Helgrind (runtime), CBMC (proof), TLA+ (interleaving model), RTOS-aware analysis | Single-threaded event model; no preemption, IRQ nesting, or atomics at instruction level |
 | Hybrid control (continuous plant) | Discrete transitions and modes only | "switching is stable", "no chattering", "settling within T" | SpaceEx, Flow* (hybrid reachability), Simulink/Stateflow verification | No continuous dynamics; stability is not expressible |
 | Probabilistic / reliability | Qualitative reachability and invariants | "MTBF ≥ X", "failure rate ≤ p", "availability ≥ 99.9%" | PRISM, Storm (stochastic model checking), fault-tree / FMEA | No probability semantics |
 | Execution cost / performance | A12 budget checks over declared transition `cost` (absent = 1) | "worst-case dispatch ≤ 100 cycles" | aiT, RapiTime (real WCET at binary level) | `cost` is a modeler label, not measured execution time |
-| Multi-machine composition | Single machine verified; cross-machine contract must be documented separately | "A sends E, B always handles E" | CSP (FDR), mCRL2, TLA+ (compositional models) | No composition semantics between machines |
-| Nested/hierarchical statecharts | Flat models only; flatten before verification | parent/child states, orthogonal regions | SCXML / Stateflow (native hierarchy) | Flat state list only — flatten manually and re-confirm |
-| Write-site / single-owner analysis | **Not covered, and not planned.** logicprobe reviews the diagram and the model; it does not read the source to see *who writes* a variable, a register or a field | "only the ISR writes this", "one owner per flag", "no double write to the CAN mailbox" | A source-side AST/rule check (e.g. the project's own include/arch checker), a static analyzer (clang-tidy, PC-lint, Coverity), or a model checker over the real code (CBMC) | It needs the source and a rule table about statements — a different input than a model or a diagram. `logicprobe_concurrency_scan` will flag the *claim* as unverified and route it here, which is the honest part of this plugin's answer |
+| Multi-machine composition | `logicprobe_compose_verify` (dsh) and the engine's `compose` subcommand (non-dsh) check machines together: C1 composition deadlock, C2 a rendezvous that never fires. They stop at one handshake event per rendezvous | "A sends E, B always handles E", "these two never deadlock" | CSP (FDR), mCRL2, TLA+ (compositional models) | No payloads, no rate ratio and no fairness bound; each machine's own step order is free |
+| Protocol semantics (message contents, channels, per-message ordering) | Events and handshakes between machines | "QoS 1 delivers exactly once", "the broker never reorders", "the queue never overflows" | TLA+, mCRL2, SPIN (Promela channels) | The model has states and events, not messages, queues or payloads |
+| Nested/hierarchical statecharts | Flat models only; flatten before verification | parent/child states, orthogonal regions | SCXML / Stateflow (native hierarchy) | A flat state list only. `logicprobe_compose_verify` places machines side by side; it does not nest states. Flatten manually and re-confirm |
+| Write-site / single-owner analysis | **Not covered, and not planned.** logicprobe reviews the diagram and the model; it does not read the source to see *who writes* a variable, a register or a field | "only the ISR writes this", "one owner per flag", "no double write to the CAN mailbox" | A source-side AST/rule check (e.g. the project's own include/arch checker), a static analyzer (clang-tidy, PC-lint, Coverity), or a model checker over the real code (CBMC) | It needs the source and a rule table about statements — a different input than a model or a diagram. `logicprobe_concurrency_scan` will flag the *claim* as unverified and route it here, which is the honest part of this plugin's answer (it is a dsh-only capability; without it, route the claim by hand) |
 
 ## Where the routing surfaces
 
@@ -30,8 +31,8 @@ as outside this engine and points at tooling that can handle it.
   interrupt-safe, ...) carry `suggestions` naming dedicated tools.
 - Manual review: when reading a plan, match its claims against the table above and
   require dedicated evidence before accepting "always"/"never"/"guaranteed" language
-- Generators: `exportModel(model, format)` emits native inputs for UPPAAL (.xta + queries),
-  TLA+ (TLC spec + safety), PRISM (.pm + .pctl), and SPIN (Promela + ltl) from a
-  LogicModelV1 — v1 translates the core machine (guards/updates/weights; booleans as
-  integers) and leaves unrepresentable invariants as explicit warnings.
-  Self-tests: tests/exporters/run.mjs.
+- Generators: `logicprobe_export` (dsh) and the engine's `export` subcommand (non-dsh) emit
+  native inputs for UPPAAL (.xta + queries), TLA+ (TLC spec + safety), PRISM (.pm + .pctl),
+  and SPIN (Promela + ltl) from a LogicModelV1. Both translate the core machine (guards,
+  updates, weights; booleans as integers) and return unrepresentable invariants as explicit
+  warnings.

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

@@ -202,7 +202,7 @@ When a probe finds a counter-example, classify it:
 
 ### Model Fidelity Warning
 
-The model is an APPROXIMATION. It models state transitions, not execution semantics. A model that passes all 22 checks (S1-S8 structural, A1-A14) means the plan's LOGIC is consistent — NOT that the implementation will work. Always follow logic verification with code-level review.
+The model is an APPROXIMATION. It models state transitions, not execution semantics. A model that passes every check (S1-S8 structural, A1-A14) means the plan's LOGIC is consistent — NOT that the implementation will work. Always follow logic verification with code-level review.
 
 ## Refactoring Verification
 

package/skills/logicprobe-concurrency/SKILL.md

@@ -41,3 +41,5 @@ The full routing table, including hard-real-time, hybrid-control and execution-c
 2. **No absolute language in the answer.** "This is thread-safe" is exactly the claim being mined, not a result this skill can produce.
 3. **One counterexample is enough to refute.** If a race is suspected, the deliverable is the interleaving that breaks it plus the harness that demonstrates it (TSan/Helgrind output), not an argument.
 4. **Sequential targets are out of scope.** If nothing runs concurrently, say so and stop.
+5. **The scanner is dsh-only.** `logicprobe_concurrency_scan` has no mirror subcommand. Without it, mine the text by hand against the keyword table above and route each claim the same way.
+6. **Name the claim and its routing in words.** 「QoS 1 只投递一次」plus the tool that decides it, never a bare check name. A reader who has not memorized this skill's tables learns nothing from an enumeration. The full rule is under "Writing the Answer" in the `logicprobe` skill.

package/skills/logicprobe-datamodel/SKILL.md

@@ -92,6 +92,11 @@ The **DataModelV1 shape** is in [`references/data-model-schema.md`](references/d
 | DD3 | Delta summary | Warning |
 | DD4 | Breaking change regression | Error/Warning |
 
+Every `#` in these tables is a report field, not a name. Write what the check found for the
+reader (「回滚与备份不对称」), in their language; keep the id for a report field quoted
+verbatim, a baseline diff or a test name. The full rule is under "Writing the Answer" in the
+`logicprobe` skill.
+
 ## Extraction Rule
 
 Before writing any verification code, output a data-model table:

package/skills/logicprobe-structure/SKILL.md

@@ -91,5 +91,6 @@ This tool audits the **diagram**; an include or dependency scan audits the **cod
 2. **Quote the rule id for every judged edge.** "Not allowed" without the rule is an opinion; `matchedRules` makes it a finding.
 3. **Run the numbers, never the impression.** An isolated node and a back edge are exactly what a reader misses by eye; that is why the check exists.
 4. **Report the diagram-code difference, not just the diagram.** A structure review that never touches the source is a review of a drawing.
+5. **Report the rule id with its meaning, never the id alone.** Rule 2 keeps the id on every judged edge, so the finding is defensible; the sentence the reader gets says what the edge violated (「HAL 反向依赖了上层」), in their language. The full rule is under "Writing the Answer" in the `logicprobe` skill.
 
 The full matrix schema, a worked example and the reconciliation worksheet are in [`references/structure-review-guide.md`](references/structure-review-guide.md).

package/skills/logicprobe-uml/SKILL.md

@@ -32,6 +32,8 @@ code flow → model (citation per element) → logicprobe_uml action=render →
 - **review** — it answers one of three questions. Give it a model: is the machine well-modelled? Give it a diagram: what does the diagram say? Give it both: does the diagram match the model?
 - **explain-labels** — the parser's own account of labels and comments: the accepted spellings, the form the renderer writes, and which lines it ignores. No diagram needed. It answers "why does my hand-drawn diagram report drift or ignored lines?" without reading the source.
 
+The view follows the question, not the machine, and no tool picks it for you. Declare the question with `intent` (`present` / `verify` / `fidelity`) and a view that cannot serve it is refused before any work, with a code that names why. The ordered procedure, the intent-by-action table and those codes are under [Choosing the view](references/uml-modeling-guide.md#choosing-the-view).
+
 A host without the tools runs the same four actions through the repository engine. The engine is deliberately single-source — do not copy it into this skill.
 
 ## A Structure Diagram Is the Dangerous Case, Because It Parses
@@ -53,5 +55,6 @@ Structural defects: unreachable states, dead ends, ambiguous or non-exhaustive b
 3. **Check the verdict before the picture.** `ok: true` with `verdict: "fail"` means the review failed; a diagram whose review failed is not something to show as if it were checked.
 4. **The review never replaces verification.** It covers the modelling. S1-S8 and A1-A14 cover the behaviour, and each finding names the check that settles it — hand those over to the `logicprobe` skill.
 5. **Keep the narrative with the model.** Write `narrative.states`, `narrative.events` and `narrative.scenarios`. Then the diagram stays readable against the code, and label drift shows up as a finding instead of as a stale picture.
+6. **Name a finding for the reader, not by its code.** `UML017_ROUND_TRIP_MISMATCH` is a report field; the sentence the reader gets says what disagreed (「图里少了 ERROR→COOLDOWN 这条迁移」), in their language. Keep the code for a report field quoted verbatim, a diff or a test name. The full rule is under "Writing the Answer" in the `logicprobe` skill.
 
 The full checklist (codes `UML001` to `UML019` plus `UML_NOT_A_STATE_DIAGRAM`), the directive format generated diagrams carry, a worked example, and the limits of each view are in [`references/uml-modeling-guide.md`](references/uml-modeling-guide.md).

package/skills/logicprobe-uml/references/uml-modeling-guide.md

@@ -4,7 +4,17 @@ This guide covers two jobs: drawing a code flow as UML, and reviewing that drawi
 
 One rule runs through the whole guide. **A diagram is a model, and a model can be wrong.** A tidy flow chart is not evidence about the code. Worse, a diagram that disagrees with the model it came from will mislead every reader who trusts it.
 
-## When to use this
+## Choosing the view
+
+The view follows the question, not the machine. Decide in this order.
+
+**1. Is the question about where dependencies point?** Architecture, layering, module
+structure, "may this call that" — that question belongs to the `logicprobe-structure`
+skill, which reads the same component, package, class or deployment text as a dependency
+graph. The state front end refuses that text by name
+(`UML_NOT_A_STATE_DIAGRAM`) instead of reviewing it.
+
+**2. Otherwise fix the boundary first, then pick the view by the reader's question.**
 
 | Situation | View that answers it |
 |---|---|
@@ -14,7 +24,65 @@ One rule runs through the whole guide. **A diagram is a model, and a model can b
 | "Somebody gave me a diagram. Is it right?" | Any view. Feed it to the review and compare it against the code. |
 | "This diagram and this model disagree." | Feed both to the review. The round-trip check names every difference. |
 
-Do not use this guide for a behavioural claim about a specific machine. That is the job of `logicprobe_verify` (S1-S8 and A1-A14). The review here covers the modelling, not the behaviour. Every finding it produces names the engine check that settles the behavioural half.
+**3. Check the choice against the next step.** A view that cannot feed the check you are
+about to run is the wrong view, however readable it looks.
+
+| Next step | Views that can feed it |
+|---|---|
+| `logicprobe_verify` (S1-S8 and A1-A14) | State or activity: `parse` reads either into a LogicModelV1 |
+| `logicprobe_uml action=review` with a model, for the fidelity check | State or activity: only those round-trip |
+| `logicprobe_uml action=review` with a model alone | Any view. With `kind: "sequence"` the trace is rendered and the fidelity check is reported inapplicable (`UML019`) |
+| A human reading a protocol exchange | Sequence, which is the honest view there |
+
+**4. Say that out loud, and the tool refuses a pairing that cannot serve it.** `intent`
+declares what the artifact is for. The check runs before any work, so an impossible
+pairing is a refusal with a code rather than a report about the wrong artifact.
+
+| Intent | What it means | Actions that serve it | View it needs |
+|---|---|---|---|
+| `present` | a human is going to read the diagram | render, review | any view the notation can draw |
+| `verify` | it must be parseable into a LogicModelV1 for the engine | render, parse, review | state or activity: a trace cannot be parsed back |
+| `fidelity` | the point is the render-and-reparse proof | review | state or activity: only those round-trip |
+
+| `errorCode` | What happened |
+|---|---|
+| `UML_INTENT_UNSERVABLE` | The view exists but cannot serve the intent — a sequence view for `verify` or `fidelity`. |
+| `UML_VIEW_UNREPRESENTABLE` | The `(notation, view)` cell does not exist — PlantUML activity. |
+| `UML_INTENT_MISMATCH` | The intent names something this action does not do — `fidelity` on render (render proves nothing), `present` or `fidelity` on parse (parse returns a model). |
+
+Omitting `intent` changes nothing: a sequence view still renders, and a review of one
+still reports `UML019`. The intent is an opt-in statement of purpose, and nothing infers
+it. The CLI mirror takes the same values: `--intent present|verify|fidelity` on
+`uml-render`, `uml-parse` and `uml-review`.
+
+When the question is still unclear, model the state machine. It is the safe default, and
+the other views render from the same model afterwards.
+
+### Nothing picks the view for you
+
+`render` takes `kind` from the caller and defaults to `state`; it never guesses. A guess
+between state and activity would be a presentation decision, and the machine cannot make
+it: the same guarded branch is a state machine to one reader and an error path to another.
+`parse` does detect the notation and the diagram family from the text, and it refuses the
+families it cannot model, by name.
+
+Mechanically decidable, and nothing else:
+
+- the notation and the family the text declares — a Mermaid header (`stateDiagram`,
+  `flowchart`, `sequenceDiagram`, or a known other-family header) or a PlantUML body
+  keyword;
+- whether the requested notation-and-kind combination exists at all (PlantUML has no
+  activity view here);
+- whether a view can carry the fidelity check (a sequence cannot).
+
+Everything else is a fact about the question, not about the artifact. A model can tell you
+its shape — its state count, its guarded branches, its cycles — and its shape does not
+choose the view.
+
+Do not use this guide for a behavioural claim about a specific machine. That is the job of
+`logicprobe_verify` (S1-S8 and A1-A14). The review here covers the modelling, not the
+behaviour. Every finding it produces names the engine check that settles the behavioural
+half.
 
 ## The three views
 

package/src/compose-tool.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runCompositionVerification } from './engine.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_COMPOSE_TOOL_NAME = 'logicprobe_compose_verify'
 
@@ -26,14 +27,19 @@ export const logicProbeComposeTool = defineTool({
       type: 'integer',
       description: 'Maximum composite states to explore. Default 10000.',
     },
+    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: 'Composition verification report with C1/C2 findings.',
     },
-    render(_args, value) {
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
   },
   timeoutMs: 10_000,

package/src/concurrency-tool.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runConcurrencyScan } from './concurrency.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME = 'logicprobe_concurrency_scan'
 
@@ -20,14 +21,19 @@ export const logicProbeConcurrencyScanTool = defineTool({
       required: true,
       description: 'Document or plan text to scan for concurrency-related claims.',
     },
+    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: 'Concurrency scan report with findings and summary.',
     },
-    render(_args, value) {
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
   },
   timeoutMs: 10_000,