smith-migrate-system-paths

Smith System Path Migration

Add paths: YAML frontmatter to existing system specs without disturbing their hand-authored prose. After migration, the Smith manifest v2 path-resolver tier 1 reads these paths: entries and routes source files into the correct system bucket.

Arguments: $ARGUMENTS

When to use

• A project has .specify/systems/system-*/spec.md files written as prose (no YAML frontmatter, or frontmatter without paths:).
• The Smith manifest v2 resolver is now in use and you want tier 1 (declared paths) to take precedence over tier 2 (system-paths.json) and tier 3 (heuristic).
• You ran /smith-index and the per-system manifests are bucketing files into the wrong systems (because the resolver fell through to tier 3 heuristic).

When NOT to use

• The project has no .specify/systems/ directory at all — there's nothing to migrate. Use /smith Phase 4.8 (Optionally Scaffold System Specs) instead, or hand-author the first specs.
• The system specs already have paths: in their frontmatter — this skill skips them automatically (idempotent re-runs are a no-op), but there's no value in re-running.
• You want to migrate features (numbered spec folders) into the system hierarchy — that's /smith-migrate-specs, a different skill.

Behavior overview

This skill operates on .specify/systems/system-*/spec.md files in the current project. For each file:

1. Skip if it already has a non-empty paths: list in its YAML frontmatter (idempotency check).
2. Scan the prose body with a heuristic regex matcher (see scripts/propose_paths.py) to identify candidate path prefixes (services/<X>/, backend/<X>/, frontend/<X>/, apps/<X>/, packages/<X>/, backticked dirs, backticked files, bulleted paths, code-fenced file paths).
3. Score and rank each candidate by frequency × position_weight (earlier mentions in the file get higher weight — prose near the top is usually scope-defining).
4. Present the top-N proposals to the operator with each prefix's score, raw match count, and up to two line-quoted excerpts. The operator chooses Accept / Skip per system.
5. On accept, inject YAML frontmatter into the file:
   • If the file has NO frontmatter at all: prepend a fresh block (system, status, paths, also_affects) above the body, body preserved verbatim.
   • If the file has frontmatter WITHOUT paths:: insert only the paths: field inside the existing block, body preserved verbatim.
6. On skip, leave the file unchanged.