camunda-cli 0.3.1 → 0.4.2

package/PANDUAN.md

@@ -0,0 +1,341 @@
+# Panduan camunda-cli
+
+Alat baris perintah untuk Camunda 7 self-hosted. Dibuat untuk dua pekerjaan yang paling
+memakan waktu saat mengembangkan BPMN: **memahami model yang sudah ter-deploy**, dan
+**mencari tahu kenapa sebuah instance macet**.
+
+Dokumen ini disusun per kasus nyata, bukan per perintah. Untuk daftar opsi lengkap tiap
+perintah, jalankan `camunda <perintah> --help`.
+
+---
+
+## Pasang dan masuk
+
+```bash
+npm install -g camunda-cli
+camunda login https://camunda.contoh.com
+```
+
+URL boleh tanpa `/engine-rest`, akan ditambahkan otomatis. Username dan password ditanyakan
+lewat prompt (jangan ditulis di baris perintah supaya tidak masuk riwayat shell).
+
+Kredensial disimpan di `~/.config/camunda-cli/config.json` dengan permission `0600`. Camunda 7
+memakai HTTP Basic Auth di setiap request dan tidak punya token sesi, jadi yang disimpan
+memang password, dan hanya dikirim ke engine yang kamu konfigurasi.
+
+Cek sambungan kapan saja:
+
+```bash
+camunda whoami
+```
+
+**Publish tidak memperbarui yang sudah terpasang.** Setelah versi baru rilis, jalankan lagi
+`npm install -g camunda-cli`, lalu pastikan dengan `camunda --version`.
+
+---
+
+## Kasus 1: memeriksa model sebelum di-deploy
+
+Ini kebiasaan yang paling menghemat waktu. Kondisi gateway, form field, dan wiring addon
+hanya ada di dalam XML BPMN, tidak ada endpoint REST-nya, jadi tanpa alat ini satu-satunya
+cara mengetahuinya adalah membaca XML mentah.
+
+```bash
+camunda lint ./proses-saya.bpmn      # file lokal, tanpa engine, tanpa login
+camunda lint Process_PengajuanCuti   # versi yang sudah ter-deploy
+```
+
+Severity dipisah dengan sengaja:
+
+- **ERROR** hanya untuk yang **terbukti rusak dari modelnya sendiri**. `camunda deploy`
+  menolak model yang punya error.
+- **WARNING** untuk risiko yang butuh penilaianmu, karena modelnya sendiri tidak cukup untuk
+  membuktikan salah atau benar.
+- **INFO** untuk catatan, disembunyikan kecuali pakai `--all`.
+
+Kalibrasi ini diuji ke 190 model produksi nyata: nol error, nol deploy terblokir, sementara
+model yang memang dibuat rusak tetap menghasilkan dua error.
+
+### Yang ditangkap sebagai ERROR
+
+| Aturan | Artinya |
+|---|---|
+| `uncovered-value` | Gateway bercabang `> N` dan `< N`, jadi nilai tepat `N` tidak ke mana-mana. Engine melempar `ENGINE-02004` dan instance berhenti. |
+| `default-flow-with-condition` | Flow yang ditandai default tapi masih punya kondisi. Engine menolak model ini saat deploy dengan `ENGINE-09005`. |
+| `variable-name-mismatch` | Form menulis satu variabel yang tidak dibaca siapa pun, sementara kondisi di hilirnya membaca variabel yang tidak ditulis siapa pun. Menyelesaikan elemen itu tidak akan pernah memenuhi kondisinya. |
+| `dangling-flow`, `dangling-boundary`, `no-start-event` | Menunjuk elemen yang tidak ada. |
+
+### Yang ditangkap sebagai WARNING
+
+`no-default-flow` (semua cabang berkondisi tanpa fallback), `unwritten-variable` (membaca
+`${x}` yang tidak ditulis siapa pun di model ini), `initiator-expression`, `no-op-service-task`
+(service task tanpa implementasi), `addon-without-config`, `unreachable`, `dead-end`,
+`ambiguous-branch`.
+
+### Melihat isi model
+
+```bash
+camunda inspect Process_PengajuanCuti
+camunda inspect ./proses-saya.bpmn
+```
+
+Menampilkan semua elemen beserta penanda async, assignee, addon yang dipanggil, jumlah form
+field, dan **berapa instance yang sedang berada di elemen itu**; lalu seluruh sequence flow
+dengan kondisinya; lalu form field per elemen; lalu daftar integrasi.
+
+---
+
+## Kasus 2: menguji proses dari awal sampai selesai
+
+```bash
+camunda start Process_PengajuanCuti --var initiator=budi@contoh.com -b UJI-1
+```
+
+Yang muncul:
+
+```
+Started Process_PengajuanCuti v3 as instance 3441986
+business key UJI-1
+
+Now waiting at:
+    3442065  Review Leave Request  budi@contoh.com
+camunda complete 3442065 --var catatan=<value>
+```
+
+`start` **tidak berhenti di "berhasil dikirim"**. HTTP 200 dari engine cuma berarti perintahnya
+diterima; apa pun yang ditandai async baru berjalan setelah respons. Jadi `start` menunggu
+sebentar lalu melaporkan salah satu dari tiga: gagal, selesai, atau sedang menunggu di task
+mana beserta perintah persis untuk menyelesaikannya.
+
+Lanjutkan dengan menyalin perintah yang disarankan:
+
+```bash
+camunda complete 3442065 --var catatan=ok
+```
+
+```
+Task 3442065 completed.
+Instance 3441986 finished in 3.6s.
+```
+
+Kalau proses masih berjalan, `complete` menampilkan task berikutnya. Jadi menggiring proses
+tiga langkah cukup tiga perintah, tanpa perlu mencari-cari sendiri.
+
+### Menemukan task lewat business key
+
+```bash
+camunda tasks -b UJI-1
+```
+
+Business key itu pegangan yang kamu tentukan sendiri saat `start`, jadi bisa dipakai langsung
+tanpa perlu tahu instance id.
+
+### Tipe variabel itu penting
+
+```bash
+--var jumlah=300              # String, dan "300" > 200 dibandingkan sebagai teks
+--var jumlah=300:Integer      # angka sungguhan
+--var aktif=true:Boolean
+--var data:='{"a":1}'         # JSON
+```
+
+Kalau gateway membandingkan secara numerik, salah tipe membuat kondisinya berperilaku aneh
+tanpa error.
+
+### Membersihkan setelah menguji
+
+```bash
+camunda cancel --key Process_PengajuanCuti          # semua instance proses itu
+camunda cancel 3441986                              # satu instance
+camunda cancel --key Process_X -y -r "bersih-bersih" # tanpa konfirmasi
+```
+
+Menguji meninggalkan banyak instance menggantung. Tanpa `-y` akan diminta konfirmasi.
+
+---
+
+## Kasus 3: instance macet atau gagal
+
+Satu perintah untuk semuanya:
+
+```bash
+camunda diagnose 3441986
+```
+
+Ini membaca lebih banyak daripada sekadar `/incident`, karena beberapa bentuk kegagalan tidak
+terlihat di sana:
+
+- Langkah yang gagal **di dalam transaksi pemanggilnya** tidak meninggalkan incident maupun
+  job sama sekali; satu-satunya jejak ada di historic job log, atau tidak ada sama sekali.
+- Incident menunjuk activity tempat job menempel, yang **sering bukan** activity yang error.
+  `diagnose` membedakan keduanya secara eksplisit.
+- Incident yang sudah teratasi hilang dari `/incident`.
+
+Contoh keluaran:
+
+```
+Stopped at
+    Activity_CekSisaKuota  transition  Check Remaining Quota
+
+1 problem(s)
+
+  open incident at 2026-08-13 08:19:33
+  failing element: Activity_TinjauPengajuan
+  job attached to:  Activity_CekSisaKuota  (the async marker sits here, the error came from
+                    the element above)
+  Unknown property used in expression: ${initiator}. Cause: Cannot resolve identifier 'initiator'
+
+  The variable "initiator" is injected by AlurKerja when a process is started through its own
+  API. Starting the same process straight through the Camunda REST API skips that...
+```
+
+Exit code-nya **1 kalau ada yang sedang rusak, 0 kalau sehat**, jadi bisa dipakai di skrip.
+
+Instance yang pernah gagal lalu pulih dilaporkan **sehat**, dengan riwayat kegagalannya
+ditampilkan terpisah sebagai konteks, bukan sebagai vonis.
+
+### Error addon yang bersarang
+
+Kegagalan addon datang sebagai pesan REST yang membungkus exception Java yang membungkus
+`body: {json}` yang field `output`-nya berisi JSON lagi. Kalimat yang benar-benar berguna ada
+di lapisan paling dalam, jadi itulah yang ditampilkan paling atas:
+
+```
+sales_name kosong. Pastikan form Submit-Weekly-Report benar-benar mengisi variabel ini
+sebelum service task ini berjalan.
+
+integration response:
+  { "details": "script exited with code 1", ... }
+
+script output:
+  { "status": "error", "message": "sales_name kosong...", ... }
+```
+
+Ini berlaku baik di `diagnose` maupun saat `complete` gagal.
+
+### Perintah pendukung
+
+```bash
+camunda trace 3441986        # setiap langkah yang dilalui, urut sesuai eksekusi engine
+camunda vars 3441986         # variabel saat ini
+camunda vars 3441986 -H      # setiap perubahan variabel beserta waktunya
+camunda jobs -i 3441986 -f   # job yang gagal
+camunda stacktrace <jobId>   # stack trace, frame internal engine disaring
+camunda incidents -k Process_X        # incident yang terbuka
+camunda incidents -k Process_X -H     # termasuk yang sudah teratasi
+camunda stats Process_X               # instance menumpuk di elemen mana
+```
+
+`trace` diurutkan memakai urutan eksekusi milik engine, bukan timestamp. Gateway dan event di
+sekitarnya sering berbagi milidetik yang sama, dan mengurutkan pakai waktu membuat urutannya
+acak.
+
+---
+
+## Kasus 4: memperbaiki instance yang gagal tanpa mengulang dari awal
+
+Ini alur sehari-hari saat mengembangkan addon: script-nya salah, instance gagal, script
+diperbaiki, lalu ingin melanjutkan instance yang sudah jalan.
+
+```bash
+camunda jobs -i 3441986 --failed          # cari job yang gagal
+camunda set-var 3441986 initiator=budi@contoh.com   # perbaiki datanya
+camunda retry 3441988 --now               # jalankan ulang job itu sekarang
+camunda diagnose 3441986                  # pastikan benar-benar pulih
+```
+
+`retry` mengembalikan jatah percobaan job supaya dijalankan lagi. Tanpa `--now`, job runner
+yang akan mengambilnya beberapa saat kemudian.
+
+Kalau yang salah adalah **kodenya** (script addon, konfigurasi listener), jangan retry job di
+instance yang sama untuk menguji perbaikannya: data yang terlanjur dihasilkan run sebelumnya
+sudah tersimpan di variabel instance itu dan tidak akan dibuat ulang. Mulai instance baru.
+Retry di tempat hanya masuk akal untuk yang sifatnya sementara (jaringan, service luar yang
+sedang mati) atau kalau yang diperbaiki memang datanya.
+
+---
+
+## Kasus 5: mesin dengan banyak tenant
+
+Di engine bersama, satu process key yang sama ada di banyak tenant. Endpoint bawaan Camunda
+menjawab *"no matching process definition ... and no tenant-id"*, yang terbaca seolah prosesnya
+tidak ada padahal ada.
+
+```bash
+camunda tenants -s Telco                 # cari id tenant dari namanya
+camunda definitions -k Contract -t <tenantId> -l
+camunda inspect Process_X -t <tenantId>
+```
+
+Kalau sebuah key ambigu, perintahnya tidak menebak, melainkan menampilkan kandidatnya:
+
+```
+"V2-Contract-Lifecycle-Management" exists in 3 tenants. Narrow it with --tenant <id>, or
+pass the full definition id:
+  V2-Contract-...:103:2794600  tenant=ef93ab58-...  version=103
+  ...
+```
+
+---
+
+## Kasus 6: deploy
+
+```bash
+camunda deploy ./proses.bpmn -t <tenantId> -n "nama deployment"
+```
+
+`deploy` menjalankan pemeriksaan yang sama dengan `lint` dan **menolak model yang punya error**.
+Pakai `--skip-lint` untuk memaksa.
+
+Kalau isinya identik dengan yang sudah ter-deploy, Camunda tidak membuat versi baru dan
+perintahnya memberi tahu hal itu, bukan diam-diam sukses.
+
+```bash
+camunda deployments               # deployment terbaru
+camunda undeploy <deploymentId>   # hapus (pakai --cascade untuk ikut instance & history)
+```
+
+---
+
+## Dipakai dari skrip atau agent AI
+
+Setiap perintah menerima `--json` untuk mengeluarkan payload API mentah:
+
+```bash
+camunda tasks -b UJI-1 --json
+camunda lint Process_X --json
+camunda diagnose 3441986 --json
+```
+
+Keluaran biasa juga sudah aman dibaca mesin: tidak ada karakter garis kotak, dan warna hanya
+muncul kalau stdout benar-benar terminal. Kolomnya dirapikan dengan spasi biasa.
+
+Exit code: `0` berhasil, `1` gagal atau ada temuan error.
+
+---
+
+## Hal-hal yang menghemat waktu
+
+**401 yang muncul acak.** Engine di belakang load balancer kadang menolak kredensial yang
+benar saat satu replika sedang tidak sehat: pernah teramati 5 kali gagal lalu 5 kali berhasil
+berturut-turut, kredensial sama, jeda setengah detik. Request diulang otomatis supaya ini
+tidak terbaca sebagai password salah. Error 4xx yang membawa pesan Camunda asli tidak pernah
+diulang, karena itu jawaban sungguhan.
+
+**`${initiator}` kosong kalau start dari CLI.** AlurKerja mengisi variabel itu saat proses
+dimulai lewat API-nya sendiri. Start langsung ke Camunda melewatkannya, jadi elemen yang
+memakai `${initiator}` (biasanya assignee) gagal begitu tercapai. Tambahkan
+`--var initiator=<userId>` saat menguji dari CLI.
+
+**Form micro-frontend menulis variabel yang tidak terlihat di model.** Field bertipe
+`EXTERNAL_MICRO_FRONTEND_FORM` namanya cuma titik pasang; MFE-nya bisa menulis variabel apa
+pun tanpa dideklarasikan di BPMN. Jadi `unwritten-variable` di proses seperti itu wajar dan
+belum tentu bug.
+
+---
+
+## Yang sengaja tidak dicakup
+
+Evaluasi DMN, operasi batch, migrasi dan modifikasi instance, serta manajemen authorization.
+Ini keputusan sadar, bukan kelalaian: cakupan perintah di sini mengikuti apa yang benar-benar
+berulang saat mengembangkan dan men-debug proses, bukan seluruh 300-an endpoint REST Camunda.

