dsh-logicprobe 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-logicprobe",
-  "version": "1.2.0",
+  "version": "1.4.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",

package/skills/logicprobe/SKILL.md

@@ -161,6 +161,24 @@ UML modelling variant (the task is to draw a flow, not to check a claim):
     → logicprobe_verify → the behavioural checks (S1-S8 / A1-A14)
 ```
 
+### Budgeting the Model Before You Run It
+
+Search cost is the declared domain times the number of states — and a declared range is
+not a bound on the search.
+
+- **`inc`/`dec` are never clamped to `min`/`max`.** The declaration is a property the
+  checks verify, not a limit the engine enforces. A counter whose guard does not pin it
+  ranges past its own declaration, so the reachable set is unbounded however small the
+  declared range looks; S8 reports that as `S8_DOMAIN_NOT_ENFORCED`.
+- **Bound a counter with a guard, not a narrower declaration.** `max: 4` with a guard
+  `retry < 4` closes the loop. `max: 4` alone does not.
+- **Say the budget before running**: values per variable x states. A product in the
+  10^5-and-up range will hit the cap and come back undecided.
+- **Model the check where the code performs it.** A cap check that lives inside the tick
+  handler is a guarded branch of the tick event, not a separate event: as a separate event
+  the environment can starve it, and the leads-to failure you then read is an artefact of
+  the model rather than a property of the code.
+
 ### Native dsh Tools
 
 | Tool | Covers |
@@ -203,6 +221,30 @@ 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.
 
+`summary.truncated: true`, or a finding whose code ends in `_UNDECIDED`
+(`S7_UNDECIDED`, `A7_UNDECIDED`, `A9_LEADS_TO_UNDECIDED`, `D2_UNDECIDED`), means the search
+stopped before deciding. That is **not** a pass: name the invariant that went undecided,
+and say the property is undecided rather than reading the silence as success.
+
+### 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
@@ -418,6 +460,8 @@ If you catch yourself thinking any of these, stop:
 | "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. |
+| "The declared range limits the search" | The declaration is a property to verify. `inc`/`dec` are never clamped to it; only a guard bounds the value. |
+| "The check found nothing" | Read the verdict: `truncated` and `_UNDECIDED` mean the search stopped, not that the property holds. |
 
 ## Rules
 
@@ -430,4 +474,5 @@ If you catch yourself thinking any of these, stop:
 7. **Don't verify what the code already checks.** If the existing codebase has compile-time assertions, static analysis, or runtime checks for a property, cite those — don't re-verify in a model.
 8. **Hand a neighbouring domain to its own skill.** A diagram is a model, not evidence: modelling or auditing one belongs to `logicprobe-uml`. A concurrency claim is mined and routed, never proven here: that is `logicprobe-concurrency`. Schema, data invariants and migrations are `logicprobe-datamodel`. This skill keeps the doctrine and the behavioural checks.
 9. **Say what this does not prove.** For dimensions logicprobe does not verify — hard real time (deadlines, periods), preemptive concurrency, hybrid-control stability, probabilistic reliability, execution-cost budgets — route to the dedicated tool named in `references/gap-routing-guide.md`. `logicprobe_verify` reports carry the same routing as informational `coverageNotes` on matching models.
-10. **Write-site analysis is out of scope, and stays there.** "Only the ISR writes this flag", "one owner per register" — logicprobe verifies models and diagrams, not *who writes what in the source*. That claim needs a source-side AST/rule check or a static analyzer; this plugin's contribution is to flag the claim as unverified and route it (`logicprobe_concurrency_scan` does exactly that). Do not imply the diagram or the model settled it.
+10. **A declared range is a property, not a bound, and a capped search is not a pass.** `inc`/`dec` are never clamped to `min`/`max`; only a guard that pins the value bounds it. When a report is `truncated` or a check is `_UNDECIDED`, say the property is undecided and narrow the model — never report it as verified.
+11. **Write-site analysis is out of scope, and stays there.** "Only the ISR writes this flag", "one owner per register" — logicprobe verifies models and diagrams, not *who writes what in the source*. That claim needs a source-side AST/rule check or a static analyzer; this plugin's contribution is to flag the claim as unverified and route it (`logicprobe_concurrency_scan` does exactly that). Do not imply the diagram or the model settled it.

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

@@ -225,6 +225,17 @@ A guard is exactly one of:
 
 `inc`/`dec` default to 1 when `value` is omitted. `set` defaults to 0.
 
+`inc` and `dec` are **never clamped** to the variable's declared `min`/`max`. The declared
+range is a property the checks verify (S7 `var-in-range`), not a bound on the search: a
+counter whose guard does not pin it ranges past its own declaration, so the reachable set
+is unbounded however narrow the declaration looks. S8 reports that as
+`S8_DOMAIN_NOT_ENFORCED` and names the transition, rather than clamping the value and
+deleting the states a range violation is witnessed by. A `set` constant outside the
+declared range contradicts the declaration and is `S8_DOMAIN_SET_OUTSIDE` (error).
+
+To bound a counter, add a guard that pins it — `"max": 4` with a guard
+`{ "variable": "retry", "op": "<", "value": 4 }` — not a narrower `max`.
+
 ## Invariants
 
 Every invariant carries `id` and **`description`** — both required strings — plus a
@@ -396,9 +407,14 @@ The report's `comparison` object includes both model hashes, state/transition co
 
 List events that must be idempotent in `idempotentEvents`. For every reachable state, applying the event twice must produce the same state as applying it once. This is useful for retries, webhook redelivery, and migration replay.
 
-## Advanced constraints (S8, A9-A14)
+## Advanced constraints (S6, S8, A9-A14)
 
-- **S8 Monotonic Variables**: declare `monotonic: "inc"|"dec"` on a variable; updates must not move in the opposite direction.
+- **S6 Guard Completeness** also reports `S6_DEAD_GUARD`: a guarded branch no reachable
+  variable value can satisfy is a branch that can never fire. The test runs over the
+  values the model can produce — each variable's `init` plus every `set` constant — not
+  over the declared domain, so a guard on a value the model never writes is satisfiable on
+  paper and dead in practice.
+- **S8 Variable Declarations**: declare `monotonic: "inc"|"dec"` on a variable; updates must not move in the opposite direction. The same check reads the declared range: `S8_DOMAIN_NOT_ENFORCED` reports an `inc`/`dec` no guard keeps inside `min`/`max`, and `S8_DOMAIN_SET_OUTSIDE` (error) reports a `set` constant outside it.
 - **A9 Leads-To**: `{ kind: "leads-to", from, to }` — every path from `from` must eventually reach `to`. `to` is one state id or a non-empty array of state ids for "reach any one of these"; a duplicated member is a validation error rather than a shorthand. Either way the property stays universal: one branch that loops forever, or that stops before every target, refutes it.
 - **A10 Sequence**: `{ kind: "sequence", events }` — events must appear in order.
 - **A11 Atomicity**: `{ kind: "atomicity", events, commit, rollback? }` — once an atomic event starts, the machine must reach commit/rollback before leaving the atomic scope or terminating.
@@ -408,7 +424,8 @@ List events that must be idempotent in `idempotentEvents`. For every reachable s
 
 ## Limits
 
-- State-space exploration caps at `maxStates` (default 10000); larger guards/domains may report truncation instead of a false pass.
+- Each breadth-first exploration caps at `maxStates` (default 10000). The leads-to walk caps at twenty times that, **shared across every start state of one check**: it is depth-first over run states, and an unbounded counter makes every one of them distinct, so it has no shorter bound available.
+- A cap that bites is **reported, never silently passed**. The report sets `summary.truncated`, and the check that stopped carries a finding whose code ends in `_UNDECIDED` — `S7_UNDECIDED`, `A7_UNDECIDED`, `A9_LEADS_TO_UNDECIDED`, `D2_UNDECIDED`. An undecided check has proven neither the violation nor its absence; read it as "not decided", never as a pass.
 - A3 samples the first `maxPermutationEvents` events (default 5).
 - The engine is a finite-state model checker. It cannot prove properties of the real implementation; follow with code-level review.
 - `cost` values are modeler-provided static labels — A12 verifies against them; real execution time/WCET needs binary-level timing analysis.

package/skills/logicprobe-concurrency/SKILL.md

@@ -42,3 +42,4 @@ The full routing table, including hard-real-time, hybrid-control and execution-c
 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