/nacl-migrate-sa — SA Markdown → Neo4j

Role

You delegate SA parsing, validation, and Cypher generation to stdlib Python scripts under $NACL_HOME/nacl-migrate-sa/scripts/. You never parse Markdown yourself; the scripts own that. Your job is:

1. Run the scripts in order.
2. Read their JSON outputs.
3. Execute the Cypher plan against Neo4j via mcp__neo4j__write-cypher.
4. Gather live counts via mcp__neo4j__read-cypher and hand them to audit_sa.py.
5. Present results and errors to the user in plain language.

If the project has a BA layer, nacl-migrate-ba must have already run — this skill emits cross-layer handoff edges that point at BA nodes.

---

Invocation

/nacl-migrate-sa [project_path] [--dry-run] [--adapter=<name>] [--no-ba]

Parameter	Required	Description
project_path	No	Project root (default: cwd).
--dry-run	No	Parse + validate + Cypher gen; no Neo4j writes, no audit.
--adapter	No	Force adapter (inline-table-v1). Default: auto-detect.
--no-ba	No	Skip cross-layer handoff edges. Use for SA-only projects.

---

Prelude — locate NaCl home and verify Python

# Resolve $NACL_HOME
if [ -z "$NACL_HOME" ]; then
  for candidate in "$HOME/projects/NaCl" "$HOME/NaCl" "$HOME/code/NaCl" "$HOME/src/NaCl"; do
    if [ -f "$candidate/nacl-migrate-core/nacl_migrate_core/__init__.py" ]; then
      export NACL_HOME="$candidate"
      break
    fi
  done
fi
if [ -z "$NACL_HOME" ] || [ ! -f "$NACL_HOME/nacl-migrate-core/nacl_migrate_core/__init__.py" ]; then
  echo "Unable to locate NaCl repo. Set NACL_HOME=/path/to/NaCl and retry." >&2
  exit 1
fi

python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3,11) else 1)' 2>/dev/null \
  || { echo "Python 3.11+ required. On macOS: brew install python@3.11"; exit 1; }

---

Soft preflight (direct invocation)

When invoked directly (i.e. not via the /nacl-migrate orchestrator), run an ID-pattern scan and warn — but do not block — if any token in the project's filenames or YAML frontmatter does not match a known adapter pattern. The orchestrator path runs the same scan at Phase A.5 with a hard gate; the direct-invocation path stays non-blocking so a single-layer rerun is ergonomic.

mkdir -p .nacl-migrate
python3 "$NACL_HOME/nacl-migrate-ba/scripts/preflight_ids.py" \
  --project "$PWD" \
  --output .nacl-migrate/preflight.json || true

Exit code 1 from the script means unknown patterns were found. Surface the report's patterns_unknown list to the user:

Preflight surfaced N unknown ID-shaped tokens. These will likely be dropped at parse. Review .nacl-migrate/preflight.json and either widen an adapter (recommended) or pass --force to proceed anyway.

If the user passes --force, continue. Otherwise stop.

---

Preconditions

1. config.yaml / .mcp.json present; Neo4j reachable via mcp__neo4j__get-schema.
2. At least one SA folder exists under docs/ (10-16 or 00-06 variant). If none: "No SA layer detected. Skipping nacl-migrate-sa." Exit cleanly.
3. Unless --no-ba: BA nodes present in Neo4j (query MATCH (bp:BusinessProcess) RETURN count(bp) > 0). If zero AND the project has a BA docs tree, stop — user must run /nacl-migrate-ba first.

---

Phase 0 — Detect adapter + numbering

The SA parser infers both at once. For now there is a single SA adapter (inline-table-v1), which auto-detects 10-16 vs 00-06 numbering and handles an optional frontmatter fallback for UC files.

Skip this phase when --adapter was passed explicitly.

---

Phase 1 — Parse SA markdown → SaIR + HandoffIR

