fix: sync .metaspec/README.md for documentation consistency (v0.6.8)

CRITICAL BUG FIX: Documentation inconsistency after metaspec sync

Problem:
- metaspec sync only updated .metaspec/commands/
- Did NOT sync .metaspec/README.md
- After sync: commands use new naming (metaspec.evolution.*.md)
- But README referenced old naming (/metaspec.proposal, etc.)
- Result: Documentation contradicted actual files

Impact:
- Severity: CRITICAL - Misleading documentation
- Affected: All speckits using metaspec sync from v0.6.2+
- User confusion: Follow README but commands don't exist

Fix:
- Added Step 7.6 to sync.py: Update .metaspec/README.md
- Extract speckit name from pyproject.toml
- Render template with current version
- Updated README.md.j2 template: All Evolution references use new naming

Before (v0.6.7):
- metaspec sync → Updates commands but not README
- README shows: /metaspec.proposal
- User runs /metaspec.proposal → File not found!

After (v0.6.8):
- metaspec sync → Updates both commands AND README
- README shows: /metaspec.evolution.proposal
- Documentation and files consistent!

All 156 tests passing.

Credit: Bug discovered by user reviewing documentation consistency.

Author: NeilJo-GY

CHANGELOG.md

@@ -9,6 +9,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.6.8] - 2025-11-15
+
+### 🐛 Bug Fixes - Critical
+
+**Fixed Documentation Inconsistency in `metaspec sync`**
+
+Fixed a critical bug where `metaspec sync` updated command files but not `.metaspec/README.md`, causing documentation to reference old command names.
+
+**Problem**:
+- `metaspec sync` only synchronized `.metaspec/commands/` directory
+- Did NOT sync `.metaspec/README.md`
+- After sync: commands use new naming (`metaspec.evolution.*.md`)
+- But README still referenced old naming (`/metaspec.proposal`, etc.)
+- **Result**: Documentation contradicted actual files
+
+**Impact**: 🔴 Critical
+- Severity: High - Documentation misleads users
+- Affected: All speckits using `metaspec sync` from v0.6.2+
+- Confusion: Users follow README but commands don't exist
+
+**Fix**:
+- Added `.metaspec/README.md` to sync process (Step 7.6)
+- Extracts speckit name from `pyproject.toml`
+- Renders template with current version
+- Updates Evolution command references in template:
+  - `/metaspec.proposal` → `/metaspec.evolution.proposal`
+  - `/metaspec.apply` → `/metaspec.evolution.apply`
+  - `/metaspec.archive` → `/metaspec.evolution.archive`
+
+**Before (v0.6.7)**:
+```
+metaspec sync
+→ Updates .metaspec/commands/metaspec.evolution.*.md
+→ .metaspec/README.md still shows: /metaspec.proposal
+→ User runs /metaspec.proposal → File not found!
+```
+
+**After (v0.6.8)**:
+```
+metaspec sync
+→ Updates .metaspec/commands/metaspec.evolution.*.md
+→ Updates .metaspec/README.md → /metaspec.evolution.proposal
+→ Documentation and files consistent!
+```
+
+**Implementation**:
+- Modified `src/metaspec/cli/sync.py`:
+  - Added Step 7.6: Sync `.metaspec/README.md`
+  - Renders template with speckit name and version
+  - Increments updated files count
+- Updated template `src/metaspec/templates/base/.metaspec/README.md.j2`:
+  - All Evolution command references now use unified naming
+  - Examples updated to show correct commands
+
+**All 156 tests passing.**
+
+**Credit**: Bug discovered by user reviewing documentation consistency.
+
+---
+
 ## [0.6.7] - 2025-11-15
 
 ### ✨ Improvements

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "meta-spec"
-version = "0.6.7"
+version = "0.6.8"
 description = "Meta-specification framework for generating Spec-Driven X (SD-X) toolkits for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

src/metaspec/__init__.py

@@ -5,7 +5,7 @@
 from YAML definitions.
 """
 
-__version__ = "0.6.7"
+__version__ = "0.6.8"
 
 __all__ = ["__version__"]
 

src/metaspec/cli/sync.py

@@ -170,6 +170,29 @@ def sync_command(
             console.print(f"   🧹 Removing old naming (v0.5.x): {old_file_name}")
             old_file.unlink()
 
+    # Step 7.6: Update .metaspec/README.md (critical for consistency)
+    readme_source = template_dir.parent / "base" / ".metaspec" / "README.md.j2"
+    readme_dest = metaspec_dir / "README.md"
+    if readme_source.exists():
+        console.print(f"   📝 Updating {readme_dest.name}...")
+        content = readme_source.read_text()
+        # Render with speckit name from pyproject.toml
+        try:
+            with open("pyproject.toml", "rb") as f:
+                import tomllib
+                data = tomllib.load(f)
+                speckit_name = data.get("project", {}).get("name", "this speckit")
+                content = content.replace("{{ name }}", speckit_name)
+                content = content.replace("{{ metaspec_version }}", current_version)
+        except Exception:
+            # Fallback if pyproject.toml can't be read
+            content = content.replace("{{ name }}", "this speckit")
+            content = content.replace("{{ metaspec_version }}", current_version)
+
+        readme_dest.write_text(content)
+        updated_files.append(readme_dest.name)
+        console.print(f"   ✅ Updated {readme_dest.name}")
+
     # Step 8: Update version in pyproject.toml
     _update_generated_version(current_version)
 

src/metaspec/templates/base/.metaspec/README.md.j2

@@ -54,9 +54,9 @@ Develop toolkit implementation:
 
 Manage specification changes:
 
-- `/metaspec.proposal` - Propose changes (use `--type sds|sdd`)
-- `/metaspec.apply` - Apply approved changes
-- `/metaspec.archive` - Archive completed changes
+- `/metaspec.evolution.proposal` - Propose changes (use `--type sds|sdd`)
+- `/metaspec.evolution.apply` - Apply approved changes
+- `/metaspec.evolution.archive` - Archive completed changes
 
 **Output**: `changes/` directory
 
@@ -142,16 +142,16 @@ Manage specification changes:
 
 ```bash
 # Propose specification change
-/metaspec.proposal "Add GraphQL support" --type sds
+/metaspec.evolution.proposal "Add GraphQL support" --type sds
 
 # Propose toolkit change
-/metaspec.proposal "Add streaming support" --type sdd
+/metaspec.evolution.proposal "Add streaming support" --type sdd
 
 # Apply approved changes
-/metaspec.apply <proposal-id>
+/metaspec.evolution.apply <proposal-id>
 
 # Archive completed changes
-/metaspec.archive <proposal-id>
+/metaspec.evolution.archive <proposal-id>
 ```
 
 ---