moai-adk 0.8.1__tar.gz → 0.8.3__tar.gz

{moai_adk-0.8.1 → moai_adk-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.8.1
+Version: 0.8.3
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -255,7 +255,7 @@ my-project/
 │   │       ├── 1-plan.md           # SPEC authoring
 │   │       ├── 2-run.md            # TDD implementation
 │   │       └── 3-sync.md           # Documentation sync
-│   ├── skills/                     # 58 Claude Skills
+│   ├── skills/                     # 55+ Claude Skills
 │   │   ├── moai-foundation-*       # 6 Foundation tier
 │   │   ├── moai-essentials-*       # 4 Essentials tier
 │   │   ├── moai-alfred-*           # 7 Alfred tier
@@ -617,7 +617,7 @@ uv tool update
 
 ```bash
 # Reinstall specific version (e.g., 0.4.2)
-uv tool install moai-adk==0.4.2
+uv tool install moai-adk
 ```
 
 ### Verify After Update
@@ -646,6 +646,231 @@ claude
 
 ---
 
+## Development Setup for Contributors
+
+If you're developing **MoAI-ADK itself**, follow these steps to set up your development environment.
+
+### Prerequisites
+
+- Python 3.13+
+- `uv` package manager
+- Git
+
+### Setup Steps
+
+#### Step 1: Clone and Install in Editable Mode
+
+```bash
+# Clone the repository
+git clone https://github.com/modu-ai/moai-adk.git
+cd moai-adk
+
+# Install in editable mode (creates symlink, not a copy)
+uv pip install -e .
+
+# Or with pip (also works)
+pip install -e .
+```
+
+The editable install allows your local changes to be immediately reflected when using `moai-adk` command.
+
+#### Step 2: Initialize Development Configuration
+
+After the editable install, initialize the development repository's configuration:
+
+```bash
+# Run the initialization script
+bash .moai/scripts/init-dev-config.sh
+```
+
+**What this script does:**
+- Extracts the actual version from `pyproject.toml`
+- Replaces template placeholders (`{{MOAI_VERSION}}`) with actual version values in `.moai/config.json`
+- Sets up `project.template_version` field
+- Ensures the `moai-adk update` command works correctly on first run
+
+**Why is this necessary?**
+
+When you install MoAI-ADK in editable mode, the `.moai/config.json` file contains unsubstituted template placeholders. This causes the first `moai-adk update` command to fail with version comparison errors. The init script resolves these placeholders so everything works seamlessly.
+
+#### Step 3: Verify Setup
+
+```bash
+# Check that moai-adk works
+moai-adk --version
+
+# Run the health check
+moai-adk doctor
+
+# Expected output:
+# ✅ Python version: 3.13+
+# ✅ UV installed
+# ✅ Project structure: Valid
+# ✅ Configuration: Ready
+```
+
+#### Step 4: Run Tests
+
+```bash
+# Run all tests with coverage
+pytest tests/
+
+# Run specific test module
+pytest tests/unit/test_update.py -v
+
+# Run with coverage report
+pytest tests/ --cov=src/moai_adk --cov-report=html
+
+# Check coverage thresholds
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+```
+
+### Common Development Workflow
+
+#### After Making Code Changes
+
+```bash
+# 1. Run tests to ensure nothing broke
+pytest tests/ -v
+
+# 2. Check code style
+ruff check src/
+ruff format src/
+
+# 3. Type checking
+mypy src/
+
+# 4. If you modified update.py, test the update command
+moai-adk update --check
+```
+
+#### Testing the Update Command
+
+The update command has been fixed to handle invalid version strings gracefully. To test it in development:
+
+```bash
+# Test update without applying it
+moai-adk update --check
+
+# Test with force mode (skips backup)
+moai-adk update --force
+
+# Test with specific version
+moai-adk update --templates-only
+```
+
+### Understanding the Init Script
+
+The `.moai/scripts/init-dev-config.sh` script performs these operations:
+
+1. **Extracts Version**: Reads `pyproject.toml` to get the current version
+2. **Updates Config**: Modifies `.moai/config.json` to set:
+   - `moai.version` → actual version value
+   - `project.template_version` → actual version value
+3. **Validates**: Ensures the JSON structure is preserved correctly
+4. **Provides Feedback**: Shows what was updated and verifies the changes
+
+### Troubleshooting Development Setup
+
+#### Problem: `moai-adk` command not found
+
+```bash
+# Solution 1: Reinstall in editable mode
+uv pip install -e .
+
+# Solution 2: Verify uv environment
+uv pip list | grep moai-adk
+
+# Solution 3: Use full path
+python -m moai_adk --version
+```
+
+#### Problem: `.moai/config.json` still has placeholders after running init script
+
+```bash
+# Manually check the config
+cat .moai/config.json | grep -i moai_version
+
+# If still showing {{MOAI_VERSION}}, rerun the script:
+bash .moai/scripts/init-dev-config.sh
+
+# Or manually update using Python:
+python3 << 'EOF'
+import json
+from pathlib import Path
+
+config_path = Path(".moai/config.json")
+config = json.loads(config_path.read_text())
+
+# Update manually
+config['moai']['version'] = "0.8.1"
+config['project']['template_version'] = "0.8.1"
+
+config_path.write_text(json.dumps(config, indent=2) + '\n')
+print("✅ Config updated manually")
+EOF
+```
+
+#### Problem: `moai-adk update` requires running twice
+
+This issue has been **fixed** in v0.8.1+. If you're experiencing this:
+
+1. Ensure you've run the init script: `bash .moai/scripts/init-dev-config.sh`
+2. Update to the latest version: `pip install -e --upgrade .`
+3. Verify the config has actual versions: `cat .moai/config.json | grep version`
+
+**What was the issue?**
+- Development installations had unsubstituted `{{MOAI_VERSION}}` placeholders in config
+- First `moai-adk update` would fail comparing "0.8.1" vs "{{MOAI_VERSION}}"
+- Second run might partially work after partial sync
+
+**How it's fixed:**
+- `init-dev-config.sh` replaces placeholders with actual versions
+- Code now gracefully handles InvalidVersion exceptions
+- Added comprehensive unit tests for placeholder detection
+
+### Contributing Tests
+
+When adding new features, always include tests:
+
+```bash
+# Add tests to tests/unit/ or tests/integration/
+# Follow existing test patterns in test_update.py
+
+# Run your new tests
+pytest tests/unit/test_*.py -v
+
+# Ensure coverage remains ≥ 85%
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+```
+
+### Making a Pull Request
+
+Before opening a PR, ensure:
+
+```bash
+# 1. All tests pass
+pytest tests/ -v
+
+# 2. Coverage is adequate
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+
+# 3. Code is formatted
+ruff format src/
+ruff check src/
+
+# 4. Types are valid
+mypy src/
+
+# 5. Init script works
+bash .moai/scripts/init-dev-config.sh
+
+# 6. Update command works
+moai-adk update --check
+```
+
+---
+
 ## Core Workflow (0 → 3)
 
 Alfred iteratively develops projects with four commands.
@@ -1643,7 +1868,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
-**TAG Guard (New in v0.4.11)**:
+**TAG Guard**:
 Automatically detects missing @TAG annotations in changed files:
 
 - Scans staged, modified, and untracked files
@@ -1774,15 +1999,16 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.8.2**  | 📖 EARS terminology update: "Constraints" → "Unwanted Behaviors" for clarity                     | 2025-10-29 |
+| **v0.8.1**  | 🔄 Command rename: `/alfred:9-help` → `/alfred:9-feedback` + User feedback workflow improvements | 2025-10-28 |
+| **v0.8.0**  | 🏷️ @DOC TAG auto-generation system + SessionStart version check enhancement                      | 2025-10-27 |
+| **v0.7.0**  | 🌍 Complete language localization system (English, Korean, Japanese, Chinese, Spanish)           | 2025-10-26 |
+| **v0.6.3**  | ⚡ 3-Stage update workflow: 70-80% performance improvement via parallel operations               | 2025-10-25 |
+| **v0.6.0**  | 🏗️ Major architecture refactor + Enhanced SPEC metadata structure (7 required + 9 optional)      | 2025-10-24 |
 | **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
-| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config             | 2025-10-23 |
-| **v0.4.9**  | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)                     | 2025-10-23 |
-| **v0.4.8**  | 🚀 Release automation + PyPI deployment + Skills refinement                                      | 2025-10-23 |
-| **v0.4.7**  | 📖 Korean language optimization + SPEC-First principle documentation                             | 2025-10-22 |
-| **v0.4.6**  | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
 
