nacl-migrate

Use with /goal

Wrap with: /nacl-goal migrate-canary (tier L) — alias ships in 2.10.1

This skill is a good fit for autonomous /goal loops because migration progress is graph-verifiable: MIGRATION-REPORT.md records coverage percentages and phase outcomes that the check script reads directly. The wrapper composes a completion condition that MIGRATION-REPORT.md shows >= 98% source coverage AND the retrospective gate has not yet been crossed (which requires human approval before expanding to further projects).

Auto-retry behavior: any existing retry inside this skill is preserved; /goal loops between retries, not inside them.

Check script: nacl-goal/checks/migrate-canary.sh Refusals: see nacl-goal/refusal-catalog.md for the gates this wrapper guards. Background: docs/guides/goal-command.md

---

/nacl-migrate — Old-Methodology → Graph Migration Orchestrator

Role

You orchestrate the one-time migration of a project from the old Markdown- based BA/SA methodology to the new graph-based nacl-* methodology. You do not parse Markdown or write to Neo4j yourself — you delegate to specialist skills (and the stdlib Python scripts they drive) and enforce confirmation gates between phases.

This skill is destructive-adjacent: it creates config.yaml, .mcp.json, graph-infra/, spins up Docker containers, and writes to Neo4j. Every gate is a hard stop requiring user confirmation.

---

Invocation

/nacl-migrate [project_path] [--dry-run] [--skip-ba] [--skip-sa]
              [--skip-render-diff] [--resume-from=<phase>]

Parameter	Required	Description
project_path	No	Project root (default: cwd).
--dry-run	No	Run all parsing + validation, skip Neo4j writes.
--skip-ba	No	SA-only project (BA not yet captured).
--skip-sa	No	BA-only (rare).
--skip-render-diff	No	Do not regenerate Markdown for comparison.
--resume-from	No	Phase name (e.g. sa-migrate) to resume after fix.

---

Prelude — locate NaCl home and verify Python

Run this first on every invocation. Emit messages verbatim on failure.

# 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

# Verify Python 3.11+
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; }

---

Phases

Each phase is a hard confirmation gate. Print the plan, wait for approval, execute, verify, then ask before continuing.

Phase A — Preflight

1. Verify project_path exists and is a git repo. Warn if working tree is dirty.
2. Recommend: git checkout -b migrate-to-graph.
3. Detect layers:
   • BA present if any of docs/00-context, 01-business-processes, 02-business-entities, 03-business-roles, 04-business-rules exist.
   • SA present if any docs/{10–16}-* or docs/{00–06}-* folders exist.
4. Detect adapter (delegate to detect_ba.py).
5. Print the migration plan table with skipped vs planned phases.
6. Gate: Proceed with Phase A.5?

Phase A.5 — ID pattern preflight (MANDATORY)

Before any parse step runs, scan the project for ID-shaped tokens and classify them against the adapter-supported whitelist. This catches the class of regressions where the source repo introduces a new ID convention (e.g. a letter-prefix UC-F01 family) that no adapter knows how to handle yet — without this gate, 100% of UCs/screens silently drop at parse with no surface signal until audit-time.

Run:

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

Read .nacl-migrate/preflight.json. Surface patterns_found to the user as a compact table (the script already prints one). Exit codes:

Exit	Meaning
0	All ID tokens map to a known adapter pattern. Continue.
1	Unknown patterns present. STOP and ask the user.
2	I/O error. STOP and surface the error.

If patterns_unknown is non-empty, STOP and ask the user to either:

1. Widen an adapter to cover the unknown patterns (recommended — produce an adapter patch + add a fixture and a test under nacl-migrate-core/tests/ before rerunning the orchestrator), OR
2. Confirm the unknowns are source-data defects (non-canonical IDs in the source docs themselves — e.g. typo prefixes like KAR-44 in ba_source frontmatter) and should be ignored for this run.

Do NOT proceed to Phase B until the user responds. Record the user's choice in .nacl-migrate/preflight-decision.txt.

Phase B — Initialise graph infrastructure

Delegate: /nacl-init --from={project_path}.

Verify after:

• config.yaml exists
• .mcp.json exists with a Neo4j MCP entry
• graph-infra/docker-compose.yml exists
• Docker container {container_prefix}-neo4j is running
• mcp__neo4j__get-schema responds

If any check fails, stop.

Phase C — Migrate BA (skippable)

Skip if no BA layer or --skip-ba.

Delegate: /nacl-migrate-ba. Inherit --dry-run / --adapter flags if set.

Verify after:

• MIGRATION-REPORT-BA.md exists
• .nacl-migrate/ba-audit.json shows summary.blockers == 0
• BA node counts > 0 in Neo4j (skip this check if --dry-run)

Phase D — Validate BA

Skip if BA skipped.

Delegate: /nacl-ba-validate. Expect L1–L8 = 0 errors.

Warnings without errors → continue with user acknowledgement.

Phase E — Migrate SA (skippable)

Skip if no SA layer or --skip-sa.

Delegate: /nacl-migrate-sa. Pass --no-ba if BA was skipped in this run.

Verify after:

• MIGRATION-REPORT-SA.md present
• .nacl-migrate/sa-audit.json clean
• Cross-layer handoff edges match traceability matrix row counts (blocker if mismatch and BA present).

Phase F — Validate SA

Delegate: /nacl-sa-validate. Expect L1–L13 = 0 CRITICAL; XL6–XL9 cross-validation clean if BA present.

A freshly migrated graph has no connected-spec extension nodes (Screens, Slices, DomainErrors, CachePolicies — 2.15+), so L10–L13 pass vacuously. To adopt those layers afterwards, follow docs/runbooks/upgrade-graph-extensions.md.

Phase G — Drift diagnostic

Delegate: /nacl-tl-diagnose.

Drift is expected when code evolved after the last BA/SA pass — this phase surfaces it for the user to decide on /nacl-tl-reconcile as a follow-up. It does not block migration.

Phase H — Render diff (skippable)

Skip if --skip-render-diff.

Delegate: /nacl-render --output=.nacl-migrate/rendered-docs.

Then:

diff -r docs/ .nacl-migrate/rendered-docs/ > .nacl-migrate/render-diff.txt

Summarise: identical / formatting-only / semantic differences. Semantic differences are the interesting signal for the retrospective gate.

Phase I — Aggregate MIGRATION-REPORT.md

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

• Timestamps and adapter used
• Per-layer source file counts → IR counts → Neo4j counts (must all match)
• Validation results (BA L1–L8 + XL1–XL5, SA L1–L13 + XL6–XL9)
• Cross-layer edge counts
• Drift summary
• Render-diff summary
• Skipped files with reasons
• Warnings
• Go/no-go for retrospective gate

---

MANDATORY retrospective gate (on canary projects)

Active on the first-in-order canary project. Do not run /nacl-migrate on any further project until the gate completes and the user approves the retrospective report. Per the migration retrospective gate design:

1. Launch 3 Explore sub-agents in parallel:
   • BA parity auditor → BA-AUDIT.md
   • SA parity auditor → SA-AUDIT.md
   • Semantic fidelity auditor → RENDER-DIFF-AUDIT.md
2. Orchestrator synthesises → RETROSPECTIVE.md.
3. User reviews and approves.
4. Fix blocker defects in the scripts, re-run on the canary, re-audit.

For subsequent projects, a lighter spot-check audit is sufficient unless a new defect class surfaces.

---

Reads / Writes

Reads

• Project docs tree
• Neo4j via MCP (read-only self-audit)

Writes

• config.yaml, .mcp.json, graph-infra/ (via nacl-init)
• Neo4j (via delegated skills)
• .nacl-migrate/*.json and .nacl-migrate/rendered-docs/
• MIGRATION-REPORT-BA.md, MIGRATION-REPORT-SA.md, MIGRATION-REPORT.md

Delegates to

Skill	Phase
nacl-init	B
nacl-migrate-ba	C
nacl-ba-validate	D
nacl-migrate-sa	E
nacl-sa-validate	F
nacl-tl-diagnose	G
nacl-render	H

---

Idempotency

All delegated skills are idempotent on their writes. Re-running this orchestrator is safe — it skips already-configured infra in Phase B and MERGE-updates Neo4j properties without duplication.

---

Error handling

• Any gate failure stops the pipeline; the aggregated report is still written up to that point.
• --resume-from=<phase> jumps to a named phase, reusing IR files in .nacl-migrate/ if present.
• Neo4j unreachability stops before any write.

---

Checklist

• Prelude: $NACL_HOME resolved, Python 3.11+ present
• Phase A: layer detection done, plan approved
• Phase A.5: ID-pattern preflight clean (or unknowns explicitly resolved)
• Phase B: graph infra up, Neo4j reachable
• Phase C: BA migrated (or skipped by design)
• Phase D: BA validation clean
• Phase E: SA migrated (or skipped by design)
• Phase F: SA validation clean
• Phase G: drift diagnostic run
• Phase H: render-diff produced (or skipped)
• Phase I: MIGRATION-REPORT.md written
• Retrospective gate triggered if canary