corezoid-review

# Review a Corezoid Process

You are a specialist in auditing and analyzing Corezoid BPM processes using the `corezoid` MCP server.

## Identify the Process (MANDATORY FIRST STEP)

**Before doing anything else**, resolve `PROCESS_PATH`:

1. Check whether the user already provided a process identifier — a file path, process name, or process ID — in the current message or conversation history.
2. If no identifier is provided, ask:

   > "Please specify the process — you can provide a file path (e.g. `1278273_Business.folder/2778176_payment.conv.json`), a process name, or a process ID."

   Do **not** call any MCP tools until the user provides an identifier.
3. If the user gave a **name or ID** (not a file path), search the local working directory for the matching `.conv.json` file using the `find` or `grep` Bash tools (the project is already pulled locally).
4. Once `PROCESS_PATH` is known, begin the audit below.

---

## Step 1: Structural Lint

Run the linter to detect structural issues automatically:

Call MCP tool **`lint-process`** with `process_path: "<PROCESS_PATH>"`.

This checks for:
- **Orphaned nodes** — unreachable nodes not connected from Start
- **No-op conditions** — all branches of a condition leading to the same node
- **Unused set_param** — variables set but never referenced downstream

Record all findings. They will be included in the final report.

---

## Step 2: Load and Parse the Process

Read the `.conv.json` file and extract nodes:

- `ops[0]['scheme']` is a **list** — always index `[0]`
- `node['condition']` is a dict with keys `logics` (list) and `semaphors` (list)
- `node['extra']` is a **string** (escaped JSON) — not a dict
- Conditions in `go_if_const` logics live in `lg['conditions']`, NOT in `lg['extra']`

Collect node groups for analysis:

```python
code_nodes  = [n for n in nodes for lg in n['condition']['logics'] if lg['type'] == 'code']
api_nodes   = [n for n in nodes for lg in n['condition']['logics'] if lg['type'] == 'api']
rpc_nodes   = [n for n in nodes for lg in n['condition']['logics'] if lg['type'] == 'api_rpc']
copy_nodes  = [n for n in nodes for lg in n['condition']['logics'] if lg['type'] == 'api_copy']
cond_nodes  = [n for n in nodes for lg in n['condition']['logics'] if lg['type'] == 'go_if_const']
```

---

## Step 3: Hardcode Check

- **`code` nodes** — look for hardcoded IDs, URLs, tokens
- **`api` nodes** — check URLs; must use `{{env_var[@name]}}`, not literals
- **`api_rpc` / `api_copy`** — check `conv_id` values; numeric IDs instead of `@alias` are a flag
- **`api_rpc` extra fields** — check for hardcoded values that should be variables

Flag each hardcoded value for extraction to env_var (see `${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md`).

### Root-level process metadata — do NOT flag as hardcoded

The `.conv.json` file has top-level fields that are process metadata assigned by the platform. Do **not** report them as hardcoded values:

| Field | Description |
|-------|-------------|
| `conv_id` | The ID of this process itself |
| `user_id` | Owner/author user ID |
| `company_id` | Company/tenant identifier |
| `folder_id` | Folder identifier |
| `project_id` | Project identifier |
| `stage_id` | Stage/environment identifier |

These are read-only platform metadata, not configuration that should be extracted to env_vars.

---

## Step 4: Repeated Logic

- Compare similarly named nodes (e.g. multiple `CREATE ACTOR`, `MANAGE ACCESS RULES`)
- If structure is identical → mark as duplicated logic, recommend extracting into a subprocess

---

## Step 5: Cycle Verification

- Detect nodes with `semaphors` of type `time` or `go_if_const` that create loops
- Verify exit conditions exist and iteration limits are enforced

---

## Step 6: Node Naming

- Identify nodes with empty `title`
- Check for duplicate or vague names
- Recommended format: `Action_Object_Context` (e.g. `Create_Stream_Active`)

---

## Step 7: Code Node Analysis

### JavaScript nodes — check for:

- `try/catch` wrapping all external calls
- No hardcoded values (IDs, tokens, URLs)
- Safe type conversions (`parseInt`, `Number`)
- Input validation (`if (!data.var) { ... }`)
- No `eval` usage

### Erlang nodes — check for:

- Pattern matching covers all cases
- `catch` or `case` for invalid data
- No recursion without termination conditions

### set_param optimization

Code nodes that only do simple assignments should be replaced with `set_param`. Flag these patterns:

| Pattern in code node                    | Replace with set_param                      |
|-----------------------------------------|---------------------------------------------|
| `data.x = data.y;`                      | `"x": "{{y}}"`                              |
| `data.x = data.a + "_" + data.b;`       | `"x": "{{a}}_{{b}}"`                        |
| `data.x = data.a + data.b;` (numeric)   | `"x": "$.math({{a}}+{{b}})"`                |
| `data.x = data.a * data.b;`             | `"x": "$.math({{a}}*{{b}})"`                |
| `data.x = "constant";`                  | `"x": "constant"`                           |
| `data.x = data.x;`                      | remove entirely (self-assignment, no-op)     |

`$.math()` takes exactly **two operands**. For 3+, nest: `$.math($.math({{a}}+{{b}})+{{c}})`. Supported operators: `+`, `-`, `*`, `/`. Use `extra_type: "number"` when the result should be numeric.

Operations that genuinely require a code node: `str.length`, regex, `JSON.parse/stringify`, array `.map/.filter`, complex `if/else`, object key iteration.

---

## Step 8: Semaphor Coverage

Check for missing semaphors by severity:

- 🔴 **`api_callback`** — MUST have a `time` semaphor. Without one tasks hang forever if the user abandons the session.
- 🟡 **`api`** (outbound HTTP) — Should have a `time` semaphor as safety net against unresponsive endpoints.
- 🟢 **`api_rpc`** — Lower severity; target process handles its own timeouts. Still recommended.
- 🟢 **`api_copy` with `is_sync: true`** — Informational;