-> 📦 **Install Now**: `uv tool install moai-adk==0.4.11` or `pip install moai-adk==0.4.11`
+> 📦 **Install Now**: `uv tool install moai-adk` or `pip install moai-adk`
 
 ---
 
@@ -1790,7 +2016,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Purpose                   | Resource                                                        |
 | ------------------------- | --------------------------------------------------------------- |
-| Skills detailed structure | `.claude/skills/` directory (58 Skills)                         |
+| Skills detailed structure | `.claude/skills/` directory (55+ Skills)                         |
 | Sub-agent details         | `.claude/agents/alfred/` directory (12 agents)                  |
 | Workflow guide            | `.claude/commands/alfred/` (4 commands: 0-project ~ 3-sync)     |
 | Documentation             | Coming soon (see `.moai/`, `.claude/`, `docs/` in your project) |
@@ -1804,8 +2030,8 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | ------------------------ | -------------------------------------------------------- |
 | **GitHub Repository**    | https://github.com/modu-ai/moai-adk                      |
 | **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues               |
-| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.11)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/                       |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases             |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project         |
 
 ---
@@ -1814,7 +2040,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 > **"No CODE without SPEC"**
 
-MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 56 Claude Skills together guarantee:
+MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 55+ Claude Skills together guarantee:
 
 - ✅ **SPEC → TEST (TDD) → CODE → DOCS consistency**
 - ✅ **Complete history tracking with @TAG system**

