@bpmn-ld/bpmn-ld 0.0.0-stage → 0.1.0

package/shapes/core.shapes.ttl

@@ -0,0 +1,398 @@
+@prefix bpmn: <https://bpmn-ld.example.org/ns#> .
+@prefix bpmndi: <https://bpmn-ld.example.org/di#> .
+@prefix shapes: <https://bpmn-ld.example.org/ns/shapes#> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+
+shapes:StartEventShape a sh:NodeShape ;
+    sh:targetClass bpmn:StartEvent ;
+    sh:property shapes:StartEventNoIncomingSequenceFlow .
+
+shapes:StartEventNoIncomingSequenceFlow a sh:PropertyShape ;
+    sh:path [ sh:inversePath bpmn:targetRef ] ;
+    sh:node [ sh:not [ sh:class bpmn:SequenceFlow ] ] ;
+    sh:message "A start event must not have an incoming sequence flow." .
+
+shapes:EndEventShape a sh:NodeShape ;
+    sh:targetClass bpmn:EndEvent ;
+    sh:property shapes:EndEventNoOutgoingSequenceFlow .
+
+shapes:EndEventNoOutgoingSequenceFlow a sh:PropertyShape ;
+    sh:path [ sh:inversePath bpmn:sourceRef ] ;
+    sh:node [ sh:not [ sh:class bpmn:SequenceFlow ] ] ;
+    sh:message "An end event must not have an outgoing sequence flow." .
+
+shapes:SequenceFlowEndpointsShape a sh:NodeShape ;
+    sh:targetClass bpmn:SequenceFlow ;
+    sh:property shapes:SequenceFlowExactlyOneSourceRef, shapes:SequenceFlowExactlyOneTargetRef .
+
+shapes:SequenceFlowExactlyOneSourceRef a sh:PropertyShape ;
+    sh:path bpmn:sourceRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "A sequence flow must have exactly one sourceRef." .
+
+shapes:SequenceFlowExactlyOneTargetRef a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "A sequence flow must have exactly one targetRef." .
+
+shapes:SequenceFlowNodesShape a sh:NodeShape ;
+    sh:targetClass bpmn:SequenceFlow ;
+    sh:property shapes:SequenceFlowSourceIsFlowNode, shapes:SequenceFlowTargetIsFlowNode .
+
+shapes:SequenceFlowSourceIsFlowNode a sh:PropertyShape ;
+    sh:path bpmn:sourceRef ;
+    sh:class bpmn:FlowNode ;
+    sh:message "The source of a sequence flow must be a flow node." .
+
+shapes:SequenceFlowTargetIsFlowNode a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:class bpmn:FlowNode ;
+    sh:message "The target of a sequence flow must be a flow node." .
+
+shapes:MessageFlowEndpointsShape a sh:NodeShape ;
+    sh:targetClass bpmn:MessageFlow ;
+    sh:property shapes:MessageFlowExactlyOneSourceRef, shapes:MessageFlowExactlyOneTargetRef .
+
+shapes:MessageFlowExactlyOneSourceRef a sh:PropertyShape ;
+    sh:path bpmn:sourceRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "A message flow must have exactly one sourceRef." .
+
+shapes:MessageFlowExactlyOneTargetRef a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "A message flow must have exactly one targetRef." .
+
+shapes:MessageRefShape a sh:NodeShape ;
+    sh:targetClass bpmn:MessageFlow, bpmn:MessageEventDefinition, bpmn:SendTask, bpmn:ReceiveTask ;
+    sh:property shapes:MessageRefIsMessage, shapes:MessageRefAtMostOne .
+
+shapes:MessageRefIsMessage a sh:PropertyShape ;
+    sh:path bpmn:messageRef ;
+    sh:class bpmn:Message ;
+    sh:message "A message reference must name a message defined in the document." .
+
+shapes:MessageRefAtMostOne a sh:PropertyShape ;
+    sh:path bpmn:messageRef ;
+    sh:maxCount 1 ;
+    sh:message "A message flow, message event definition, send task or receive task must reference at most one message." .
+
+shapes:SignalRefShape a sh:NodeShape ;
+    sh:targetClass bpmn:SignalEventDefinition ;
+    sh:property shapes:SignalRefIsSignal, shapes:SignalRefAtMostOne .
+
+shapes:SignalRefIsSignal a sh:PropertyShape ;
+    sh:path bpmn:signalRef ;
+    sh:class bpmn:Signal ;
+    sh:message "A signal reference must name a signal defined in the document." .
+
+shapes:SignalRefAtMostOne a sh:PropertyShape ;
+    sh:path bpmn:signalRef ;
+    sh:maxCount 1 ;
+    sh:message "A signal event definition must reference at most one signal." .
+
+shapes:ErrorRefShape a sh:NodeShape ;
+    sh:targetClass bpmn:ErrorEventDefinition ;
+    sh:property shapes:ErrorRefIsError, shapes:ErrorRefAtMostOne .
+
+shapes:ErrorRefIsError a sh:PropertyShape ;
+    sh:path bpmn:errorRef ;
+    sh:class bpmn:Error ;
+    sh:message "An error reference must name an error defined in the document." .
+
+shapes:ErrorRefAtMostOne a sh:PropertyShape ;
+    sh:path bpmn:errorRef ;
+    sh:maxCount 1 ;
+    sh:message "An error event definition must reference at most one error." .
+
+shapes:EscalationRefShape a sh:NodeShape ;
+    sh:targetClass bpmn:EscalationEventDefinition ;
+    sh:property shapes:EscalationRefIsEscalation, shapes:EscalationRefAtMostOne .
+
+shapes:EscalationRefIsEscalation a sh:PropertyShape ;
+    sh:path bpmn:escalationRef ;
+    sh:class bpmn:Escalation ;
+    sh:message "An escalation reference must name an escalation defined in the document." .
+
+shapes:EscalationRefAtMostOne a sh:PropertyShape ;
+    sh:path bpmn:escalationRef ;
+    sh:maxCount 1 ;
+    sh:message "An escalation event definition must reference at most one escalation." .
+
+shapes:ActivityRefShape a sh:NodeShape ;
+    sh:targetClass bpmn:CompensateEventDefinition ;
+    sh:property shapes:ActivityRefIsActivity, shapes:ActivityRefAtMostOne .
+
+shapes:ActivityRefIsActivity a sh:PropertyShape ;
+    sh:path bpmn:activityRef ;
+    sh:class bpmn:Activity ;
+    sh:message "An activity reference must name an activity defined in the document." .
+
+shapes:ActivityRefAtMostOne a sh:PropertyShape ;
+    sh:path bpmn:activityRef ;
+    sh:maxCount 1 ;
+    sh:message "A compensate event definition must reference at most one activity." .
+
+shapes:DefaultFlowShape a sh:NodeShape ;
+    sh:targetObjectsOf bpmn:default ;
+    sh:property shapes:DefaultFlowSourcedFromOwner, shapes:DefaultFlowHasNoCondition .
+
+shapes:DefaultFlowSourcedFromOwner a sh:PropertyShape ;
+    sh:path [ sh:inversePath bpmn:default ] ;
+    sh:equals bpmn:sourceRef ;
+    sh:message "A default flow must be an outgoing sequence flow of the node that declares it." .
+
+shapes:DefaultFlowHasNoCondition a sh:PropertyShape ;
+    sh:path bpmn:conditionExpression ;
+    sh:maxCount 0 ;
+    sh:message "A default flow must not have a condition expression." .
+
+shapes:NoDefaultFlowGatewayShape a sh:NodeShape ;
+    sh:targetClass bpmn:ParallelGateway, bpmn:EventBasedGateway ;
+    sh:property shapes:NoDefaultFlowOnGateway .
+
+shapes:NoDefaultFlowOnGateway a sh:PropertyShape ;
+    sh:path bpmn:default ;
+    sh:maxCount 0 ;
+    sh:message "A parallel or event-based gateway must not have a default flow." .
+
+shapes:BoundaryEventShape a sh:NodeShape ;
+    sh:targetClass bpmn:BoundaryEvent ;
+    sh:property shapes:BoundaryEventExactlyOneAttachedToRef .
+
+shapes:BoundaryEventExactlyOneAttachedToRef a sh:PropertyShape ;
+    sh:path bpmn:attachedToRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "A boundary event must be attached to exactly one activity." .
+
+shapes:SequenceFlowEventSubProcessShape a sh:NodeShape ;
+    sh:targetClass bpmn:SequenceFlow ;
+    sh:property shapes:SequenceFlowSourceNotEventSubProcess, shapes:SequenceFlowTargetNotEventSubProcess .
+
+shapes:SequenceFlowSourceNotEventSubProcess a sh:PropertyShape ;
+    sh:path bpmn:sourceRef ;
+    sh:node shapes:NotEventSubProcess ;
+    sh:message "An event sub-process must not have an outgoing sequence flow." .
+
+shapes:SequenceFlowTargetNotEventSubProcess a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:node shapes:NotEventSubProcess ;
+    sh:message "An event sub-process must not have an incoming sequence flow." .
+
+shapes:NotEventSubProcess a sh:NodeShape ;
+    sh:not [ sh:property [ sh:path bpmn:triggeredByEvent ; sh:hasValue true ] ] .
+
+shapes:ConditionalEventDefinitionShape a sh:NodeShape ;
+    sh:targetClass bpmn:ConditionalEventDefinition ;
+    sh:property shapes:ConditionalEventDefinitionAtMostOneCondition .
+
+shapes:ConditionalEventDefinitionAtMostOneCondition a sh:PropertyShape ;
+    sh:path bpmn:condition ;
+    sh:maxCount 1 ;
+    sh:message "A conditional event definition must have at most one condition." .
+
+shapes:ComplexGatewayShape a sh:NodeShape ;
+    sh:targetClass bpmn:ComplexGateway ;
+    sh:property shapes:ComplexGatewayAtMostOneActivationCondition .
+
+shapes:ComplexGatewayAtMostOneActivationCondition a sh:PropertyShape ;
+    sh:path bpmn:activationCondition ;
+    sh:maxCount 1 ;
+    sh:message "A complex gateway must have at most one activation condition." .
+
+shapes:FormalExpressionShape a sh:NodeShape ;
+    sh:targetClass bpmn:FormalExpression ;
+    sh:property shapes:FormalExpressionAtMostOneEvaluatesToTypeRef .
+
+shapes:FormalExpressionAtMostOneEvaluatesToTypeRef a sh:PropertyShape ;
+    sh:path bpmn:evaluatesToTypeRef ;
+    sh:maxCount 1 ;
+    sh:message "A formal expression must have at most one evaluatesToTypeRef." .
+
+shapes:ExpressionShape a sh:NodeShape ;
+    sh:targetClass bpmn:Expression ;
+    sh:property shapes:ExpressionHasBody .
+
+shapes:ExpressionHasBody a sh:PropertyShape ;
+    sh:path bpmn:body ;
+    sh:minCount 1 ;
+    sh:message "An expression must have a body." .
+
+shapes:DataAssociationTargetShape a sh:NodeShape ;
+    sh:targetClass bpmn:DataInputAssociation, bpmn:DataOutputAssociation ;
+    sh:property shapes:DataAssociationExactlyOneTargetRef, shapes:DataAssociationTargetIsItemAware, shapes:DataAssociationSourceIsItemAware .
+
+shapes:DataAssociationExactlyOneTargetRef a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "A data association must have exactly one targetRef." .
+
+shapes:DataAssociationTargetIsItemAware a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:class bpmn:ItemAwareElement ;
+    sh:message "The target of a data association must be an item-aware element." .
+
+shapes:DataAssociationSourceIsItemAware a sh:PropertyShape ;
+    sh:path bpmn:sourceRef ;
+    sh:class bpmn:ItemAwareElement ;
+    sh:message "The sources of a data association must be item-aware elements." .
+
+shapes:AssignmentShape a sh:NodeShape ;
+    sh:targetClass bpmn:Assignment ;
+    sh:property shapes:AssignmentExactlyOneFrom, shapes:AssignmentExactlyOneTo .
+
+shapes:AssignmentExactlyOneFrom a sh:PropertyShape ;
+    sh:path bpmn:from ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "An assignment must have exactly one from expression." .
+
+shapes:AssignmentExactlyOneTo a sh:PropertyShape ;
+    sh:path bpmn:to ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "An assignment must have exactly one to expression." .
+
+shapes:IoSpecificationShape a sh:NodeShape ;
+    sh:targetClass bpmn:InputOutputSpecification ;
+    sh:property shapes:IoSpecificationHasInputSet, shapes:IoSpecificationHasOutputSet .
+
+shapes:IoSpecificationHasInputSet a sh:PropertyShape ;
+    sh:path bpmn:inputSets ;
+    sh:minCount 1 ;
+    sh:message "An input output specification must have at least one input set." .
+
+shapes:IoSpecificationHasOutputSet a sh:PropertyShape ;
+    sh:path bpmn:outputSets ;
+    sh:minCount 1 ;
+    sh:message "An input output specification must have at least one output set." .
+
+shapes:DataObjectReferenceShape a sh:NodeShape ;
+    sh:targetClass bpmn:DataObjectReference ;
+    sh:property shapes:DataObjectReferenceAtMostOneDataObjectRef .
+
+shapes:DataObjectReferenceAtMostOneDataObjectRef a sh:PropertyShape ;
+    sh:path bpmn:dataObjectRef ;
+    sh:maxCount 1 ;
+    sh:message "A data object reference must refer to at most one data object." .
+
+shapes:DataStoreReferenceShape a sh:NodeShape ;
+    sh:targetClass bpmn:DataStoreReference ;
+    sh:property shapes:DataStoreReferenceAtMostOneDataStoreRef .
+
+shapes:DataStoreReferenceAtMostOneDataStoreRef a sh:PropertyShape ;
+    sh:path bpmn:dataStoreRef ;
+    sh:maxCount 1 ;
+    sh:message "A data store reference must refer to at most one data store." .
+
+shapes:AssociationEndpointsShape a sh:NodeShape ;
+    sh:targetClass bpmn:Association ;
+    sh:property shapes:AssociationExactlyOneSourceRef, shapes:AssociationExactlyOneTargetRef .
+
+shapes:AssociationExactlyOneSourceRef a sh:PropertyShape ;
+    sh:path bpmn:sourceRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "An association must have exactly one sourceRef." .
+
+shapes:AssociationExactlyOneTargetRef a sh:PropertyShape ;
+    sh:path bpmn:targetRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+    sh:message "An association must have exactly one targetRef." .
+
+shapes:ActivityQuantitiesShape a sh:NodeShape ;
+    sh:targetClass bpmn:Activity ;
+    sh:property shapes:ActivityStartQuantity, shapes:ActivityCompletionQuantity .
+
+shapes:ActivityStartQuantity a sh:PropertyShape ;
+    sh:path bpmn:startQuantity ;
+    sh:maxCount 1 ;
+    sh:minInclusive 0 ;
+    sh:message "The start quantity of an activity must be a single non-negative integer." .
+
+shapes:ActivityCompletionQuantity a sh:PropertyShape ;
+    sh:path bpmn:completionQuantity ;
+    sh:maxCount 1 ;
+    sh:minInclusive 0 ;
+    sh:message "The completion quantity of an activity must be a single non-negative integer." .
+
+shapes:LinkEventDefinitionReferenceShape a sh:NodeShape ;
+    sh:targetClass bpmn:LinkEventDefinition ;
+    sh:property shapes:LinkEventDefinitionSourceIsLinkEventDefinition, shapes:LinkEventDefinitionTargetIsLinkEventDefinition, shapes:LinkEventDefinitionAtMostOneTarget .
+
+shapes:LinkEventDefinitionSourceIsLinkEventDefinition a sh:PropertyShape ;
+    sh:path bpmn:source ;
+    sh:class bpmn:LinkEventDefinition ;
+    sh:message "A link source must be a link event definition defined in the document." .
+
+shapes:LinkEventDefinitionTargetIsLinkEventDefinition a sh:PropertyShape ;
+    sh:path bpmn:target ;
+    sh:class bpmn:LinkEventDefinition ;
+    sh:message "A link target must be a link event definition defined in the document." .
+
+shapes:LinkEventDefinitionAtMostOneTarget a sh:PropertyShape ;
+    sh:path bpmn:target ;
+    sh:maxCount 1 ;
+    sh:message "A link event definition must have at most one target." .
+
+shapes:LaneSingleValuesShape a sh:NodeShape ;
+    sh:targetClass bpmn:Lane ;
+    sh:property shapes:LaneAtMostOnePartitionElement, shapes:LaneAtMostOnePartitionElementRef .
+
+shapes:LaneAtMostOnePartitionElement a sh:PropertyShape ;
+    sh:path bpmn:partitionElement ;
+    sh:maxCount 1 ;
+    sh:message "A lane must have at most one partitionElement." .
+
+shapes:LaneAtMostOnePartitionElementRef a sh:PropertyShape ;
+    sh:path bpmn:partitionElementRef ;
+    sh:maxCount 1 ;
+    sh:message "A lane must have at most one partitionElementRef." .
+
+shapes:SequenceFlowAtMostOneIsImmediateShape a sh:NodeShape ;
+    sh:targetClass bpmn:SequenceFlow ;
+    sh:property shapes:SequenceFlowAtMostOneIsImmediate .
+
+shapes:SequenceFlowAtMostOneIsImmediate a sh:PropertyShape ;
+    sh:path bpmn:isImmediate ;
+    sh:maxCount 1 ;
+    sh:message "A sequence flow must have at most one isImmediate value." .
+
+shapes:DiagramSingleValuesShape a sh:NodeShape ;
+    sh:targetClass bpmndi:BPMNDiagram ;
+    sh:property shapes:DiagramAtMostOneName, shapes:DiagramAtMostOneResolution .
+
+shapes:DiagramAtMostOneName a sh:PropertyShape ;
+    sh:path bpmn:name ;
+    sh:maxCount 1 ;
+    sh:message "A diagram must have at most one name." .
+
+shapes:DiagramAtMostOneResolution a sh:PropertyShape ;
+    sh:path bpmndi:resolution ;
+    sh:maxCount 1 ;
+    sh:message "A diagram must have at most one resolution." .
+
+shapes:EdgeAtMostOneMessageVisibleKindShape a sh:NodeShape ;
+    sh:targetClass bpmndi:BPMNEdge ;
+    sh:property shapes:EdgeAtMostOneMessageVisibleKind .
+
+shapes:EdgeAtMostOneMessageVisibleKind a sh:PropertyShape ;
+    sh:path bpmndi:messageVisibleKind ;
+    sh:maxCount 1 ;
+    sh:message "An edge must have at most one messageVisibleKind." .
+
+shapes:EventDefinitionRefShape a sh:NodeShape ;
+    sh:targetClass bpmn:CatchEvent, bpmn:ThrowEvent ;
+    sh:property shapes:EventDefinitionRefIsEventDefinition .
+
+shapes:EventDefinitionRefIsEventDefinition a sh:PropertyShape ;
+    sh:path bpmn:eventDefinitionRef ;
+    sh:class bpmn:EventDefinition ;
+    sh:message "An event definition reference must name an event definition defined in the document." .

