Guide / Checking
Every rule
One page for each check Penstock makes: why it matters and how to fix it.
How to read a rule page
Every check Penstock makes has a page. It says why it matters, how to fix it, and where you see it. Select a finding in the Problems tab and its link opens the page. In penstock check --format json, SARIF and GitHub annotations, every finding carries the rule id and the address of its page.
| Level | Meaning |
|---|---|
| Error | The diagram or the process is wrong. penstock check fails on it. |
| Advice | It works, and reads or runs better without it. It is shown as a note and does not fail the check. |
| Off by default | The rule exists but does nothing until you turn it on. |
185 rules in 12 groups: modelling rules, engine compatibility, flowable and activiti, drawing, process flow, decision tables, forms, diagrams and code, connections, ai agents, cmmn case models, modelling conventions. The groups process flow, decision tables, diagrams and code, and modelling conventions are part of Pro. The rest is free, except that comparing two environments in the connections group is Pro.
Modelling rules
The bpmnlint rules that run on every BPMN diagram, in the editor and in penstock check. Which ones run, and how strictly, is set in .bpmnlintrc.
| Rule | What | Level |
|---|---|---|
bpmnlint/ad-hoc-sub-process | Ad-hoc sub-process with a start or end event | Error |
bpmnlint/conditional-event | Conditional event without a condition | Off by default |
bpmnlint/conditional-flows | Conditional flow without a condition | Error |
bpmnlint/end-event-required | Process or sub-process without an end event | Error |
bpmnlint/event-based-gateway | Event-based gateway used wrongly | Error |
bpmnlint/event-sub-process-typed-start-event | Event sub-process start without an event | Error |
bpmnlint/fake-join | Several flows enter a task that does not join them | Advice |
bpmnlint/global | Global element without a name, unused or not unique | Advice |
bpmnlint/label-required | Element without a label | Error |
bpmnlint/link-event | Link event without a name or without its counterpart | Error |
bpmnlint/no-bpmndi | Element without a place in the diagram | Error |
bpmnlint/no-complex-gateway | Complex gateway | Error |
bpmnlint/no-disconnected | Element with no incoming or outgoing flow | Error |
bpmnlint/no-duplicate-sequence-flows | Two identical flows between the same elements | Error |
bpmnlint/no-gateway-join-fork | Gateway that joins and forks | Error |
bpmnlint/no-implicit-end | Path that ends without an end event | Error |
bpmnlint/no-implicit-split | Task that forks the flow without a gateway | Error |
bpmnlint/no-implicit-start | Path that starts without a start event | Error |
bpmnlint/no-inclusive-gateway | Inclusive gateway | Advice |
bpmnlint/no-overlapping-elements | Element overlaps another or leaves its parent | Advice |
bpmnlint/single-blank-start-event | More than one blank start event | Error |
bpmnlint/single-event-definition | Event with several event definitions | Error |
bpmnlint/standard-size | Element not in its standard size | Off by default |
bpmnlint/start-event-required | Process or sub-process without a start event | Error |
bpmnlint/sub-process-blank-start-event | Sub-process start event with a type | Error |
bpmnlint/superfluous-gateway | Gateway with one way in and one way out | Advice |
bpmnlint/superfluous-label | Label on a flow that needs none | Advice |
bpmnlint/superfluous-termination | Terminate end event that terminates nothing | Advice |
Engine compatibility
What the engine the diagram is written for cannot run: a missing job type, an element or an expression the chosen version does not support. They run on Camunda 7 and Camunda 8 diagrams, in the editor and in penstock check, against the version in the file's modeler:executionPlatformVersion, or the newest one without it. Operaton and CIB seven are checked as Camunda 7. A finding is called compat/<rule> here and in penstock check; a rule is turned off in .bpmnlintrc as camunda-compat/<rule> or, the same, compat/<rule>.
| Rule | What | Level |
|---|---|---|
compat/ad-hoc-sub-process | Ad-hoc sub-process without an activity | Error |
compat/agent-fromai-contract | fromAi() key that is not a plain name under toolCall | Error |
compat/agent-tool-documentation | Tool of an AI agent without documentation | Advice |
compat/agent-tool-output-key | Tool of an AI agent that returns nothing to it | Advice |
compat/before-all-execution-listener | beforeAll listener outside a multi-instance element | Error |
compat/element-type | Element the engine version cannot run | Error |
compat/cancel-execution-listener | cancel listener on an element that cannot be cancelled | Error |
compat/called-element | Call activity without a process to call | Error |
compat/collapsed-subprocess | Collapsed sub-process | Error |
compat/connector-properties | Connector with a property this version does not have | Advice |
compat/duplicate-execution-listener-headers | Two headers of a listener with the same key | Error |
compat/duplicate-execution-listeners | Two execution listeners that are the same | Error |
compat/duplicate-task-headers | Two task headers with the same key | Error |
compat/error-reference | Error event without an error or an error code | Error |
compat/escalation-boundary-event-attached-to-ref | Escalation boundary event on the wrong element | Error |
compat/escalation-reference | Escalation event without an escalation or a code | Error |
compat/event-based-gateway-target | Receive task after an event-based gateway | Error |
compat/executable-process | No executable process | Error |
compat/execution-listener | Execution listener without an event type or a job type | Error |
compat/feel-compatibility | FEEL function the engine version does not have | Error |
compat/feel | FEEL expression that is not valid | Error |
compat/history-time-to-live | Process without a history time to live | Advice |
compat/implementation | Task or event that has nothing to run | Error |
compat/inclusive-gateway | Inclusive gateway with more than one way in | Error |
compat/link-event | Link events that do not match | Error |
compat/loop-characteristics | Multi-instance without what it needs | Error |
compat/io-mapping | Input or output mapping that is incomplete | Error |
compat/message-reference | Message event without a message or its name | Error |
compat/no-binding-type | Binding type that this version does not have | Error |
compat/no-business-id | Business id that this version does not have | Error |
compat/no-before-all-execution-listener | beforeAll listener that this version does not have | Error |
compat/no-candidate-users | Candidate users that this version does not have | Error |
compat/no-cancel-execution-listener | cancel listener that this version does not have | Error |
compat/no-execution-listener-headers | Listener headers that this version does not have | Error |
compat/no-execution-listeners | Execution listeners that this version does not have | Error |
compat/no-expression | Expression this version does not support | Error |
compat/no-interrupting-event-subprocess | Interrupting event sub-process in an ad-hoc sub-process | Error |
compat/no-job-priority-definition | Job priority that this version does not have | Error |
compat/no-loop | Loop that never waits | Error |
compat/no-multiple-none-start-events | More than one blank start event in Camunda 8 | Error |
compat/no-priority-definition | Priority that this version does not have | Error |
compat/no-propagate-all-parent-variables | Propagate all parent variables that this version does not have | Error |
compat/no-signal-event-sub-process | Signal event sub-process that this version does not have | Error |
compat/no-task-schedule | Task schedule that this version does not have | Error |
compat/no-task-listeners | Task listeners that this version does not have | Error |
compat/no-template | Element template that this version does not have | Error |
compat/no-version-tag | Version tag that this version does not have | Error |
compat/no-zeebe-properties | Zeebe properties that this version does not have | Error |
compat/no-zeebe-user-task | Camunda user task that this version does not have | Error |
compat/priority-definition | User task priority that is not valid | Error |
compat/zeebe-user-task | Job worker user task | Advice |
compat/secrets | Secret written in a form the engine no longer reads | Advice |
compat/sequence-flow-condition | Condition on a flow that cannot have one | Error |
compat/signal-reference | Signal event without a signal or its name | Error |
compat/start-event-form | Start event form that this version cannot show | Error |
compat/start-event-form-embedded | Embedded form on a start event | Advice |
compat/subscription | Message without a correlation key | Error |
compat/task-listener | Task listener without an event type or a job type | Error |
compat/task-schedule | Task schedule that is not a date | Error |
compat/timer | Timer that is not valid | Error |
compat/timer-past-date | Start timer set in the past | Advice |
compat/unresolvable-secret-reference | Secret used in a way the engine cannot resolve | Error |
compat/user-task-definition | User task without a form | Advice |
compat/user-task-form | User task form that is not filled in | Error |
compat/variable-name | Variable name that is not valid | Error |
compat/version-tag | Version tag that is empty | Error |
compat/wait-for-completion | Compensation that does not wait | Error |
Flowable and Activiti
What a Flowable or an Activiti engine ignores or cannot run: an extension of another engine, an attribute the engine does not know, an element it does not support. They run on diagrams of the Flowable and Activiti profiles, in the editor and in penstock check. A finding is called engine/<rule>.
| Rule | What | Level |
|---|---|---|
engine/foreign-extension | Extension of another engine | Error |
engine/unknown-attribute | Attribute the engine does not know | Advice |
engine/attribute-not-allowed | Attribute on the wrong kind of element | Advice |
engine/unsupported-element | Element the engine does not support | Error |
engine/service-task-implementation | Service task with nothing to run | Error |
engine/script-format | Script task without a script format | Error |
engine/feel-expression | FEEL expression in a Flowable or Activiti diagram | Error |
Drawing
What is wrong with how a diagram is drawn, found by the check card in the editor and by the first section of penstock check. The errors break the picture; the others make it harder to read.
| Rule | What | Level |
|---|---|---|
drawing/dangling-connection | Connection without both ends | Error |
drawing/lost-connection | Connection in the file but not on the canvas | Error |
drawing/containment | Element outside the container it belongs to | Error |
drawing/overlap | Shapes sit on top of each other | Error |
drawing/edge-through-node | Connection runs through a shape | Error |
drawing/edge-through-boundary | Connection runs through a boundary event | Error |
drawing/crossing | Connections cross | Advice |
drawing/detached-edge | Connection does not reach the shape it connects | Error |
drawing/boundary-off-host | Boundary event is off its host | Error |
drawing/label-adrift | Label sits far from what it names | Advice |
drawing/diagonal-edge | Connection is not drawn at right angles | Advice |
drawing/label-overlap | Labels cover each other | Error |
drawing/merged-edge | Connections run along the same line | Advice |
drawing/note-adrift | Annotation sits far from what it describes | Advice |
drawing/semantic-drift | The diagram means something different | Error |
drawing/backtrack | Connection doubles back along itself | Error |
drawing/edge-through-label | Connection crosses a label | Advice |
drawing/edge-along-shape | Connection runs along the border of a shape | Advice |
drawing/detour | Connection takes a long way round | Advice |
drawing/jog | Connection sidesteps for no reason | Advice |
Process flow
What the way a process is wired can do when it runs. Part of Penstock Pro, and Team in a pipeline.
| Rule | What | Level |
|---|---|---|
flow/deadlock | The process can get stuck | Error |
flow/no-synchronization | A part of the process can run twice | Error |
flow/dead-element | An element can never run | Error |
flow/never-finishes | The process may never finish | Error |
flow/too-complex | Only part of the process was analysed | Advice |
flow/no-way-out | A decision has no way out for some values | Error |
flow/overlap | Two ways out of a decision can both hold | Error |
flow/no-default | A decision may have no way out | Advice |
flow/lookalike | Two variables look like one | Advice |
Decision tables
What a DMN decision table does with the inputs it can be given. Part of Penstock Pro, and Team in a pipeline.
| Rule | What | Level |
|---|---|---|
table/rule-overlap | Two rules match the same input | Error |
table/rule-gap | No rule matches some input | Advice |
table/table-unread | A decision table could not be checked | Advice |
Forms
What a Camunda Form does with what the user enters. The form check is lint, so it is free.
| Rule | What | Level |
|---|---|---|
form/key-clash | Two fields write the same variable | Error |
form/no-key | A field writes no variable | Error |
form/repeated-option | An option list repeats a value | Error |
form/no-label | A field has no label | Advice |
Diagrams and code
Where a diagram and the code that runs it disagree: a step nothing implements, a worker no diagram uses, a variable read under another name than it is set.
| Rule | What | Level |
|---|---|---|
code/missing-implementation | Nothing in the code runs a step | Advice |
code/never-thrown | Nothing in the code throws the error a step catches | Advice |
code/variable-typo | A variable is read, but only a similar one is set | Advice |
code/worker-fetch | A worker reads a variable it does not fetch | Advice |
code/writer-unread | A worker sets a variable no step after it reads | Advice |
code/lost-update | Every parallel instance writes the same result collection | Advice |
code/late-read | A worker reads a variable no step before it sets | Advice |
code/near-name | A job type, topic, bean, message or error code is one letter off the code | Advice |
code/mapping-order | A mapping line reads a value an earlier line was meant to set | Advice |
code/implicit-job-type | A job worker takes its job type from the method name | Advice |
code/no-worker | No worker handles a job type | Error |
code/no-topic-worker | No external task worker subscribes to a topic | Error |
code/class-missing | A class named in the diagram is not in the project | Error |
code/bean-missing | No Spring bean has the name a diagram uses | Error |
code/unknown-process | A call activity calls a process no diagram defines | Error |
code/unknown-decision | A business rule task calls a decision no file defines | Error |
code/unknown-form | A user task shows a form no file defines | Error |
code/unknown-embedded-form | A user task shows an embedded form the diagram does not contain | Error |
code/unused-worker | A worker for a job type no diagram uses | Advice |
code/unused-subscription | A subscription to a topic no diagram uses | Advice |
code/variable-field | A step reads a field the variable does not have | Advice |
code/variable-unknown | A step reads a variable nothing sets | Advice |
Connections
The configuration around a diagram that is not in the diagram: the secrets and MCP clients it names, and the environment files, Docker Compose files, Helm values and Spring Boot properties that are meant to supply them. A finding is called connections/<rule>. Comparing two environments is part of Penstock Pro, and Team in a pipeline.
| Rule | What | Level |
|---|---|---|
connections/secret-undefined | Secret that no file of the project defines | Advice |
connections/secret-prefix | Secret that is defined without the configured prefix | Advice |
connections/mcp-client-undefined | MCP client that no configuration defines | Error |
connections/property-renamed | Property with its Camunda 8.7 name | Advice |
connections/property-removed | Property that Camunda 8.8 no longer reads | Advice |
connections/secret-missing-in-env | Secret defined in one environment and missing in another | Error |
connections/key-missing-in-env | Setting defined in one environment and missing in another | Advice |
AI agents
What is wrong with an AI agent of Camunda 8: a loop with no limit, a tool the model cannot understand, a secret written into the diagram, an MCP client nothing configures, an element template that 8.10 has replaced. They run on .bpmn files in the editor and in penstock check. A finding is called agents/<rule>. Rewriting an old agent to the 8.10 templates is penstock migrate agents, which writes with Penstock Pro.
| Rule | What | Level |
|---|---|---|
agents/no-model-call-limit | AI agent without a limit on model calls | Advice |
agents/tool-without-description | Tool of an AI agent without a description | Advice |
agents/fromai-incomplete | fromAi() parameter without a description or a type | Advice |
agents/tool-filter-matches-nothing | MCP tool filter that lets nothing through | Advice |
agents/duplicate-tool-names | Two tools of an agent with the same name | Advice |
agents/adhoc-without-agent | Tool container that no agent uses | Advice |
agents/mcp-client-no-config | MCP client of an agent that no configuration defines | Error |
agents/plain-text-secret | API key or secret written into the diagram | Error |
agents/deprecated-template | Agent on a deprecated 8.9 element template | Advice |
CMMN case models
What is wrong in a Camunda 7 or Flowable case model: a reference that points at nothing, an id used twice, a task with nothing to run. They run on .cmmn files in the viewer and in penstock check. A finding is called cmmn/<rule>.
| Rule | What | Level |
|---|---|---|
cmmn/duplicate-id | Id used twice | Error |
cmmn/definition-ref-missing | Plan item that points at no definition | Error |
cmmn/dangling-sentry-ref | Criterion that points at a sentry that is not there | Error |
cmmn/dangling-on-part | Sentry that waits for a plan item that is not there | Error |
cmmn/task-without-target | Task that names nothing to run | Advice |
cmmn/no-case-plan-model | Case without a case plan model | Error |
cmmn/plan-truncated | Plan that is shown only in part | Advice |
Modelling conventions
Conventions the editor applies while modelling, so a team does not have to remember them. They are set under conventions in penstock.yaml.
| Rule | What | Level |
|---|---|---|
convention/id-from-name | Ids follow names | Off by default |
convention/defaults | Defaults for new elements | Off by default |