{moai_adk-0.8.1 → moai_adk-0.8.3}/README.md

@@ -215,7 +215,7 @@ my-project/
 │   │       ├── 1-plan.md           # SPEC authoring
 │   │       ├── 2-run.md            # TDD implementation
 │   │       └── 3-sync.md           # Documentation sync
-│   ├── skills/                     # 58 Claude Skills
+│   ├── skills/                     # 55+ Claude Skills
 │   │   ├── moai-foundation-*       # 6 Foundation tier
 │   │   ├── moai-essentials-*       # 4 Essentials tier
 │   │   ├── moai-alfred-*           # 7 Alfred tier
@@ -577,7 +577,7 @@ uv tool update
 
 ```bash
 # Reinstall specific version (e.g., 0.4.2)
-uv tool install moai-adk==0.4.2
+uv tool install moai-adk
 ```
 
 ### Verify After Update
@@ -606,6 +606,231 @@ claude
 
 ---
 
+## Development Setup for Contributors
+
+If you're developing **MoAI-ADK itself**, follow these steps to set up your development environment.
+
+### Prerequisites
+
+- Python 3.13+
+- `uv` package manager
+- Git
+
+### Setup Steps
+
+#### Step 1: Clone and Install in Editable Mode
+
+```bash
+# Clone the repository
+git clone https://github.com/modu-ai/moai-adk.git
+cd moai-adk
+
+# Install in editable mode (creates symlink, not a copy)
+uv pip install -e .
+
+# Or with pip (also works)
+pip install -e .
+```
+
+The editable install allows your local changes to be immediately reflected when using `moai-adk` command.
+
+#### Step 2: Initialize Development Configuration
+
+After the editable install, initialize the development repository's configuration:
+
+```bash
+# Run the initialization script
+bash .moai/scripts/init-dev-config.sh
+```
+
+**What this script does:**
+- Extracts the actual version from `pyproject.toml`
+- Replaces template placeholders (`{{MOAI_VERSION}}`) with actual version values in `.moai/config.json`
+- Sets up `project.template_version` field
+- Ensures the `moai-adk update` command works correctly on first run
+
+**Why is this necessary?**
+
+When you install MoAI-ADK in editable mode, the `.moai/config.json` file contains unsubstituted template placeholders. This causes the first `moai-adk update` command to fail with version comparison errors. The init script resolves these placeholders so everything works seamlessly.
+
+#### Step 3: Verify Setup
+
+```bash
+# Check that moai-adk works
+moai-adk --version
+
+# Run the health check
+moai-adk doctor
+
+# Expected output:
+# ✅ Python version: 3.13+
+# ✅ UV installed
+# ✅ Project structure: Valid
+# ✅ Configuration: Ready
+```
+
+#### Step 4: Run Tests
+
+```bash
+# Run all tests with coverage
+pytest tests/
+
+# Run specific test module
+pytest tests/unit/test_update.py -v
+
+# Run with coverage report
+pytest tests/ --cov=src/moai_adk --cov-report=html
+
+# Check coverage thresholds
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+```
+
+### Common Development Workflow
+
+#### After Making Code Changes
+
+```bash
+# 1. Run tests to ensure nothing broke
+pytest tests/ -v
+
+# 2. Check code style
+ruff check src/
+ruff format src/
+
+# 3. Type checking
+mypy src/
+
+# 4. If you modified update.py, test the update command
+moai-adk update --check
+```
+
+#### Testing the Update Command
+
+The update command has been fixed to handle invalid version strings gracefully. To test it in development:
+
+```bash
+# Test update without applying it
+moai-adk update --check
+
+# Test with force mode (skips backup)
+moai-adk update --force
+
+# Test with specific version
+moai-adk update --templates-only
+```
+
+### Understanding the Init Script
+
+The `.moai/scripts/init-dev-config.sh` script performs these operations:
+
+1. **Extracts Version**: Reads `pyproject.toml` to get the current version
+2. **Updates Config**: Modifies `.moai/config.json` to set:
+   - `moai.version` → actual version value
+   - `project.template_version` → actual version value
+3. **Validates**: Ensures the JSON structure is preserved correctly
+4. **Provides Feedback**: Shows what was updated and verifies the changes
+
+### Troubleshooting Development Setup
+
+#### Problem: `moai-adk` command not found
+
+```bash
+# Solution 1: Reinstall in editable mode
+uv pip install -e .
+
+# Solution 2: Verify uv environment
+uv pip list | grep moai-adk
+
+# Solution 3: Use full path
+python -m moai_adk --version
+```
+
+#### Problem: `.moai/config.json` still has placeholders after running init script
+
+```bash
+# Manually check the config
+cat .moai/config.json | grep -i moai_version
+
+# If still showing {{MOAI_VERSION}}, rerun the script:
+bash .moai/scripts/init-dev-config.sh
+
+# Or manually update using Python:
+python3 << 'EOF'
+import json
+from pathlib import Path
+
+config_path = Path(".moai/config.json")
+config = json.loads(config_path.read_text())
+
+# Update manually
+config['moai']['version'] = "0.8.1"
+config['project']['template_version'] = "0.8.1"
+
+config_path.write_text(json.dumps(config, indent=2) + '\n')
+print("✅ Config updated manually")
+EOF
+```
+
+#### Problem: `moai-adk update` requires running twice
+
+This issue has been **fixed** in v0.8.1+. If you're experiencing this:
+
+1. Ensure you've run the init script: `bash .moai/scripts/init-dev-config.sh`
+2. Update to the latest version: `pip install -e --upgrade .`
+3. Verify the config has actual versions: `cat .moai/config.json | grep version`
+
+**What was the issue?**
+- Development installations had unsubstituted `{{MOAI_VERSION}}` placeholders in config
+- First `moai-adk update` would fail comparing "0.8.1" vs "{{MOAI_VERSION}}"
+- Second run might partially work after partial sync
+
+**How it's fixed:**
+- `init-dev-config.sh` replaces placeholders with actual versions
+- Code now gracefully handles InvalidVersion exceptions
+- Added comprehensive unit tests for placeholder detection
+
+### Contributing Tests
+
+When adding new features, always include tests:
+
+```bash
+# Add tests to tests/unit/ or tests/integration/
+# Follow existing test patterns in test_update.py
+
+# Run your new tests
+pytest tests/unit/test_*.py -v
+
+# Ensure coverage remains ≥ 85%
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+```
+
+### Making a Pull Request
+
+Before opening a PR, ensure:
+
+```bash
+# 1. All tests pass
+pytest tests/ -v
+
+# 2. Coverage is adequate
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+
+# 3. Code is formatted
+ruff format src/
+ruff check src/
+
+# 4. Types are valid
+mypy src/
+
+# 5. Init script works
+bash .moai/scripts/init-dev-config.sh
+
+# 6. Update command works
+moai-adk update --check
+```
+
+---
+
 ## Core Workflow (0 → 3)
 
 Alfred iteratively develops projects with four commands.