python3 "$NACL_HOME/nacl-migrate-sa/scripts/parse_sa.py" \
  --project "$PWD" \
  --adapter inline-table-v1 \
  --output .nacl-migrate/sa-ir.json \
  --handoff-output .nacl-migrate/handoff-ir.json

Expected stdout: counts table for SaIR and HandoffIR. Surface every warning code to the user.

On error exit, print message + remediation verbatim.

---

Phase 2 — Validate IR

python3 "$NACL_HOME/nacl-migrate-sa/scripts/validate_sa_ir.py" \
  --input .nacl-migrate/sa-ir.json \
  --handoff .nacl-migrate/handoff-ir.json \
  --output .nacl-migrate/sa-validation.json

13 referential checks (SV1–SV8 + HV1–HV5). Exit 0 → all pass. Exit 1 → stop and print the failure list.

The script also prints a Coverage section (SC1–SC7) and writes a coverage block to sa-validation.json. This is the completeness dimension — it measures how much of each node type the adapter actually populated (UC activity steps, UC module, UC↔form links, entity attributes, enum values, form fields). It exists because the referential checks and the Phase 7 audit are both blind to under-extraction: an IR with 1 ActivityStep total is internally consistent and writes cleanly, yet leaves nearly every UseCase an empty shell.

Coverage is advisory by default (it does not change the exit code — some emptiness is legitimate, e.g. a pure list-view UC has no steps). Surface the Coverage lines to the user verbatim; do not bury them. A severely under-extracted migration now shows e.g. SC1 UC activity steps: 1/50 (2.0%) instead of a silent "clean".

To gate in CI, add --strict (fail any metric below 100%) or --min-coverage PCT (fail below PCT). These flip the exit code to non-zero; leave them off for the normal interactive migration.

---

Phase 3 — Generate Cypher plan

python3 "$NACL_HOME/nacl-migrate-sa/scripts/generate_sa_cypher.py" \
  --input .nacl-migrate/sa-ir.json \
  --handoff .nacl-migrate/handoff-ir.json \
  --output .nacl-migrate/sa-cypher.json

Three batch kinds: node, edge (SA-internal), handoff (BA↔SA). If --no-ba was set, skip all handoff batches when executing.

If --dry-run: stop here and report the plan summary.

---

Phase 4 — Execute Cypher against Neo4j

Preflight: mcp__neo4j__get-schema() must succeed.

Read .nacl-migrate/sa-cypher.json. For each batch:

mcp__neo4j__write-cypher(query = batch.cypher, params = batch.params)

Report progress per batch: [i/N] {label} rows=... ok.

If --no-ba, skip batches where kind == "handoff" and log a single line: Skipping N handoff batches (--no-ba).

On any batch failure: log the batch index + error; stop. The partial graph is MERGE-idempotent — rerunning after a fix is safe.

---

Phase 5 — SUGGESTS edges (optional, best-effort)

Emit ProcessGroup -[:SUGGESTS]-> Module edges from in-graph data. This is the only SA edge type that can't be computed by the scripts because it requires joining SA's Module.related_process_ids with BA's ProcessGroup -[:CONTAINS]-> BusinessProcess. Run via MCP:

MATCH (gpr:ProcessGroup)-[:CONTAINS]->(bp:BusinessProcess)
MATCH (m:Module)
WHERE bp.id IN m.related_process_ids
MERGE (gpr)-[:SUGGESTS]->(m)
RETURN count(*) AS n

Skip entirely if --no-ba.

---

Phase 6 — Gather live counts

Query Neo4j via mcp__neo4j__read-cypher for every node label and edge type listed in audit_sa.py. Important: scope HAS_STEP, HAS_ATTRIBUTE, and NEXT_STEP counts to the SA layer, because those relationship types also exist on the BA layer. Use label-scoped Cypher:

MATCH (:UseCase)-[r:HAS_STEP]->(:ActivityStep) RETURN count(r) AS n
MATCH (:DomainEntity)-[r:HAS_ATTRIBUTE]->(:DomainAttribute) RETURN count(r) AS n
MATCH (:ActivityStep)-[r:NEXT_STEP]->(:ActivityStep) RETURN count(r) AS n

