fix: implement unified command naming pattern

Critical bug fix for duplicate Evolution commands

Changes:
1. Unified naming: metaspec.{group}.{command}.md for all commands
   - SDS: metaspec.sds.specify.md
   - SDD: metaspec.sdd.plan.md
   - Evolution: metaspec.evolution.apply.md (was: metaspec.apply.md)

2. Generator: Use unified naming from the start (metaspec init)
   - src/metaspec/generator.py: Evolution output path updated

3. Sync: Migrate v0.5.x projects automatically
   - src/metaspec/cli/sync.py: Remove old naming during sync
   - Prevents duplicate files (metaspec.apply.md + metaspec.evolution.apply.md)

4. Documentation: Update file structure examples
   - src/metaspec/templates/meta/README.md
   - src/metaspec/templates/README.md

Rationale:
- Consistent pattern across all command groups
- Better extensibility for future command groups
- Easier automation and tooling
- Clearer logical grouping

Breaking Change:
- v0.5.x users must run 'metaspec sync' to migrate naming
- Old files automatically cleaned up during sync

Resolves duplicate Evolution commands bug report

Author: NeilJo-GY

CHANGELOG.md

@@ -26,6 +26,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **Root Cause**: Code only checked for `FileSystemLoader`, but Generator uses `PackageLoader` in editable installs
 
+**Unified Command Naming (Breaking Change for v0.5.x users)**
+- Unified naming pattern for all command groups: `metaspec.{group}.{command}.md`
+- Evolution commands now use: `metaspec.evolution.apply.md` (previously `metaspec.apply.md`)
+- Rationale: Consistent naming pattern across all command groups (SDS, SDD, Evolution)
+- Benefits: ✅ Unified pattern, ✅ Better extensibility, ✅ Easier automation, ✅ Clearer grouping
+- Migration: `metaspec sync` automatically removes old v0.5.x naming and installs new naming
+- **Action Required**: If upgrading from v0.5.x, run `metaspec sync` to migrate naming
+
 ---
 
 ## [0.6.0] - 2025-11-14

src/metaspec/cli/sync.py

@@ -150,6 +150,7 @@ def sync_command(
 
         for source_file in source_dir.glob("*.md.j2"):
             # Remove .j2 extension for destination
+            # Unified naming: metaspec.{group}.{command}.md
             dest_file = commands_dir / f"metaspec.{command_group}.{source_file.stem}"
 
             # Read and render template (basic rendering, no complex logic)
@@ -160,6 +161,15 @@ def sync_command(
             dest_file.write_text(content)
             updated_files.append(dest_file.name)
 
+    # Step 7.5: Clean up old Evolution naming (v0.5.x → v0.6.x migration)
+    # Remove old naming pattern from pre-v0.6.0 versions
+    old_evolution_files = ["metaspec.apply.md", "metaspec.archive.md", "metaspec.proposal.md"]
+    for old_file_name in old_evolution_files:
+        old_file = commands_dir / old_file_name
+        if old_file.exists():
+            console.print(f"   🧹 Removing old naming (v0.5.x): {old_file_name}")
+            old_file.unlink()
+
     # Step 8: Update version in pyproject.toml
     _update_generated_version(current_version)
 

src/metaspec/generator.py

@@ -329,7 +329,7 @@ def _select_templates(self, meta_spec: MetaSpecDefinition) -> dict[str, str]:
             template_map[source_path] = output_path
 
         # Evolution commands (3): Shared specification evolution commands
-        # File naming: metaspec.{command}.md to use /metaspec.{command} prefix
+        # File naming: metaspec.evolution.{command}.md (unified naming pattern)
         # These commands support both SDS and SDD through --type parameter
         evolution_commands = [
             "proposal",  # Propose changes (SDS or SDD)
@@ -339,7 +339,7 @@ def _select_templates(self, meta_spec: MetaSpecDefinition) -> dict[str, str]:
 
         for cmd in evolution_commands:
             source_path = f"meta/evolution/commands/{cmd}.md.j2"
-            output_path = f".metaspec/commands/metaspec.{cmd}.md"
+            output_path = f".metaspec/commands/metaspec.evolution.{cmd}.md"
             template_map[source_path] = output_path
 
         # MetaSpec README.md (Developer guide for speckit developers)

src/metaspec/templates/README.md

@@ -206,7 +206,7 @@ my-speckit/
     │   ├── metaspec.sds.plan.md            # from meta/sds/commands/
     │   ├── metaspec.sdd.constitution.md    # from meta/sdd/commands/
     │   ├── metaspec.sdd.plan.md            # from meta/sdd/commands/
-    │   ├── metaspec.proposal.md            # from meta/evolution/commands/
+    │   ├── metaspec.evolution.proposal.md  # from meta/evolution/commands/
     │   └── ... (19 commands total: 8 SDS + 8 SDD + 3 Evolution)
     └── templates/
         ├── constitution-template.md   # from meta/templates/

src/metaspec/templates/meta/README.md

@@ -198,9 +198,9 @@ generated-speckit/
 │       ├── metaspec.sdd.checklist.md
 │       ├── metaspec.sdd.analyze.md
 │       │
-│       ├── metaspec.proposal.md           ← Evolution commands
-│       ├── metaspec.apply.md
-│       └── metaspec.archive.md
+│       ├── metaspec.evolution.proposal.md ← Evolution commands
+│       ├── metaspec.evolution.apply.md
+│       └── metaspec.evolution.archive.md
 │
 ├── specs/
 │   ├── domain/    ← SDS output (domain specifications)