@@ -1603,7 +1828,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
-**TAG Guard (New in v0.4.11)**:
+**TAG Guard**:
 Automatically detects missing @TAG annotations in changed files:
 
 - Scans staged, modified, and untracked files
@@ -1734,15 +1959,16 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.8.2**  | 📖 EARS terminology update: "Constraints" → "Unwanted Behaviors" for clarity                     | 2025-10-29 |
+| **v0.8.1**  | 🔄 Command rename: `/alfred:9-help` → `/alfred:9-feedback` + User feedback workflow improvements | 2025-10-28 |
+| **v0.8.0**  | 🏷️ @DOC TAG auto-generation system + SessionStart version check enhancement                      | 2025-10-27 |
+| **v0.7.0**  | 🌍 Complete language localization system (English, Korean, Japanese, Chinese, Spanish)           | 2025-10-26 |
+| **v0.6.3**  | ⚡ 3-Stage update workflow: 70-80% performance improvement via parallel operations               | 2025-10-25 |
+| **v0.6.0**  | 🏗️ Major architecture refactor + Enhanced SPEC metadata structure (7 required + 9 optional)      | 2025-10-24 |
 | **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
-| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config             | 2025-10-23 |
-| **v0.4.9**  | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)                     | 2025-10-23 |
-| **v0.4.8**  | 🚀 Release automation + PyPI deployment + Skills refinement                                      | 2025-10-23 |
-| **v0.4.7**  | 📖 Korean language optimization + SPEC-First principle documentation                             | 2025-10-22 |
-| **v0.4.6**  | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
 
