corezoid-project-review

# Review a Corezoid Project

You are a specialist in auditing entire Corezoid projects and folders using the `corezoid` MCP server.

Per-process analysis follows the same steps as the `corezoid-review` skill (lint, hardcodes, naming, code review, semaphors, error handling, dependencies). This skill adds orchestration: discovery, batching, cross-process analysis, and aggregated reporting.

---

## Phase 0 — Project Discovery

### Step 0.1: Verify Environment

Read `.env` from the current working directory and check for `COREZOID_STAGE_ID`.

- If `COREZOID_STAGE_ID` is **missing or empty** → stop and invoke the `corezoid-init` skill. Do not proceed until init completes.
- If `COREZOID_STAGE_ID` is present → use it as the root `folder_id` for the review scope.

### Step 0.2: Build Process Inventory

Collect for each process: `conv_id`, `title`, `folder_id`, `project_id`, `stage_id`, `obj_type`.
Store as `process_inventory[]`. Skip objects where `obj_type != conveyor` unless explicitly requested.

### Step 0.3: Announce Scope

Before starting, report:

```
Found N processes in project "<project_name>":
  - Process A (conv_id: 12345)
  - Process B (conv_id: 67890)
  ...
Proceeding with full review.
```

Process all sizes automatically without confirmation. Stream progress in batches of 10.

---

## Phase 1 — Per-Process Audit

For each process in `process_inventory[]`:

1. Pull the process with MCP tool **`pull-process`** using `process_id`
2. Run the full per-process audit (same steps as `corezoid-review` skill):
   - **Step 1** Structural lint (`lint-process`)
   - **Step 2** Load and parse nodes
   - **Step 3** Hardcode check
   - **Step 4** Repeated logic
   - **Step 5** Cycle verification
   - **Step 6** Node naming
   - **Step 7** Code node analysis
   - **Step 8** Semaphor coverage
   - **Step 9** Error handling review
   - **Step 10** External dependencies inventory
3. Store result as `process_reports[conv_id]`
4. Log progress: `Reviewed N/total: "<title>" — X findings`

Reference: `${CLAUDE_PLUGIN_ROOT}/skills/corezoid-review/SKILL.md`

---

## Phase 2 — Cross-Process Analysis

Requires all `process_reports[]` from Phase 1.

### Step 2.1: Dependency Graph

Build a directed graph — nodes: all processes; edges: every `api_rpc` / `api_copy` call between them.

Flag:
- ⚠️ **Circular dependencies** — A calls B which calls A
- ⚠️ **Orphaned processes** — never called and no direct external input
- ⚠️ **High fan-in** — called by > 5 other processes (single point of failure)
- ⚠️ **High fan-out** — calls > 7 other processes (coupling risk)
- ℹ️ **External calls** — `conv_id` values pointing outside the project inventory

### Step 2.2: Duplicate Logic Across Processes

- Two processes with identical or >80% similar `api_code` nodes → candidate for shared subprocess
- Two processes calling the same external URL with same parameters → candidate for shared wrapper process

### Step 2.3: Shared Hardcoded Values

Aggregate only normalized `hardcode.*` findings from per-process reports. Do **not** aggregate dynamic Corezoid expressions, `dependency.state_store_ref`, or values fully wrapped in `{{...}}` as shared hardcodes.

- Same URL in > 2 processes → recommend shared `env_var` (use `/corezoid-variable-manager` to create)
- Same numeric `conv_id` in > 1 process → one alias fix resolves all
- Same token/key fragment in > 1 process → security risk, centralize immediately via `/corezoid-variable-manager` as `secret` variable
- Same status string in > 2 processes → recommend shared constant or `env_var`
- Same error text in > 1 process → recommend shared text constant

False-positive guard (same as per-process review):
- Ignore values that are fully dynamic expressions, e.g. `{{conv[@storage].ref[{{key}}].field}}`
- If a shared value is a state-store alias, report it under dependency analysis instead of `cross_process.shared_hardcode_value`
- Recompute aggregate summary counts after removing false positives

### Step 2.4: Alias Consistency

Flag:
- Same alias used with both `create` and `modify` in different processes → race condition risk
- Alias defined in one process but used with numeric `conv_id` in another → inconsistency
- Aliases referenced in processes but absent from project inventory → undocumented external dependency

To fix alias issues found here (create missing aliases, rename, repoint, delete conflicts),
use the `/corezoid-alias-manager` skill.

### Step 2.5: Naming Consistency

Flag:
- Same vague name used widely (e.g. 10+ nodes named `"error"` across project) → recommend naming standard
- Mixed conventions across processes (`Create_X` vs `createX`)

---

## Phase 3 — Aggregate Report

Produce two output files: `project-review-<date>.json` and `project-review-<date>.md`.

All per-process findings from Phase 1 are merged into a single flat `findings[]` array. Cross-process findings (Phase 2) are added to the same array with `conv_id: null` and `issue_type` from the table below.

Run final normalization after merging: remove duplicates, remove dynamic-expression hardcode false positives, keep `dependency.state_store_ref` separate from hardcode metrics, recompute all summary counters.

### Cross-Process Issue Types

| issue_type | issue_subtype | severity |
|------------|---------------|----------|
| `cross_process` | `circular_dependency` | high |
| `cross_process` | `orphaned_process` | warning |
| `cross_process` | `high_fan_in` | warning |
| `cross_process` | `high_fan_out` | warning |
| `cross_process` | `external_call` | low |
| `cross_process` | `shared_hardcode_url` | high |
| `cross_process` | `shared_hardcode_token` | high |
| `cross_process` | `shared_hardcode_value` | medium |
| `cross_process` | `duplicate_logic` | low |
| `cross_process` | `alias_conflict` | warning |
| `cross_process` | `naming_convention` | low |

Cross-process finding example:

```json
{
  "conv_id": null,
  "process_title": null,
  "node_id": null,
  "node_title": null,
  "issue_type": "cross_process"