dsh-logicprobe 1.0.0 → 1.2.0

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,

package/src/data-tool.ts

@@ -1,6 +1,7 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runDataVerification, DATA_ENGINE_SCHEMA_VERSION } from './data-engine.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_DATAMODEL_VERIFY_TOOL_NAME = 'logicprobe_datamodel_verify'
 
@@ -40,14 +41,19 @@ export const logicProbeDataModelVerifyTool = defineTool({
       type: 'json',
       description: 'Optional backup/restore pairs for DA7 rollback symmetry.',
     },
+    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: 'logicprobe-datamodel verification report with summary and per-check 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/engine.ts

@@ -206,7 +206,11 @@ export interface PathStep {
 
 export interface Finding {
   code: string
-  severity: 'error' | 'warning'
+  /**
+   * `info` is a note, not a defect: it is reported so a machine-readable reader can see it,
+   * and it never contributes to `verdict`, `summary.errors` or `summary.warnings`.
+   */
+  severity: 'error' | 'warning' | 'info'
   message: string
   /** Longer explanation: the shortest-path note, the per-machine reasons, the quoted source lines. */
   detail?: string
@@ -286,6 +290,20 @@ function verificationNextSteps(checks: CheckResult[], coverage: NarrativeCoverag
   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: string[]): string[] {
+  const steps: string[] = []
+  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
+}
+
 export interface ComparisonSummary {
   beforeModelHash: string
   afterModelHash: string
@@ -366,6 +384,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',
@@ -1060,7 +1079,9 @@ function checkResult(id: string, name: string, findings: Finding[], detail: stri
   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,
   }
@@ -2893,7 +2914,7 @@ export function runVerification(input: unknown, options: VerificationOptions = {
       ...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
@@ -2973,6 +2994,16 @@ export function runVerification(input: unknown, options: VerificationOptions = {
   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,
@@ -3223,11 +3254,21 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
         .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
@@ -3269,7 +3310,7 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
       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(' | '),
@@ -3277,15 +3318,18 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
       })
     }
   }
-  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'
@@ -3294,8 +3338,21 @@ export function runCompositionVerification(machinesInput: unknown[], options: Co
     checkResult('C2', 'Rendezvous Sync', c2Findings, c2Detail),
   ]
   const nextSteps: string[] = []
-  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/src/export-tool.ts

@@ -2,6 +2,7 @@ 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'
+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: unknown): { hashSpec: typeof DEFAULT_HASH_SPEC; modelHash?: string } {
@@ -34,14 +35,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' 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/index.ts

@@ -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.
  *
@@ -75,41 +76,28 @@ 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. 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>
 `
 
 /** A schemastery field that may or may not carry `.volatile()`. */
@@ -261,7 +249,7 @@ function inspectProvider(config: Config, isToolRegistered: () => boolean, isData
   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/src/report-diff-tool.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { diffReports } from './baseline.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_REPORT_DIFF_TOOL_NAME = 'logicprobe_report_diff'
 
@@ -25,14 +26,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' 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,