package/README.md

@@ -19,6 +19,8 @@ ERROR   variable-name-mismatch  flow Flow_0jpsuir (retry)
         expression throws "Cannot resolve identifier 'input_huruf'" the moment it is evaluated.
 ```
 
+A task-by-task guide in Indonesian is in [PANDUAN.md](PANDUAN.md).
+
 ## Install
 
 ```bash
@@ -72,21 +74,29 @@ camunda lint ./order-process.bpmn     # no engine and no login needed
 camunda lint order-process            # or the deployed version
 ```
 
-Every rule exists because that failure was reproduced against a real engine first:
+Every rule exists because that failure was reproduced against a real engine first.
+
+**Errors** are reserved for defects that are provable from the model alone, because `deploy`
+refuses to push a model that has one:
 
 | Rule | What it catches |
 |---|---|
-| `uncovered-value` | `> N` and `< N` branches that leave `== N` with nowhere to go (`ENGINE-02004`) |
-| `no-default-flow` | Every branch conditional, no default: any instance where they all fail stops dead |
-| `variable-name-mismatch` | A condition reads `foo` while the form writes `foo_2`, so the expression throws |
-| `unwritten-variable` | A direct `${x}` read where nothing sets `x`; throws instead of yielding null |
-| `initiator-expression` | `${initiator}`, which exists only when started through AlurKerja's API |
-| `no-op-service-task` | A service task with no implementation behind it |
-| `addon-without-config` | An integration call with no config bound |
-| `unreachable`, `dead-end`, `dangling-flow` | Structural mistakes |
-
-`deploy` runs the same checks and refuses to push a model with blocking issues, unless you
-pass `--skip-lint`.
+| `uncovered-value` | `> N` and `< N` branches leaving `== N` with nowhere to go (`ENGINE-02004`) |
+| `default-flow-with-condition` | A default flow that also carries a condition, which the engine rejects outright (`ENGINE-09005`) |
+| `variable-name-mismatch` | A form writing one variable nothing reads, feeding a condition reading one nothing writes |
+| `dangling-flow`, `dangling-boundary`, `no-start-event` | References to elements that do not exist |
+
+**Warnings** are risks that need a human to judge, since the model cannot prove them either
+way: `no-default-flow`, `unwritten-variable`, `initiator-expression`, `no-op-service-task`,
+`addon-without-config`, `unreachable`, `dead-end`, `ambiguous-branch`.
+
+Run over 190 production models, the checks raised zero errors and did not block a single
+deploy, while still flagging both defects in a model built to contain them. That balance is
+deliberate: a static check an agent cannot trust is worse than none, because acting on a
+confident wrong answer breaks a process that was working.
+
+`deploy` runs the same checks and refuses to push a model with an error, unless you pass
+`--skip-lint`.
 
 **Work out why an instance is stuck.** `diagnose` gathers what is scattered across several
 endpoints and unpacks it:

package/bin/camunda.js

@@ -24,7 +24,7 @@ program
       'Start with "camunda inspect <key>" to read a deployed model, and\n' +
       '"camunda diagnose <instanceId>" when an instance misbehaves.'
   )
-  .version('0.3.1')
+  .version('0.4.2')
   .option('--json', 'print the raw API payload instead of a formatted view')
   .option('--no-color', 'never emit colour, even on a terminal')
   .showHelpAfterError()
@@ -189,6 +189,7 @@ withTenant(
     .description('Open human tasks')
     .option('-a, --assignee <userId>')
     .option('-i, --instance <processInstanceId>')
+    .option('-b, --business-key <key>', 'tasks of the instance started with this business key')
     .option('-k, --key <definitionKey>')
     .option('-u, --unassigned')
     .option('--limit <n>', 'maximum rows', int)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camunda-cli",
-  "version": "0.3.1",
+  "version": "0.4.2",
   "description": "Command-line client for self-hosted Camunda 7: inspect and lint deployed BPMN models, and diagnose why an instance is stuck",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,8 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "PANDUAN.md"
   ],
   "keywords": [
     "camunda",

package/src/commands/tasks.js

@@ -10,6 +10,9 @@ export async function tasksCommand(options) {
   const query = { maxResults: options.limit ?? 50 };
   if (options.assignee) query.assignee = options.assignee;
   if (options.instance) query.processInstanceId = options.instance;
+  // The business key is the handle you chose when starting, so it is the natural way back
+  // to a task without first looking the instance id up.
+  if (options.businessKey) query.processInstanceBusinessKey = options.businessKey;
   if (options.key) query.processDefinitionKey = options.key;
   if (options.tenant) query.tenantIdIn = options.tenant;
   if (options.unassigned) query.unassigned = true;

package/src/lint.js

@@ -24,22 +24,104 @@ function levenshtein(a, b) {
   return d[m][n];
 }
 
+// Deliberately narrow. An earlier version also treated a shared prefix as evidence, which
+// made every model using a naming convention look broken: in a process where a form writes
+// gr_number, gr_date and gr_amount, reading an unrelated gr_recorded was reported as a typo
+// of gr_number. A near-identical spelling is the only similarity worth mentioning, and even
+// that is offered as a candidate rather than a conclusion.
 function similarNames(target, candidates) {
-  const prefix = target.includes('_') ? target.slice(0, target.indexOf('_') + 1) : null;
   return candidates.filter((c) => {
     if (c === target) return false;
-    if (prefix && c.startsWith(prefix)) return true;
-    return levenshtein(c.toLowerCase(), target.toLowerCase()) <= 3;
+    const a = c.toLowerCase().replace(/[_-]/g, '');
+    const b = target.toLowerCase().replace(/[_-]/g, '');
+    if (a === b) return true;
+    if (Math.min(a.length, b.length) < 4) return false;
+    return levenshtein(a, b) <= 2;
   });
 }
 
-// Reads `${x > 300}` style comparisons so a gateway's branches can be checked for gaps.
+// Evidence that a form and the expression reading it were never lined up, independent of
+// how the two names are spelled: an element whose form writes exactly one variable that
+// nothing anywhere reads, immediately followed by a flow reading a variable nothing writes.
+// Both halves are dead on their own, and they sit either side of the same element.
+// Field types whose name is a mount point rather than a variable. An embedded micro
+// frontend writes whatever it likes and the model has no way to declare that, so a form
+// containing one tells you nothing about which variables the element sets. Reasoning about
+// unwritten variables around these produced a confident, wrong error on a process that had
+// been running correctly for months.
+const OPAQUE_FIELD_TYPES = new Set([
+  'EXTERNAL_MICRO_FRONTEND_FORM',
+  'HTML_CUSTOM_FORM',
+  'VARIABLE_RENDERER',
+  'EXPRESSION_INPUT',
+]);
+
+function findStrandedFormField(model, node, byId, outgoing, readEverywhere, written) {
+  if (node.formFields.some((f) => OPAQUE_FIELD_TYPES.has(f.type))) return null;
+  const writable = node.formFields.filter((f) => !f.disabled && f.name);
+  if (writable.length !== 1) return null;
+  const field = writable[0].name;
+  if (readEverywhere.has(field)) return null;
+
+  // The conditions that act on a user task's input usually sit on the flows out of the
+  // gateway after it rather than on the task's own flow, so pass through gateways. Nothing
+  // else is followed: once a real activity intervenes, the value could have come from there.
+  const seen = new Set([node.id]);
+  const frontier = [node.id];
+  for (let depth = 0; depth < 3 && frontier.length; depth++) {
+    const next = [];
+    for (const id of frontier) {
+      for (const flow of outgoing.get(id) ?? []) {
+        if (flow.condition) {
+          const { direct } = readVariables(flow.condition);
+          const orphan = direct.find((v) => !written.has(v) && v !== 'initiator');
+          if (orphan) return { field, orphan, flow };
+        }
+        const target = byId.get(flow.target);
+        if (target && GATEWAYS.has(target.type) && !seen.has(target.id)) {
+          seen.add(target.id);
+          next.push(target.id);
+        }
+      }
+    }
+    frontier.length = 0;
+    frontier.push(...next);
+  }
+  return null;
+}
+
+// Reads `${x > 300}` and `${x == 'draft'}` style comparisons so a gateway's branches can be
+// checked for gaps. Values stay as written: a numeric gap is only meaningful between numbers.
 function parseComparison(expression) {
   const m = String(expression || '').match(
-    /\$\{\s*([A-Za-z_$][\w$]*)\s*(==|!=|>=|<=|>|<)\s*(-?\d+(?:\.\d+)?)\s*\}/
+    /^\s*\$\{\s*([A-Za-z_$][\w$]*)\s*(==|!=|>=|<=|>|<)\s*('[^']*'|"[^"]*"|-?\d+(?:\.\d+)?|true|false)\s*\}\s*$/
   );
   if (!m) return null;
-  return { variable: m[1], op: m[2], value: Number(m[3]) };
+  const raw = m[3];
+  const numeric = /^-?\d/.test(raw);
+  return {
+    variable: m[1],
+    op: m[2],
+    value: numeric ? Number(raw) : raw.replace(/^['"]|['"]$/g, ''),
+    numeric,
+  };
+}
+
+// Two branches that between them cover every value need no default flow. Recognising the
+// common complementary pairs keeps the check off models that are already exhaustive, which
+// would otherwise be a third of them.
+const COMPLEMENTARY = [
+  ['==', '!='],
+  ['>', '<='],
+  ['<', '>='],
+];
+
+function coversEverything(comparisons) {
+  if (comparisons.length !== 2) return false;
+  const [a, b] = comparisons;
+  if (a.variable !== b.variable) return false;
+  if (a.numeric !== b.numeric || String(a.value) !== String(b.value)) return false;
+  return COMPLEMENTARY.some(([x, y]) => (a.op === x && b.op === y) || (a.op === y && b.op === x));
 }
 
 export function lintProcess(model, { engineVariables = [] } = {}) {
@@ -71,6 +153,17 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
   const starts = model.nodes.filter((n) => START_TYPES.has(n.type) && !n.scope);
   if (starts.length === 0) add('error', 'no-start-event', model.id, 'The process has no start event, so nothing can ever begin it.');
 
+  // A boundary event has no incoming sequence flow: it fires because the activity it is
+  // attached to is running. So whatever hangs off a boundary event is reachable exactly
+  // when its host activity is, and walking sequence flows alone would report every error
+  // and timeout handler in the model as unreachable.
+  const boundaryByHost = new Map();
+  for (const n of model.nodes) {
+    if (!n.attachedTo) continue;
+    if (!boundaryByHost.has(n.attachedTo)) boundaryByHost.set(n.attachedTo, []);
+    boundaryByHost.get(n.attachedTo).push(n.id);
+  }
+
   const reachable = new Set();
   const queue = starts.map((s) => s.id);
   while (queue.length) {
@@ -78,6 +171,7 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
     if (reachable.has(id)) continue;
     reachable.add(id);
     for (const f of outgoing.get(id) || []) queue.push(f.target);
+    for (const b of boundaryByHost.get(id) || []) queue.push(b);
   }
   for (const n of model.nodes) {
     if (n.scope || n.attachedTo || START_TYPES.has(n.type)) continue;
@@ -102,36 +196,36 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
     const unconditional = outs.filter((f) => !f.condition && f.id !== n.defaultFlow);
 
     if (conditional.length === outs.length && !n.defaultFlow) {
-      add(
-        'error',
-        'no-default-flow',
-        n.id,
-        `Every outgoing flow of "${n.name || n.id}" has a condition and there is no default flow. ` +
-          `If they all evaluate false at runtime the engine raises ENGINE-02004 and the instance stops. ` +
-          `Mark one flow as the default and remove its condition: a default flow carrying a condition is ` +
-          `rejected at deploy time with ENGINE-09005.`
-      );
+      const comparisons = conditional.map((f) => parseComparison(f.condition)).filter(Boolean);
+      const exhaustive = comparisons.length === conditional.length && coversEverything(comparisons);
 
-      // Numeric gap: a > N and a < N leave a == N with nowhere to go.
-      const comparisons = conditional.map((f) => ({ flow: f, cmp: parseComparison(f.condition) })).filter((c) => c.cmp);
-      const byVar = new Map();
-      for (const c of comparisons) {
-        if (!byVar.has(c.cmp.variable)) byVar.set(c.cmp.variable, []);
-        byVar.get(c.cmp.variable).push(c.cmp);
-      }
-      for (const [variable, cmps] of byVar) {
-        if (cmps.length !== conditional.length) continue;
-        const gt = cmps.find((c) => c.op === '>');
-        const lt = cmps.find((c) => c.op === '<');
-        if (gt && lt && gt.value === lt.value && !cmps.some((c) => ['==', '>=', '<='].includes(c.op))) {
-          add(
-            'error',
-            'uncovered-value',
-            n.id,
-            `"${n.name || n.id}" branches on ${variable} > ${gt.value} and ${variable} < ${lt.value}, ` +
-              `so ${variable} == ${gt.value} matches neither branch and the instance will fail there.`
-          );
-        }
+      // A provable gap: `> N` and `< N` between them never match `== N`. This one is
+      // certain, so it is an error even though the general case below is not.
+      const gt = comparisons.find((c) => c.op === '>' && c.numeric);
+      const lt = comparisons.find((c) => c.op === '<' && c.numeric);
+      const sameVar = gt && lt && gt.variable === lt.variable && gt.value === lt.value;
+
+      if (sameVar && comparisons.length === conditional.length) {
+        add(
+          'error',
+          'uncovered-value',
+          n.id,
+          `"${n.name || n.id}" branches on ${gt.variable} > ${gt.value} and ${lt.variable} < ${lt.value}, ` +
+            `so ${gt.variable} == ${gt.value} matches neither branch. The engine raises ENGINE-02004 and the ` +
+            `instance stops there.`
+        );
+      } else if (!exhaustive) {
+        // Not provably broken: the conditions may well cover every case in a way that
+        // cannot be read off the expressions. Worth flagging, not worth blocking a deploy.
+        add(
+          'warning',
+          'no-default-flow',
+          n.id,
+          `Every outgoing flow of "${n.name || n.id}" has a condition and there is no default flow. If a case ever ` +
+            `arises where they all evaluate false, the engine raises ENGINE-02004 and the instance stops. Marking ` +
+            `one flow as the default removes that risk; a default flow must not carry a condition itself, or the ` +
+            `model is rejected at deploy time with ENGINE-09005.`
+        );
       }
     }
 
@@ -174,7 +268,33 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
   const knownNames = new Set([...written.keys(), ...engineVariables]);
   const formFieldNames = [...written.keys()];
 
-  for (const { where, expression, kind } of collectExpressions(model)) {
+  const hasOpaqueForms = model.nodes.some((n) => n.formFields.some((f) => OPAQUE_FIELD_TYPES.has(f.type)));
+  const expressions = collectExpressions(model);
+  const readEverywhere = new Set();
+  for (const e of expressions) {
+    const { direct, safe } = readVariables(e.expression);
+    for (const v of [...direct, ...safe]) readEverywhere.add(v);
+  }
+
+  // Structural mismatch first: a form field nothing reads sitting directly upstream of a
+  // condition reading something nothing writes. This holds whatever the two are called,
+  // so it is the only case reported as an error.
+  for (const n of model.nodes) {
+    if (n.formFields.length === 0) continue;
+    const stranded = findStrandedFormField(model, n, byId, outgoing, readEverywhere, written);
+    if (!stranded) continue;
+    add(
+      'error',
+      'variable-name-mismatch',
+      n.id,
+      `The form on "${n.name || n.id}" writes only "${stranded.field}", which nothing in this process reads, ` +
+        `while the flow leaving it ("${stranded.flow.name || stranded.flow.id}") reads "${stranded.orphan}", which ` +
+        `nothing writes. Completing this element therefore cannot satisfy the condition, and evaluating it throws ` +
+        `"Cannot resolve identifier '${stranded.orphan}'". One of the two names needs to change.`
+    );
+  }
+
+  for (const { where, expression, kind } of expressions) {
     const { direct } = readVariables(expression);
     for (const v of direct) {
       if (knownNames.has(v)) continue;
@@ -192,24 +312,16 @@ export function lintProcess(model, { engineVariables = [] } = {}) {
       }
 
       const near = similarNames(v, formFieldNames);
-      if (near.length > 0) {
-        add(
-          'error',
-          'variable-name-mismatch',
-          where,
-          `Reads "${v}", which nothing in this process writes, while a form here writes ${near.map((s) => `"${s}"`).join(', ')}. ` +
-            `These names look related, so this is most likely a typo: the expression throws ` +
-            `"Cannot resolve identifier '${v}'" the moment it is evaluated.`
-        );
-      } else {
-        add(
-          'warning',
-          'unwritten-variable',
-          where,
-          `Reads "${v}" directly and nothing in this process writes it. If it is not supplied at start time the ` +
-            `expression throws rather than treating it as null. Use \${execution.getVariable('${v}')} if absent is a valid state.`
-        );
-      }
+      add(
+        'warning',
+        'unwritten-variable',
+        where,
+        `Reads "${v}" directly and nothing in this process writes it. That is fine if it always arrives with the ` +
+          `start payload; otherwise the expression throws "Cannot resolve identifier '${v}'" rather than treating ` +
+          `it as null, and \${execution.getVariable('${v}')} would yield null instead.` +
+          (near.length > 0 ? ` A form here writes ${near.map((s) => `"${s}"`).join(', ')}, which is spelled almost the same.` : '') +
+          (hasOpaqueForms ? ` This process embeds an external form, which can set variables the model does not declare, so "${v}" may well be one of those.` : '')
+      );
     }
   }