package/skills/bpmn-ld/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: bpmn-ld
+description: Write a BPMN 2.0 process model directly as BPMN-LD JSON-LD, then check it with the repository's validation and analyzer commands and fix it for at most three rounds. Use when asked to model, draw or generate a business process as BPMN-LD.
+---
+
+# BPMN-LD authoring
+
+Write the model as a BPMN-LD JSON-LD document, check it with the commands below, fix it, and report what remains. Run every command from the repository root. Use only the commands in this file.
+
+## Files
+
+- `template.jsonld`: minimal valid document to start from.
+- `examples/positive/order-approval.jsonld`: worked example with a user task, an exclusive gateway with a default flow and a condition, a service task and two end events.
+- `references/patterns.md`: guidance for parallel branches, exclusive choices, loops, sub-processes, boundary events and multiple participants, each with a worked example in `examples/positive/` and the analyzer rules that catch common mistakes.
+- `references/rule-catalogue.md`: every analyzer rule identifier with its severity, a plain explanation, typical causes and the typical fix. Use it to explain findings.
+- `references/common-mistakes.md`: common modelling mistakes, each with why it matters, the fix in BPMN-LD and the analyzer rule that catches it. Use it to avoid or repair mistakes.
+- `references/clarification-and-refinement.md`: when to ask the user and when to state an assumption, how to report assumptions, how to apply feedback to an existing model in place, and what to report when errors remain after the cap.
+- `references/explain-and-document.md`: how to explain an existing model in plain language, produce Markdown or prose documentation from it, and convert BPMN XML first.
+- `references/modify-existing-model.md`: how to modify an existing model from BPMN-LD or BPMN XML while preserving identifiers, extensions and existing diagram data, laying out only what is missing.
+- `references/vocabulary-summary.md`: the terms you need most. The full list is `docs/reference/vocabulary.md`; conventions are in `docs/conventions/` (start with `naming-and-identifiers.md` and `nested-and-flat.md`).
+
+## Workflow: generate, check, fix
+
+1. Generate. Copy `template.jsonld` to `<work>/positive/<name>.jsonld`, where `<work>` is a scratch directory and the `positive` subfolder name is required by the validate command. Replace `/ABSOLUTE/PATH/TO/REPO` (or the output of `bpmn-ld root` in an installed package) in the first `@context` entry with the absolute path of the package or repository root, and change the `@base` IRI. Then write the process: nest every flow node and sequence flow in `flowElements`, give each element a unique `id`, and connect flows by `sourceRef` and `targetRef`.
+2. Self-review. Compare the draft against `references/common-mistakes.md` and fix what you find. The analyzer cannot detect the review-only mistakes, so a clean analyzer run is not enough.
+3. Check. Run both commands:
+
+   ```
+   npm run validate -- <work>
+   npm run analyze -- <work>/positive/<name>.jsonld --format json
+   ```
+
+4. Fix. Read the output, correct the document, and check again. This is one fix round.
+5. Stop when done, or after the cap (see below), and report.
+
+## Workflow: lay out, export, check externally
+
+After the model has zero errors, add the missing diagram, export BPMN 2.0 XML and run the external checks. One command lays out and exports; it never changes the JSON-LD file:
+
+```
+npm run export -- --layout <work>/positive/<name>.jsonld -o <work>/<name>.bpmn --json
+npm run check-xml -- <work>/<name>.bpmn --json
+```
+
+`npm run layout -- <file> -o <out.jsonld>` only writes the laid-out JSON-LD; use it only when the user wants the model with a diagram. Existing diagram content is kept; add `--force` to `export --layout` to replace it by a fresh layout.
+
+Reading export output: with `--json` and `-o`, standard output is one object `{ "warnings": [], "errors": [] }`. Exit 0 means the XML was written. Exit 2 means unusable input (see `errors`); go back to the fix step. `warnings` list constructs the XML cannot express; report them and do not block on them.
+
+Reading check-xml output: it checks the XML with three independent tools and prints one object:
+
+```json
+{ "ok": true, "checks": { "xsd": { "status": "pass", "issues": [] }, "moddle": { "status": "pass", "issues": [] }, "lint": { "status": "pass", "issues": [] } } }
+```
+
+- `xsd` is validation against the BPMN 2.0 XSD, `moddle` is import with bpmn-moddle, `lint` is bpmnlint.
+- `status` is `pass`, `fail` or `skipped` (lint is skipped when moddle cannot import). Each issue has `severity` (`error` or `warning`), `message`, optional `rule` and `location`.
+- Exit 0 means no check reported an error. Exit 1 means at least one did (`ok` is false). Exit 2 means the file could not be read.
+- bpmnlint warnings do not block: exit stays 0. Report each with its `rule` and `message`, and fix only when obviously correct.
+
+When an external check reports an error:
+
+1. Read the failing check and issue. A `lint` error such as `start-event-required` or `no-implicit-start` usually means a modelling gap; fix the JSON-LD model.
+2. An `xsd` or `moddle` error on a model that passed validate and analyze is an exporter problem, not a modelling one; report it with the issue text and the model path, and do not edit the XML by hand.
+3. After fixing the model, run validate, analyze, export and check-xml again. This counts as a fix round and the cap below applies.
+4. Never report the XML as valid while any external check has an error.
+
+Optional render step (only when the user asks for an image, SVG or picture): after `check-xml` exits 0, run `npm run render -- <work>/<name>.bpmn -o <work>/<name>.svg --json`. A render failure does not change the done criterion: the model is still valid. Report the SVG path. The final report lists the SVG path.
+
+## Reading validate output
+
+`npm run validate -- <work>` checks every file in `<work>/positive/` with structural validation, the JSON Schema and SHACL. It prints one line per file and exits 0 only if all files pass:
+
+```
+ok   positive/<name>.jsonld
+```
+
+```
+FAIL positive/<name>.jsonld
+     <error message>
+```
+
+Each indented line under a `FAIL` is an error to fix. Messages are:
+
+- `Safe mode validation error.`: the document uses a term or value the context does not define, for example a misspelled property or type. Compare names with the vocabulary summary.
+- `schema: ...`: the JSON Schema rejected the document shape. The message names the failing location.
+- `<node IRI> violates <shape IRI>`: a SHACL shape failed for that node. The shape name says which rule.
+- other structural messages: a reference that does not resolve, or a value of the wrong type.
+
+Every validate failure is an error. There are no warnings.
+
+## Reading analyzer output
+
+`npm run analyze -- <file> --format json` prints one JSON object and exits 0 when there are zero errors, 1 when there is at least one error, and 2 for unusable input (missing file, invalid JSON, bad arguments; the message is on stderr).
+
+```json
+{
+  "findings": [
+    { "rule": "node-dead-end", "severity": "warning", "node": "https://example.org/models/x/Task_2", "message": "flow node has no outgoing sequence flow and is not an end event" }
+  ],
+  "summary": { "errors": 0, "warnings": 1 }
+}
+```
+
+- `findings[].rule` is the rule identifier, `severity` is `error` or `warning`, `node` is the full IRI of the offending element (`@base` plus its `id`, or `null`) and `message` explains it.
+- `summary.errors` and `summary.warnings` are the counts. `summary.errors` decides whether the model is done.
+- A `structural-validity` error means the document is structurally broken; fix it with the validate output first, because the graph rules are skipped until then.
+- Explanations, causes and fixes for each rule are in `references/rule-catalogue.md`; examples are in `docs/conventions/process-analysis.md`.
+
+## Done criterion and cap
+
+- Done means zero errors: `npm run validate` prints `ok` for the file and `summary.errors` is 0.
+- Warnings do not block. Report each warning with its rule, the element and a plain explanation of why it was left, or fix it if the fix is obviously correct and does not change the intended process.
+- With zero errors, lay out and export, then run the external checks. The work is only fully done when `check-xml` exits 0.
+- Fix at most three rounds. After the third fix round, run all commands one last time and stop, even if errors remain.
+- Final report: the path of the model, the result of validate, analyze and check-xml, the path of the exported `.bpmn` file, the optional SVG path when rendered, the number of fix rounds used, every warning with its explanation, and any remaining errors with their rule or message and what you think causes them. Do not claim the model is valid while errors remain.
+
+## Clarification and refinement
+
+Details and examples are in `references/clarification-and-refinement.md`.
+
+- Ask the user only when the answer changes the shape of the process and cannot be inferred; otherwise state an assumption and continue.
+- Report every assumption in the final report, naming elements by `id`.
+- Apply user feedback by editing the existing model in place and keeping its `id` values; do not regenerate it. Re-run both commands afterwards.
+- Never present a model with errors as finished. After the third fix round, report what remains.
+
+## Explain and document an existing model
+
+Details are in `references/explain-and-document.md`.
+
+- Given BPMN XML, convert it first: `npm run convert -- <work>/<name>.bpmn -o <work>/positive/<name>.jsonld`, then explain the converted file.
+- Explain in plain language, walking the steps in order and covering every gateway and end event.
+- Mention every named element by its exact name.
+- For documentation, write Markdown with a summary, steps, decisions, outcomes and notes. Do not change the model.
+- If the model shows the mistakes in `references/common-mistakes.md`, mention them to the user; do not silently restructure it.
+
+## Modify an existing model
+
+Details are in `references/modify-existing-model.md`.
+
+- Given BPMN XML, convert it first: `npm run convert -- <work>/<name>.bpmn -o <work>/positive/<name>.jsonld`, then edit the converted file in place.
+- Make only the requested change. Preserve identifiers, extensions and existing diagram data (shape bounds and edge waypoints); do not regenerate the model.
+- Lay out only what is missing with `npm run export -- --layout` or `npm run layout`; never use `--force` unless the user asks for the layout to be redone.
+- Re-run validate, analyze, export and check-xml as in the generate workflow, and report which elements changed.
+- If the model shows the mistakes in `references/common-mistakes.md`, mention them to the user and change only what was asked; do not silently restructure it.
+
+## Presenting remaining warnings
+
+For each warning left after the last round, look up its rule in `references/rule-catalogue.md` and tell the user:
+
+- what it means, in plain language, naming the element by its `id`;
+- why it may be acceptable here, for example a deliberately terminal branch, implicit completion or an endless process, or say that it is not acceptable when nothing justifies it;
+- the suggested fix, so the user can ask for it to be applied.
+
+Group warnings by rule when several elements share one. Never present a warning as an error or hide it, and explain remaining errors the same way, with the cause and the fix.