All other edge types have SA-exclusive labels and can use the unscoped form.

Write the counts to .nacl-migrate/sa-live-counts.json.

---

Phase 7 — Audit

python3 "$NACL_HOME/nacl-migrate-sa/scripts/audit_sa.py" \
  --ir .nacl-migrate/sa-ir.json \
  --handoff .nacl-migrate/handoff-ir.json \
  --counts .nacl-migrate/sa-live-counts.json \
  --output .nacl-migrate/sa-audit.json

Exit 0 → "All SA counts match." Exit 1 → surface mismatches to the user.

The audit prints a pointer line — count parity ✓ — see validation coverage (SC1–SC7 …) — because count parity only proves IR→graph fidelity, never extraction completeness. When you report the audit result to the user, quote the Phase-2 Coverage numbers next to it; never present "All SA counts match" as if it meant the migration is complete.

---

Phase 7b — Backfill validation exemption flags

Migrated graphs are populated from markdown documents that predate the L4–L7 validators. Their nodes lack the has_ui / system_only / shared / internal / field_category exemption properties, which causes nacl-sa-validate to emit dozens of false-positive findings on the very first run.

To prevent this, the migration ends with an automatic backfill via nacl-sa-flags:

/nacl-sa-flags backfill-all --detect-internal

Behavior:

• :UseCase.has_ui is derived deterministically: true if (uc)-[:USES_FORM]->(:Form), else false.
• :DomainAttribute.internal is auto-flagged for system patterns (id, *_id, *_at, *_token, *_hash).
• :SystemRole.system_only, :DomainEntity.shared, :FormField.field_category get safe defaults (false, false, 'input').

The user is prompted at the end of Phase 7 to confirm before the backfill runs. If declined, the migration completes without flags and nacl-sa-validate full will surface ~50–150 NULL-property findings as recommendations rather than CRITICAL/WARN; the user can then run nacl-sa-flags backfill-all manually at any later time.

Why --detect-internal by default: post-migration graphs have many surrogate keys and timestamps. The heuristic flags them automatically and is safe (it only sets internal=true, never internal=false, so manually-flagged user-facing attributes are preserved). Real telemetry / provider-internal columns may need additional manual marking after the first validate run.

---

Phase 8 — Report

Write MIGRATION-REPORT-SA.md at project root:

# SA Migration Report

**Project:** {project_path}
**Adapter:** {adapter}
**Numbering:** {numbering}  (10-16 or 00-06)
**Ran at:** {ISO timestamp}

## SA IR vs live Neo4j
(Copy from sa-audit.json — node + edge tables.)

**Audit result: N/N CLEAN** — but count parity only proves IR→graph fidelity.
See Completeness / Coverage below for whether the IR itself is complete.

## Completeness / Coverage
(Copy the `coverage` block from sa-validation.json. One line per metric, kept
adjacent to the audit headline so "CLEAN" is never read as "complete".)

| Metric | Covered | % | Sample missing |
|--------|---------|---|----------------|
| SC1 UC activity steps | {covered}/{total} | {pct}% | {sample_missing} |
| SC2 UC module | {covered}/{total} | {pct}% | … |
| SC3 UC→form link | {covered}/{total} | {pct}% | … |
| SC3f Form→UC link | {covered}/{total} | {pct}% | … |
| SC4 DomainEntity module | {covered}/{total} | {pct}% | … |
| SC5 DomainEntity attributes | {covered}/{total} | {pct}% | … |
| SC6 Enumeration values | {covered}/{total} | {pct}% | … |
| SC7 Form fields | {covered}/{total} | {pct}% | … |

Coverage is advisory: low percentages flag adapter under-extraction (or
legitimately empty nodes), not a write failure. Investigate any metric well
below 100% before declaring the migration done.

## Cross-layer handoff
(Counts of AUTOMATES_AS, REALIZED_AS, TYPED_AS, MAPPED_TO, IMPLEMENTED_BY, SUGGESTS.)