-> 📦 **Install Now**: `uv tool install moai-adk==0.4.11` or `pip install moai-adk==0.4.11`
+> 📦 **Install Now**: `uv tool install moai-adk` or `pip install moai-adk`
 
 ---
 
@@ -1750,7 +1976,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Purpose                   | Resource                                                        |
 | ------------------------- | --------------------------------------------------------------- |
-| Skills detailed structure | `.claude/skills/` directory (58 Skills)                         |
+| Skills detailed structure | `.claude/skills/` directory (55+ Skills)                         |
 | Sub-agent details         | `.claude/agents/alfred/` directory (12 agents)                  |
 | Workflow guide            | `.claude/commands/alfred/` (4 commands: 0-project ~ 3-sync)     |
 | Documentation             | Coming soon (see `.moai/`, `.claude/`, `docs/` in your project) |
@@ -1764,8 +1990,8 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | ------------------------ | -------------------------------------------------------- |
 | **GitHub Repository**    | https://github.com/modu-ai/moai-adk                      |
 | **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues               |
-| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.11)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/                       |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases             |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project         |
 
 ---
@@ -1774,7 +2000,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 > **"No CODE without SPEC"**
 
-MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 56 Claude Skills together guarantee:
+MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 55+ Claude Skills together guarantee:
 
 - ✅ **SPEC → TEST (TDD) → CODE → DOCS consistency**
 - ✅ **Complete history tracking with @TAG system**

{moai_adk-0.8.1 → moai_adk-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.8.1"
+version = "0.8.3"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0"
 readme = "README.md"
 requires-python = ">=3.13"

{moai_adk-0.8.1 → moai_adk-0.8.3}/src/moai_adk/cli/commands/update.py

@@ -274,6 +274,10 @@ def _get_project_config_version(project_path: Path) -> str:
     Raises:
         ValueError: If config.json exists but cannot be parsed
     """
+    def _is_placeholder(value: str) -> bool:
+        """Check if value contains unsubstituted template placeholders."""
+        return isinstance(value, str) and value.startswith("{{") and value.endswith("}}")
+
     config_path = project_path / ".moai" / "config.json"
 
     if not config_path.exists():
@@ -284,15 +288,15 @@ def _get_project_config_version(project_path: Path) -> str:
         config_data = json.loads(config_path.read_text(encoding="utf-8"))
         # Check for template_version in project section
         template_version = config_data.get("project", {}).get("template_version")
-        if template_version:
+        if template_version and not _is_placeholder(template_version):
             return template_version
 
         # Fallback to moai version if no template_version exists
         moai_version = config_data.get("moai", {}).get("version")
-        if moai_version:
+        if moai_version and not _is_placeholder(moai_version):
             return moai_version
 
-        # If neither exists, this is a new/old project
+        # If values are placeholders or don't exist, treat as uninitialized (0.0.0 triggers sync)
         return "0.0.0"
     except json.JSONDecodeError as e:
         raise ValueError(f"Failed to parse project config.json: {e}") from e
@@ -796,7 +800,14 @@ def update(path: str, force: bool, check: bool, templates_only: bool, yes: bool)
         console.print(f"   Package template: {package_config_version}")
         console.print(f"   Project config:   {project_config_version}")
 
-        config_comparison = _compare_versions(package_config_version, project_config_version)
+        try:
+            config_comparison = _compare_versions(package_config_version, project_config_version)
+        except version.InvalidVersion as e:
+            # Handle invalid version strings (e.g., unsubstituted template placeholders, corrupted configs)
+            console.print(f"[yellow]⚠ Invalid version format in config: {e}[/yellow]")
+            console.print("[cyan]ℹ️  Forcing template sync to repair configuration...[/cyan]")
+            # Force template sync by treating project version as outdated
+            config_comparison = 1  # package_config_version > project_config_version
 
         # If versions are equal, no sync needed
         if config_comparison <= 0:

{moai_adk-0.8.1 → moai_adk-0.8.3}/src/moai_adk/core/config/migration.py

@@ -34,7 +34,7 @@ def migrate_config_to_nested_structure(config: dict[str, Any]) -> dict[str, Any]
     if "conversation_language" in config and "language" not in config:
         # Extract conversation language from legacy location
         conversation_language = config.pop("conversation_language", "en")
-        locale = config.pop("locale", None)
+        config.pop("locale", None)  # Remove legacy locale field
 
         # Map language codes to language names
         language_names = {