ba-sync

/nacl:ba-sync --- Синхронизация Excalidraw-доски с Neo4j-графом

Роль

You are a Business Analyst agent specialized in graph synchronization. You read an Excalidraw .excalidraw board file, determine which elements are new or changed, and write the corresponding nodes and relationships to the Neo4j knowledge graph. After writing, you update the board file with assigned IDs and visual confirmation (green stroke), producing a fully synchronized state where the board is the single visual source of truth and the graph is the single structured source of truth.

You are the ONLY skill that writes BA-layer nodes to Neo4j. Other skills (nacl-ba-import-doc, nacl-ba-from-board) produce .excalidraw files with synced: false. This skill is responsible for the board-to-graph bridge.

---

Invocation

/nacl:ba-sync [board_path]

Parameter	Required	Description
board_path	No	Absolute or relative path to an .excalidraw file. If omitted, uses the most recently modified file in {$boards_dir}/ (where $boards_dir is from config.yaml → graph.boards_dir, default: "graph-infra/boards").

---

Shared References

Before executing, read and internalize:

• ${CLAUDE_PLUGIN_ROOT}/nacl-core/SKILL.md --- Excalidraw JSON format, element types, customData structure, color coding, ID generation rules, Neo4j MCP tool names and connection info, and the Board Meta Sidecar schema (§ "Board Meta Sidecar (<board>.meta.json)").

All ID formats, Cypher patterns, customData fields, and color values referenced below originate from that file.

---

Workflow Overview

+-----------------+     +------------------+     +-------------------+
| Phase 1         |     | Phase 2          |     | Phase 3           |
| Read & Validate |---->| Determine        |---->| Sync New          |
| Board           |     | Context          |     | Elements          |
+-----------------+     +------------------+     +-------------------+
                                                         |
+------------------+     +------------------+            v
| Phase 6          |     | Phase 5          |     +-------------------+
| Update Board &   |<----| Sync Changed     |<----| Phase 4           |
| Report           |     | Elements         |     | Sync              |
+------------------+     +------------------+     | Relationships     |
                                                  +-------------------+

Each phase runs sequentially. Phases 3--5 involve interactive Neo4j writes. Phase 6 writes back to the .excalidraw file and updates the meta sidecar.

---

Phase 1: Read and Validate Board

1.1 Locate the board file

If board_path is provided, use it directly. Otherwise, find the latest board:

ls -t {$boards_dir}/*.excalidraw | head -1

If no .excalidraw files exist in {$boards_dir}/, stop and report:

No Excalidraw boards found in {$boards_dir}/. Create a board first with /nacl:ba-import-doc or /nacl:ba-from-board, then run /nacl:ba-sync.

1.2 Read and parse the JSON

Use the Read tool to read the entire .excalidraw file. Parse the JSON structure and confirm:

• Top-level field "type" equals "excalidraw"
• The "elements" array exists and is non-empty

If the file is not valid Excalidraw JSON, stop and report:

File {path} is not a valid Excalidraw file. Expected JSON with "type": "excalidraw".

1.3 Validate customData

Iterate over all non-deleted shape elements (type in ["rectangle", "diamond"]). For each:

• Verify customData exists
• Verify customData.nodeType is one of: WorkflowStep, Decision, BusinessEntity, BusinessRole, Annotation

Collect elements that lack customData or customData.nodeType into a warnings list:

Shape element (id: {id}) at ({x}, {y}) has no customData.nodeType --- will be skipped during sync.

Skip these elements in all subsequent phases. They remain on the board but are not synchronized.

1.4 Classify elements into sync categories

Build three lists from the valid shape elements:

• newElements[] --- elements where customData.nodeId is null (never synced)
• existingElements[] --- elements where customData.nodeId is not null and customData.synced is true
• dirtySyncedElements[] --- elements where customData.nodeId is not null and customData.synced is false (previously synced, then modified on the board)

Also build:

• arrows[] --- all elements where type == "arrow"
• labelMap{} --- map from shape id to its text label (resolved via boundElements / containerId linkage as described in nacl-ba-analyze/SKILL.md Phase 1.3)

1.5 Summary gate

Report to the user before proceeding:

Board: {board_path}
Total shape elements: {N}
  - New (nodeId: null): {N} --- will be created in Neo4j
  - Synced (unchanged): {N} --- will be skipped
  - Modified (synced: false): {N} --- will be updated in Neo4j
  - Skipped (no customData): {N}
Arrows: {N}

Proceeding with sync...

If there are zero new elements AND zero dirty elements, report:

Nothing to sync. All board elements are already synchronized with Neo4j. Board is up to date.

Stop execution.

---

Phase 2: Determine Context

Every WorkflowStep must belong to a BusinessProcess, and every BusinessProcess must belong to a ProcessGroup. This phase establishes these parent containers.

2.1 Query existing ProcessGroups

Use mcp__neo4j__read-cypher:

MATCH (gpr:ProcessGroup)
RETURN gpr.id AS id, gpr.name AS name
ORDER BY gpr.id

Present results to the user:

Existing ProcessGroups in the graph:
  1. GPR-01: {name}
  2. GPR-02: {name}
  ...
  N. [Create new ProcessGroup]

Which ProcessGroup do the processes on this board belong to?

If the user selects an existing group, record its id as targetGprId.

If the user chooses to create a new one, ask for the name, then generate the ID and create the node:

Generate next GPR ID:

MATCH (gpr:ProcessGroup)
RETURN coalesce(max(toInteger(replace(gpr.id, 'GPR-', ''))), 0) + 1 AS nextNum

Format the id with the single-authority formatter — it centralises the prefix/width rule that was duplicated (as the right('0…' + toString(n), w) idiom) across every BA id query; pinned by ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/nacl-ids.test.mjs:

node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/nacl-ids.mjs process-group "$nextNum"   # → GPR-01 when nextNum=1

Create the ProcessGroup node via mcp__neo4j__write-cypher:

MERGE (gpr:ProcessGroup {id: $gprId})
ON CREATE SET gpr.name = $name,
              gpr.description = '',
              gpr.created = datetime(),
              gpr.updated = datetime()
ON MATCH SET  gpr.updated = datetime()
RETURN gpr.id AS id, gpr.name AS name

Record targetGprId.

2.2 Query existing BusinessProcesses within the selected group

Use mcp__neo4j__read-cypher:

MATCH (gpr:ProcessGroup {id: $gprId})-[:CONTAINS]->(bp:BusinessProcess)
RETURN bp.id AS id, bp.name AS name
ORDER BY bp.id

Present results to the user:

Existing BusinessProcesses in {gprName}:
  1. BP-001: {name}
  2. BP-002: {name}
  ...
  N. [Create new BusinessProcess]

Which BusinessProcess does this board represent?

If the user selects an existing process, record its id as targetBpId.

If the user chooses to create a new one, ask for the name, then generate the ID and create:

Generate next BP ID:

MATCH (bp:BusinessProcess)
RETURN coalesce(max(toInteger(replace(bp.id, 'BP-', ''))), 0) + 1 AS nextNum

Format via the single-authority formatter (see GPR note above):

node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/nacl-ids.mjs business-process "$nextNum"   # → BP-001 when nextNum=1

Create the BusinessProcess node and link to ProcessGroup via mcp__neo4j__write-cypher:

MATCH (gpr:ProcessGroup {id: $gprId})
MERGE (bp:BusinessProcess {id: $bpId})
ON CREATE SET bp.name = $name,
              bp.description = '',
              bp.status = 'draft',
              bp.created = datetime(),
              bp.updated = datetime()
ON MATCH SET  bp.updated = datetime()
MERGE (gpr)-[:CONTAINS]->(bp)
RETURN bp.id AS id, bp.name AS name

Record targetBpId.

2.3 Context summary

Report back:

Sync context established:
  ProcessGroup: {targetGprId} ({gprName})
  BusinessProcess: {targetBpId} ({bpName})

---

Phase 3: Sync New Elements

Process every element in newElements[] (those with customData.nodeId == null).

For each element, determine the node type from customData.nodeType and execute the corresponding creation sequence.

3.1 WorkflowStep

a) Generate step ID:

MATCH (bp:BusinessProcess {id: $bpId})-[:HAS_STEP]->(ws:WorkflowStep)
RETURN coalesce(max(toInteger(replace(ws.id, $bpId + '-S', ''))), 0) + 1 AS nextNum

Format via the single-authority formatter — pass the parent $bpId (see GPR note above):

node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/nacl-ids.mjs workflow-step "$nextNum" "$bpId"   # → BP-001-S01 when nextNum=1

b) Resolve display text:

Look up labelMap[element.id] to get the function name text.

c) Determine stereotype:

• If the element's Excalidraw backgroundColor is #e3f2fd (blue), the stereotype is "Автоматизируется"
• If the element's Excalidraw backgroundColor is #e8f5e9 (green), the stereotype is "Бизнес-функция"
• Default: "Бизнес-функция"

d) Determine step_number:

Assign step numbers based on the left-to-right X-coordinate ordering of all WorkflowStep elements on the board. The leftmost step gets step_number: 1, the next gets 2, and so on.

e) Create the node via mcp__neo4j__write-cypher:

MERGE (ws:WorkflowStep {id: $wsId})
ON CREATE SET ws.function_name = $functionName,
              ws.step_number   = $stepNumber,
              ws.stereotype    = $stereotype,
              ws.change_marker = coalesce($changeMarker, '[new]'),
              ws.description   = '',
              ws.created       = datetime(),
              ws.updated       = datetime()
ON MATCH SET  ws.function_name = $functionName,
              ws.step_number   = $stepNumber,
              ws.stereotype    = $stereotype,
              ws.change_marker = coalesce($changeMarker, ws.change_marker),
              ws.updated       = datetime()
RETURN ws.id AS id

f) Link to BusinessProcess via mcp__neo4j__write-cypher:

MATCH (bp:BusinessProcess {id: $bpId})
MATCH (ws:WorkflowStep {id: $wsId})
MERGE (bp)-[:HAS_STEP {order: $stepNumber}]->(ws)
RETURN bp.id AS bpId, ws.id AS wsId

g) Record the mapping: Store {excalidrawElementId -> wsId} for later use in Phase 4 and Phase 6.

3.2 Decision

Decisions are modeled as WorkflowStep nodes with stereotype: "Решение".

a) Generate step ID: Same query as 3.1a (they share the step counter within the process).

b) Resolve display text: Look up labelMap[element.id].

c) Create the node via mcp__neo4j__write-cypher:

MERGE (ws:WorkflowStep {id: $wsId})
ON CREATE SET ws.function_name = $functionName,
              ws.step_number   = $stepNumber,
              ws.stereotype    = 'Решение',
              ws.description   = '',
              ws.created       = datetime(),
              ws.updated       = datetime()
ON MATCH SET  ws.function_name = $functionName,
              ws.step_number   = $stepNumber,
              ws.stereotype    = 'Решение',
              ws.updated       = datetime()
RETURN ws.id AS id

d) Link to BusinessProcess: Same as 3.1f.

e) Record the mapping: Store {excalidrawElementId -> wsId}.

3.3 BusinessEntity

a) Generate entity ID:

MATCH (e:BusinessEntity)
RETURN coalesce(max(toInteger(replace(e.id, 'OBJ-', ''))), 0) + 1 AS nextNum

Format via the single-authority formatter (see GPR note above):

node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/nacl-ids.mjs entity "$nextNum"   # → OBJ-001 when nextNum=1

b) Resolve display text: Look up labelMap[element.id] for the entity name.

c) Determine entity type:

• If the text contains keywords indicating a document (e.g., "заявка", "акт", "отчёт", "форма", "договор", "счёт", "приказ", "протокол", "application", "report", "form", "contract", "invoice") --- set type: "Документ", stereotype: "Внешний документ"
• If the text contains keywords indicating a result (e.g., "результат", "итог", "решение", "result", "output") --- set type: "Результат", stereotype: "Результат"
• If the text contains keywords indicating an object (e.g., "клиент", "заказ", "товар", "проект", "client", "order", "product", "project") --- set type: "Бизнес-объект", stereotype: "Бизнес-объект"
• Default: type: "Бизнес-объект", stereotype: "Бизнес-объект"

d) Create the node via mcp__neo4j__write-cypher:

MERGE (be:BusinessEntity {id: $entityId})
ON CREATE SET be.name        = $name,
              be.type        = $entityType,
              be.stereotype  = $stereotype,
              be.has_states  = false,
              be.description = '',
              be.created     = datetime(),
              be.updated     = datetime()
ON MATCH SET  be.name        = $name,
              be.type        = $entityType,
              be.stereotype  = coalesce($stereotype, be.stereotype),
              be.updated     = datetime()
RETURN be.id AS id

e) Record the mapping: Store {excalidrawElementId -> entityId}.

3.4 BusinessRole

a) Generate role ID:

MATCH (r:BusinessRole)
RETURN coalesce(max(toInteger(replace(r.id, 'ROL-', ''))), 0) + 1 AS nextNum

Format via the single-authority formatter (see GPR note above):

node ${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/nacl-ids.mjs role "$nextNum"   # → ROL-01 when nextNum=1

b) Resolve display text: Look up labelMap[element.id] for the role full name.

c) Check for existing role with the same name (to prevent duplicates when a role appears on multiple boards):

MATCH (r:BusinessRole)
WHERE toLower(r.full_name) = toLower($fullName)
RETURN r.id AS id

If a match is found, reuse the existing id and skip creation. Record the mapping.

d) Create the node (if no match) via mcp__neo4j__write-cypher:

MERGE (r:BusinessRole {id: $roleId})
ON CREATE SET r.full_name   = $fullName,
              r.description = '',
              r.created     = datetime(),
              r.updated     = datetime()
ON MATCH SET  r.full_name   = $fullName,
              r.updated     = datetime()
RETURN r.id AS id

e) Link role to BusinessProcess via mcp__neo4j__write-cypher:

MATCH (r:BusinessRole {id: $roleId})
MATCH (bp:BusinessProcess {id: $bpId})
MERGE (r)-[:PARTICIPATES_IN]->(bp)
RETURN r.id AS roleId, bp.id AS bpId

f) Record the mapping: Store {excalidrawElementId -> roleId}.

3.5 Annotation

Annotations (customData.nodeType == "Annotation") are not synced to Neo4j. They exist only on the board as visual notes.

For each Annotation element:

• Set customData.synced = true (marks it as "processed")
• Set customData.nodeId = "ANNOTATION" (sentinel value, not a real graph ID)
• No Neo4j write occurs

3.6 Progress tracking

After processing each new element, maintain a running log:

[1/{total}] Created WorkflowStep BP-001-S01: "Review application"
[2/{total}] Created WorkflowStep BP-001-S02: "Verify documents"
[3/{total}] Created BusinessEntity OBJ-001: "Application form"
[4/{total}] Reused BusinessRole ROL-01: "Procurement Manager" (already exists)
[5/{total}] Skipped Annotation: "Max processing time: 5 days"

---

Phase 4: Sync Relationships

Process every element in arrows[]. For each arrow, determine the relationship type and create the corresponding edge in Neo4j.

4.1 Resolve arrow endpoints

For each arrow element:

sourceId = arrow.startBinding.elementId  (Excalidraw element ID)
targetId = arrow.endBinding.elementId    (Excalidraw element ID)

If startBinding or endBinding is null, the arrow is dangling. Log a warning and skip:

Arrow (id: {arrow.id}) is not fully connected --- skipping relationship creation.

Look up the Neo4j node IDs using the mapping built in Phase 3 and Phase 1.4:

sourceNodeId = mapping[sourceId]   (e.g., "BP-001-S01")
targetNodeId = mapping[targetId]   (e.g., "BP-001-S02")
sourceNodeType = customData.nodeType of the source element
targetNodeType = customData.nodeType of the target element

If either endpoint has no mapping (e.g., element was skipped due to missing customData), log a warning and skip.

4.2 Determine relationship type

Apply the following rules based on the node types of the source and target:

Source nodeType	Target nodeType	Relationship	Direction
WorkflowStep	WorkflowStep	NEXT_STEP	source -> target
Decision (diamond)	WorkflowStep	NEXT_STEP	source -> target
WorkflowStep	Decision (diamond)	NEXT_STEP	source -> target
Decision (diamond)	Decision (diamond)	NEXT_STEP	source -> target
WorkflowStep	BusinessEntity	PRODUCES	source -> target
BusinessEntity	WorkflowStep	READS	target -> source (the step reads the entity)
BusinessRole	WorkflowStep	PERFORMED_BY	target -> source (the step is performed by the role)
WorkflowStep	BusinessRole	PERFORMED_BY	source -> target (the step is performed by the role)
BusinessRole	BusinessProcess	PARTICIPATES_IN	source -> target

Decision nodes: Decision diamonds are stored in Neo4j as WorkflowStep with stereotype: "Решение" and a step_number assigned in sequence alongside regular steps (see Phase 3.2). They have no PERFORMED_BY relationship --- decisions are process gates, not role-assigned. In the table above, "Decision (diamond)" refers to Excalidraw diamond elements with customData.nodeType: "Decision" which become WorkflowStep nodes in Neo4j.

Special case for BusinessEntity arrows:

When an arrow goes from a WorkflowStep to a BusinessEntity, the relationship is PRODUCES (the step produces the entity).

When an arrow goes from a BusinessEntity to a WorkflowStep, the relationship is READS (the step reads/consumes the entity). In Neo4j, this is stored as (step)-[:READS]->(entity), so the Cypher direction is reversed from the arrow direction on the board.

Special case for BusinessRole arrows:

Regardless of arrow direction on the board, the Neo4j relationship is always (step)-[:PERFORMED_BY]->(role).

4.3 Create relationships

For each resolved arrow, use mcp__neo4j__write-cypher with the appropriate Cypher.

NEXT_STEP (WorkflowStep/Decision to WorkflowStep/Decision):

MATCH (source:WorkflowStep {id: $sourceId})
MATCH (target:WorkflowStep {id: $targetId})
MERGE (source)-[:NEXT_STEP]->(target)
RETURN source.id AS from, target.id AS to

PRODUCES (WorkflowStep to BusinessEntity):

MATCH (ws:WorkflowStep {id: $wsId})
MATCH (be:BusinessEntity {id: $entityId})
MERGE (ws)-[:PRODUCES]->(be)
RETURN ws.id AS step, be.id AS entity

READS (BusinessEntity arrow to WorkflowStep --- stored as step READS entity):

MATCH (ws:WorkflowStep {id: $wsId})
MATCH (be:BusinessEntity {id: $entityId})
MERGE (ws)-[:READS]->(be)
RETURN ws.id AS step, be.id AS entity

PERFORMED_BY (BusinessRole to/from WorkflowStep):

MATCH (ws:WorkflowStep {id: $wsId})
MATCH (r:BusinessRole {id: $roleId})
MERGE (ws)-[:PERFORMED_BY]->(r)
RETURN ws.id AS step, r.id AS role

4.4 Swimlane-based PERFORMED_BY inference

After processing all explicit arrows, check for steps that lack a PERFORMED_BY relationship but are visually contained within a BusinessRole swimlane on the board.

For each WorkflowStep that has no PERFORMED_BY edge created in 4.3:

For each BusinessRole element on the board:
  If step.x >= role.x AND step.y >= role.y
     AND step.x + step.width <= role.x + role.width
     AND step.y + step.height <= role.y + role.height:
    -> The step is inside this role's swimlane
    -> Create PERFORMED_BY relationship (same Cypher as 4.3)

4.5 Progress tracking

[1/{total}] NEXT_STEP: BP-001-S01 -> BP-001-S02
[2/{total}] NEXT_STEP: BP-001-S02 -> BP-001-S03
[3/{total}] PRODUCES: BP-001-S03 -> OBJ-001
[4/{total}] READS: BP-001-S01 <- OBJ-002 (stored as BP-001-S01 -[:READS]-> OBJ-002)
[5/{total}] PERFORMED_BY: BP-001-S01 -> ROL-01
[6/{total}] PERFORMED_BY (swimlane): BP-001-S02 -> ROL-01
[7/{total}] Skipped arrow (id: arrow-015) --- dangling (endBinding: null)

---

Phase 5: Sync Changed Elements

Process every element in dirtySyncedElements[] (those with customData.nodeId != null AND customData.synced == false). These are elements that were previously synced but then modified on the board.

5.1 Read current state from Neo4j

For each element, query the current node using mcp__neo4j__read-cypher:

MATCH (n {id: $nodeId})
RETURN n.id AS id,
       labels(n) AS labels,
       properties(n) AS props

If the node is not found in Neo4j, log an error:

[ERROR] Element '{label}' has nodeId={nodeId} but node not found in Neo4j. Skipping update.
         Consider removing nodeId from customData and re-syncing as new element.

Skip this element.

5.2 Compare and update

Resolve the current board text via labelMap[element.id] and compare with the Neo4j node's name/function_name.

For WorkflowStep / Decision nodes (compare against function_name):

boardText = labelMap[element.id]
graphText = props.function_name

If boardText != graphText:
  -> Update needed

Update via mcp__neo4j__write-cypher:

MATCH (ws:WorkflowStep {id: $wsId})
SET ws.function_name = $newFunctionName,
    ws.updated       = datetime()
RETURN ws.id AS id, ws.function_name AS function_name

For BusinessEntity nodes (compare against name):

MATCH (be:BusinessEntity {id: $entityId})
SET be.name    = $newName,
    be.updated = datetime()
RETURN be.id AS id, be.name AS name

For BusinessRole nodes (compare against full_name):

MATCH (r:BusinessRole {id: $roleId})
SET r.full_name = $newFullName,
    r.updated   = datetime()
RETURN r.id AS id, r.full_name AS full_name

5.3 Mark as synced

After a successful update (or if the text has not changed), mark the element for sync confirmation in Phase 6:

element.customData.synced = true

5.4 Progress tracking

[1/{total}] Updated WorkflowStep BP-001-S03: "Verify documents" -> "Verify and validate documents"
[2/{total}] No change for BusinessEntity OBJ-001: "Application form" (text unchanged)
[3/{total}] Updated BusinessRole ROL-02: "Manager" -> "Senior Manager"
[4/{total}] [ERROR] Node BP-001-S99 not found in Neo4j --- skipped

---

Phase 6: Update Board File and Report

6.1 Update customData in all processed elements

For each element that was successfully synced or created in Phases 3--5, update its customData:

{
  "customData": {
    "nodeId": "{assigned Neo4j ID}",
    "nodeType": "{unchanged}",
    "confidence": "{unchanged}",
    "sourceDoc": "{unchanged}",
    "sourcePage": "{unchanged}",
    "synced": true
  }
}

6.2 Update strokeColor for synced elements

For every element where customData.synced was set to true in this run, change the strokeColor to green:

strokeColor = "#2e7d32"

This provides visual feedback that the element is confirmed in the graph.

6.3 Write the updated board file

Reconstruct the full .excalidraw JSON with the updated elements array and write it back to the same path using the Write tool.

Preserve all other fields (type, version, source, appState, files) unchanged. Preserve all elements that were not processed (arrows, text elements, skipped elements) exactly as they were.

6.4 Write board meta sidecar (success path)

After writing the board file, update the board meta sidecar. The canonical schema, hash algorithm, and merge rules are in ${CLAUDE_PLUGIN_ROOT}/nacl-core/SKILL.md § "Board Meta Sidecar (<board>.meta.json)".

Steps:

1. Derive board name from board_path: strip the directory prefix and the .excalidraw extension (e.g. {$boards_dir}/process-BP-001.excalidraw → process-BP-001).
2. Read existing sidecar: read {$boards_dir}/<board>.meta.json and parse as JSON; if absent or unreadable, start from all-null defaults.
3. Compute content hash: apply the computeBoardHash algorithm (see ${CLAUDE_PLUGIN_ROOT}/nacl-core/SKILL.md § "Board Meta Sidecar") to the scene that was just written. Strip volatile per-element keys (version, versionNonce, seed, updated), sort remaining element keys alphabetically, keep only viewBackgroundColor and gridSize from appState, serialize with JSON.stringify, SHA-256 the result, prefix with sha256:.
4. Merge: patch the following fields, preserving all others (especially lastGeneratedAt and lastGeneratedBy) unchanged:
   • lastSyncedAt = current UTC timestamp in ISO-8601 (e.g. "2026-05-03T19:00:00.000Z")
   • lastSyncStatus = "ok"
   • lastSyncRunId = the run ID passed in by the caller (e.g. analyst-tool's r-<hex> value), or null if the skill was invoked directly without a run ID
   • contentHashAtLastSync = the hash from step 3
5. Atomic write: write the merged JSON to {$boards_dir}/<board>.meta.json.tmp, then rename to {$boards_dir}/<board>.meta.json.

Run ID note: when invoked directly by a human via Claude Code (not via the analyst-tool's skill runner), there is no run ID. In that case set lastSyncRunId to null. When invoked via the analyst-tool, the tool passes the run ID as context; use that value.

6.5 Generate the sync report

Print the report directly to the user:

## Sync Complete: {boardname}

**Board file:** `{board_path}`
**Sync date:** {YYYY-MM-DD HH:MM}
**Target process:** {targetBpId} ({bpName}) in {targetGprId} ({gprName})

---

### Nodes Created

| # | Neo4j ID | Type | Name |
|---|----------|------|------|
| 1 | BP-001-S01 | WorkflowStep | Review application |
| 2 | BP-001-S02 | WorkflowStep | Verify documents |
| 3 | OBJ-001 | BusinessEntity | Application form |
| 4 | ROL-01 | BusinessRole | Procurement Manager |

**Total created:** {N} ({X} WorkflowSteps, {Y} BusinessEntities, {Z} BusinessRoles)

---

### Relationships Created

| # | Type | From | To |
|---|------|------|----|
| 1 | NEXT_STEP | BP-001-S01 | BP-001-S02 |
| 2 | PRODUCES | BP-001-S02 | OBJ-001 |
| 3 | PERFORMED_BY | BP-001-S01 | ROL-01 |

**Total created:** {N} ({A} NEXT_STEP, {B} READS, {C} PRODUCES, {D} PERFORMED_BY)

---

### Nodes Updated

| # | Neo4j ID | Type | Old Value | New Value |
|---|----------|------|-----------|-----------|
| 1 | BP-001-S03 | WorkflowStep | Verify documents | Verify and validate documents |

**Total updated:** {N}

---

### Warnings & Errors

{List of all warnings and errors from all phases, or "None" if clean.}

---

### Board Visual Changes

- Elements with green stroke (#2e7d32): {N} (confirmed synced)
- Elements unchanged: {N}

---

### Next Steps

1. Run `/nacl:ba-analyze` to validate board completeness and graph consistency.
2. Elements with non-green stroke still need attention (medium/low confidence).

If there were errors, add:

3. Fix errors listed above and re-run `/nacl:ba-sync` for failed elements.

---

Meta Sidecar on Failure

When sync fails partway through (validation error, Cypher write error, Neo4j connection lost, or conflict), the board file is NOT rewritten (per the error handling rules below). However, the meta sidecar must still be updated to record the failure so the analyst-tool can show the correct status.

On any terminal failure (after determining that the sync cannot proceed or did not complete cleanly):

1. Derive board name from board_path (same as 6.4 step 1).
2. Read existing sidecar (or all-null defaults if absent).
3. Merge: patch only:
   • lastSyncStatus = "failed"
   • lastSyncRunId = run ID if available, else null
   • Do not update lastSyncedAt or contentHashAtLastSync — these should still reflect the last successful sync.
4. Atomic write: write to .tmp then rename, same as the success path.

This ensures the analyst-tool displays "last sync failed" rather than stale "ok" status.

---

Idempotency Rules

This skill MUST be safe to run multiple times on the same board without creating duplicates.

Rule 1: MERGE instead of CREATE

All Neo4j node creation uses MERGE keyed on {id}. If a node with the same ID already exists, its properties are updated (ON MATCH SET) instead of creating a duplicate.

Rule 2: Skip synced-and-unchanged elements

Elements where customData.synced == true AND customData.nodeId != null are in existingElements[]. They are not processed in Phase 3 or Phase 5 unless their synced flag has been reset to false (indicating a board edit after the last sync).

Rule 3: Relationship MERGE

All relationship creation uses MERGE, not CREATE. Running the sync twice does not produce duplicate edges:

MERGE (source)-[:NEXT_STEP]->(target)      // idempotent
MERGE (ws)-[:PERFORMED_BY]->(r)             // idempotent
MERGE (ws)-[:READS]->(be)                   // idempotent
MERGE (ws)-[:PRODUCES]->(be)                // idempotent
MERGE (gpr)-[:CONTAINS]->(bp)               // idempotent
MERGE (bp)-[:HAS_STEP {order: N}]->(ws)     // idempotent
MERGE (r)-[:PARTICIPATES_IN]->(bp)          // idempotent

Rule 4: ID reuse for existing nodeId

If an element already has customData.nodeId set (from a previous sync), that ID is reused. The skill never generates a new ID for an element that already has one.

Rule 5: Role deduplication by name

Before creating a BusinessRole node, query for an existing role with the same full_name (case-insensitive). If found, reuse the existing node and skip creation (see Phase 3.4c).

---

Error Handling

Board file not found

Board file not found: {path}. Verify the path or check {$boards_dir}/ for available boards.

Invalid JSON

File {path} is not a valid Excalidraw file. Expected JSON with "type": "excalidraw".

Neo4j unavailable

If any mcp__neo4j__write-cypher or mcp__neo4j__read-cypher call fails with a connection error:

Neo4j is not reachable at bolt://localhost:{$neo4j_bolt_port}. Tell me "start the graph" and I will run node "${CLAUDE_PLUGIN_ROOT}/nacl-core/scripts/graph-doctor.mjs" --fix via Bash (works in Claude Code Desktop and CLI). Or start it yourself from the project root (main checkout, not a worktree):

• local mode: docker compose -f graph-infra/docker-compose.yml up -d --- if Docker Desktop is not running, open the Docker Desktop app first
• remote mode: relaunch the sidecar ~/.nacl/sidecar/<project_scope>.sh (Windows: %USERPROFILE%\.nacl\sidecar\<project_scope>.cmd) Cannot proceed with sync.

Stop execution. Do NOT write partial results to the board file --- the board must remain in its pre-sync state so that a retry produces correct results. Write the failure meta sidecar (see "Meta Sidecar on Failure" above).

Partial failure mid-sync

If a single node creation fails but Neo4j is otherwise reachable:

1. Log the error for that element
2. Do NOT update that element's customData (leave synced: false, nodeId: null)
3. Continue processing remaining elements
4. Include the failure in the final report
5. The user can fix the issue and re-run /nacl:ba-sync --- idempotency ensures already-synced elements are skipped

When partial failures occur, Phase 6.4 still runs with lastSyncStatus = "ok" because the overall sync completed (failed individual elements are left for retry). If the majority of the sync failed or the board was not written, use lastSyncStatus = "failed" instead.

---

Reads / Writes

Reads

# Board file:
- {$boards_dir}/{boardname}.excalidraw          # the board being synced

# Shared references:
- ${CLAUDE_PLUGIN_ROOT}/nacl-core/SKILL.md                                 # ID formats, Excalidraw format, Neo4j schema, meta sidecar spec

# Neo4j (via MCP):
- mcp__neo4j__read-cypher                             # query existing nodes, generate next IDs

Writes

# Board file (updated with nodeId, synced, strokeColor):
- {$boards_dir}/{boardname}.excalidraw

# Meta sidecar (always written — success or failure):
- {$boards_dir}/{boardname}.meta.json

# Neo4j (via MCP):
- mcp__neo4j__write-cypher                            # create/update nodes, create relationships

Creates directories

None. The board file already exists (this skill reads an existing board).

Calls

Tool	Purpose
mcp__neo4j__read-cypher	Query existing nodes, generate next available IDs, read node state for comparison
mcp__neo4j__write-cypher	Create/update nodes (MERGE), create relationships (MERGE)

Called by

Caller	Context
User	Manual invocation: /nacl:ba-sync [board_path]
Analyst Tool	Via itsalt-pinch skill runner; passes lastSyncRunId in run context
Recommended after	/nacl:ba-import-doc or /nacl:ba-from-board

---

Checklist

Before completing the sync, verify:

Phase 1: Read and Validate Board

• Board file located and read successfully
• JSON parsed, type: "excalidraw" confirmed
• All shape elements checked for customData
• Elements classified into new / existing / dirty / skipped
• Text labels resolved for all shape elements via boundElements/containerId
• Summary gate shown to user

Phase 2: Determine Context

• ProcessGroup selected or created
• BusinessProcess selected or created
• CONTAINS relationship ensured between ProcessGroup and BusinessProcess

Phase 3: Sync New Elements

• Every new WorkflowStep created with MERGE and linked to BusinessProcess via HAS_STEP
• Every new Decision created as WorkflowStep with stereotype "Решение"
• Every new BusinessEntity created with MERGE
• Every new BusinessRole created with MERGE (or reused if name matches)
• BusinessRole linked to BusinessProcess via PARTICIPATES_IN
• Annotations marked as synced with sentinel nodeId "ANNOTATION"
• All excalidrawElementId -> nodeId mappings recorded

Phase 4: Sync Relationships

• All arrows with valid bindings processed
• NEXT_STEP relationships created for step-to-step arrows
• PRODUCES relationships created for step-to-entity arrows
• READS relationships created for entity-to-step arrows
• PERFORMED_BY relationships created for role-step arrows
• Swimlane-based PERFORMED_BY inferred for steps without explicit role arrows
• Dangling arrows logged as warnings

Phase 5: Sync Changed Elements

• All dirty elements queried from Neo4j
• Text changes detected and updated
• Missing nodes logged as errors
• Updated elements marked for sync confirmation

Phase 6: Update Board and Report

• All processed elements have updated customData (nodeId, synced: true)
• strokeColor changed to #2e7d32 for all synced elements
• Board file rewritten with updated elements
• Meta sidecar written (success: lastSyncedAt + ok + hash; failure: lastSyncStatus = failed)
• Sync report displayed with node/relationship counts
• Warnings and errors listed
• Next steps provided