## Warnings
{list from sa-ir.json warnings[] and handoff-ir.json, or "none"}

## Non-extracted relationships
The following are currently 0 because the adapter does not extract them:
  - FormField / HAS_FIELD / MAPS_TO (needs _form-domain-mapping.md parser)
  - ActivityStep.NEXT_STEP (needs UC flowchart Mermaid parser)
  - UseCase -[:ACTOR]-> SystemRole
  - SystemRole -[:HAS_PERMISSION]-> DomainEntity
  - BusinessRule -[:IMPLEMENTED_BY]-> Requirement (matrix uses category names, not REQ ids)

Adding any of these is a per-adapter enhancement. Non-blocker for migration.

## Next steps
- Run `/nacl-sa-validate` (L1-L13 + XL6-XL9 cross-validation; L10-L13 pass vacuously until the project adopts the 2.15+ extension layers — see `docs/runbooks/upgrade-graph-extensions.md`)
- Run `/nacl-tl-diagnose` for code-docs drift analysis

---

Idempotency

All Neo4j writes are MERGE-keyed on canonical IDs. Safe to rerun. If an adapter change produces different canonical IDs, old nodes become orphans — audit_sa.py flags this as a count mismatch.

---

Known non-blockers

The current adapter does not extract:

• FormField / HAS_FIELD / MAPS_TO — requires parsing _form-domain-mapping.md.
• ActivityStep.NEXT_STEP — UC activity flows are text tables without explicit step-number links.
• UseCase -[:ACTOR]-> SystemRole — UC.actor is text ("ACT-01 Пользователь"); resolving it to a SYSROL requires the SystemRole table to be loaded first.
• SystemRole -[:HAS_PERMISSION]-> DomainEntity — requires parsing the permissions matrix.
• BusinessRule -[:IMPLEMENTED_BY]-> Requirement — traceability matrix maps BRQ to category strings, not REQ IDs. Warning: HANDOFF_REQ_CATEGORY is logged per row.

These can be added as adapter enhancements later. None is blocking for migration correctness.

---

Error handling

Situation	Response
Prelude can't find $NACL_HOME	Stop. Ask to export NACL_HOME.
Python < 3.11	Stop. Ask user to upgrade.
BA docs present but BA nodes missing	Stop. Ask user to run /nacl-migrate-ba first.
Ambiguous numbering (both 10-16 and 00-06 dirs present)	Stop. Ask user to remove one.
Adapter unknown	Stop. Present supported adapters.
Validation failure	Stop. Print failed checks.
Batch failure	Stop after the failing batch. Rerun after fix.
Audit mismatch	Report, do not claim success.

---

Reads / Writes

Reads

• {project}/docs/{10-16|00-06}-*/**/*.md
• {project}/docs/99-meta/traceability-matrix.md
• mcp__neo4j__read-cypher (live counts in Phase 6)
• mcp__neo4j__get-schema (preflight)

Writes

• .nacl-migrate/sa-ir.json
• .nacl-migrate/handoff-ir.json
• .nacl-migrate/sa-validation.json
• .nacl-migrate/sa-cypher.json
• .nacl-migrate/sa-live-counts.json
• .nacl-migrate/sa-audit.json
• MIGRATION-REPORT-SA.md
• mcp__neo4j__write-cypher (Phases 4, 5)

---

Checklist

• Prelude: $NACL_HOME resolved, Python 3.11+ present
• Phase 0: adapter + numbering detected (or user supplied)
• Phase 1: SA IR + Handoff IR emitted
• Phase 2: validation 13/13 pass (or blocker list surfaced) + Coverage (SC1–SC7) reported
• Phase 3: Cypher plan generated
• Phase 4: every batch executed via mcp__neo4j__write-cypher
• Phase 5: SUGGESTS edges emitted (or skipped with --no-ba)
• Phase 6: live counts gathered (layer-scoped for shared rel types)
• Phase 7: audit clean
• Phase 8: MIGRATION-REPORT-SA.md written