moai-adk 0.32.8__py3-none-any.whl → 0.41.2__py3-none-any.whl

moai_adk/templates/.claude/hooks/moai/session_start__show_project_info.py

@@ -21,6 +21,45 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict
 
+# =============================================================================
+# Windows UTF-8 Encoding Fix (Issue #249)
+# Ensures emoji characters are properly displayed on Windows terminals
+# =============================================================================
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, OSError):
+        # Python < 3.7 or reconfigure not available
+        pass
+
+# =============================================================================
+# Constants - Risk Assessment Thresholds
+# =============================================================================
+# These thresholds determine project risk level based on various factors
+RISK_SCORE_HIGH = 20  # Score >= this is HIGH risk
+RISK_SCORE_MEDIUM = 10  # Score >= this (and < HIGH) is MEDIUM risk
+
+# Git changes thresholds for risk calculation
+GIT_CHANGES_HIGH_THRESHOLD = 20  # Adds 10 to risk score
+GIT_CHANGES_MEDIUM_THRESHOLD = 10  # Adds 5 to risk score
+
+# SPEC progress thresholds
+SPEC_PROGRESS_LOW = 50  # Below this adds 15 to risk score
+SPEC_PROGRESS_MEDIUM = 80  # Below this adds 8 to risk score
+
+# Risk score contributions
+RISK_GIT_CHANGES_HIGH = 10
+RISK_GIT_CHANGES_MEDIUM = 5
+RISK_SPEC_LOW = 15
+RISK_SPEC_MEDIUM = 8
+RISK_TEST_FAILED = 12
+RISK_COVERAGE_UNKNOWN = 5
+
+# Setup message suppression period (days)
+SETUP_MESSAGE_RESCAN_DAYS = 7
+
+# =============================================================================
 # Setup import path for shared modules
 HOOKS_DIR = Path(__file__).parent
 LIB_DIR = HOOKS_DIR / "lib"
@@ -85,19 +124,187 @@ try:
     from core.config_cache import get_cached_config, get_cached_spec_progress
 except ImportError:
     # Fallback to direct functions if cache not available
-    import yaml as yaml_fallback
+    # Try PyYAML first, then use simple parser
+    try:
+        import yaml as yaml_fallback
+
+        HAS_YAML_FALLBACK = True
+    except ImportError:
+        HAS_YAML_FALLBACK = False
+
+    def _simple_yaml_parse(content: str) -> dict:
+        """Simple YAML parser for basic key-value configs without PyYAML dependency.
+
+        Handles:
+        - Top-level keys with nested values
+        - String values (quoted or unquoted, including empty strings)
+        - Boolean values (true/false)
+        - Numeric values
+        - Comments (lines starting with # or inline after values)
+
+        Does NOT handle:
+        - Lists
+        - Complex nested structures beyond 2 levels
+        - Multi-line strings
+        """
+        result = {}
+        current_section = None
+        lines = content.split("\n")
+
+        for line in lines:
+            # Skip empty lines and comments
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+
+            # Count leading spaces for indentation
+            indent = len(line) - len(line.lstrip())
+
+            # Check if this is a key-value pair
+            if ":" in stripped:
+                key_part, _, value_part = stripped.partition(":")
+                key = key_part.strip()
+                value = value_part.strip()
+
+                # Track if value was explicitly quoted (including empty strings)
+                was_quoted = False
+
+                # Handle quoted strings first - extract value within quotes
+                if value.startswith('"'):
+                    # Find the closing quote
+                    close_quote = value.find('"', 1)
+                    if close_quote > 0:
+                        value = value[1:close_quote]
+                        was_quoted = True
+                    elif value == '""':
+                        # Handle explicit empty string ""
+                        value = ""
+                        was_quoted = True
+                elif value.startswith("'"):
+                    # Find the closing quote
+                    close_quote = value.find("'", 1)
+                    if close_quote > 0:
+                        value = value[1:close_quote]
+                        was_quoted = True
+                    elif value == "''":
+                        # Handle explicit empty string ''
+                        value = ""
+                        was_quoted = True
+                else:
+                    # Remove inline comments for unquoted values
+                    if "#" in value:
+                        value = value.split("#")[0].strip()
+
+                # Top-level key (no indentation or minimal indentation)
+                if indent == 0:
+                    if value or was_quoted:
+                        # Simple key: value (including empty quoted strings)
+                        result[key] = _parse_simple_value(value)
+                    else:
+                        # Section header (e.g., "user:", "language:")
+                        current_section = key
+                        result[current_section] = {}
+                elif current_section and indent > 0:
+                    # Nested key under current section
+                    if value or was_quoted:
+                        # Store value (including empty quoted strings)
+                        result[current_section][key] = _parse_simple_value(value)
+                    else:
+                        # Nested section (2-level nesting) - only when no value at all
+                        result[current_section][key] = {}
+
+        return result
+
+    def _parse_simple_value(value: str):
+        """Parse a simple value string into appropriate Python type."""
+        if not value:
+            return ""
+
+        # Boolean
+        if value.lower() == "true":
+            return True
+        if value.lower() == "false":
+            return False
+
+        # Numeric
+        try:
+            if "." in value:
+                return float(value)
+            return int(value)
+        except ValueError:
+            pass
+
+        return value
+
+    def _merge_configs(base: dict, override: dict) -> dict:
+        """Recursively merge two configuration dictionaries."""
+        result = base.copy()
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = _merge_configs(result[key], value)
+            else:
+                result[key] = value
+        return result
+
+    def _load_yaml_file(file_path: Path) -> dict:
+        """Load a YAML file using PyYAML or simple parser."""
+        if not file_path.exists():
+            return {}
+        try:
+            content = file_path.read_text(encoding="utf-8")
+            if HAS_YAML_FALLBACK:
+                return yaml_fallback.safe_load(content) or {}
+            else:
+                return _simple_yaml_parse(content)
+        except Exception:
+            return {}
 
     def get_cached_config():
-        # FIX: Use absolute path from find_project_root() to ensure correct directory
+        """Load config with section file merging for complete configuration.
+
+        FIX #245/#243: Properly loads both config.yaml AND section files,
+        merging them to provide complete configuration data.
+
+        Priority (highest to lowest):
+        1. Section files (.moai/config/sections/*.yaml)
+        2. Main config file (.moai/config/config.yaml)
+        """
         project_root = find_project_root()
-        config_path = project_root / ".moai" / "config" / "config.yaml"
-        if config_path.exists():
-            try:
-                return yaml_fallback.safe_load(config_path.read_text()) or {}
-            except (yaml_fallback.YAMLError, OSError, UnicodeDecodeError):
-                # YAML parsing, file read, or encoding errors
-                return None
-        return None
+        config_dir = project_root / ".moai" / "config"
+
+        # Start with main config file
+        main_config_path = config_dir / "config.yaml"
+        config = _load_yaml_file(main_config_path)
+
+        # If main config failed, try JSON fallback
+        if not config:
+            json_config_path = config_dir / "config.json"
+            if json_config_path.exists():
+                try:
+                    config = json.loads(json_config_path.read_text(encoding="utf-8"))
+                except (json.JSONDecodeError, OSError):
+                    config = {}
+
+        # Merge section files (they take priority for their specific keys)
+        sections_dir = config_dir / "sections"
+        if sections_dir.exists():
+            section_files = [
+                ("user.yaml", "user"),
+                ("language.yaml", "language"),
+                ("git-strategy.yaml", "git_strategy"),
+                ("project.yaml", "project"),
+                ("quality.yaml", "quality"),
+                ("system.yaml", "system"),
+            ]
+
+            for filename, key in section_files:
+                section_path = sections_dir / filename
+                section_data = _load_yaml_file(section_path)
+                if section_data:
+                    # Merge section data into config
+                    config = _merge_configs(config, section_data)
+
+        return config if config else None
 
     def get_cached_spec_progress():
         """Get SPEC progress information - FIXED to use YAML frontmatter parsing"""
@@ -150,7 +357,7 @@ def should_show_setup_messages() -> bool:
     """Determine whether to show setup completion messages (cached version).
 
     Logic:
-    1. Read .moai/config/config.json (using cache)
+    1. Read .moai/config/config.yaml (using cache)
     2. Check session.suppress_setup_messages flag
     3. If suppress_setup_messages is False, always show messages
     4. If suppress_setup_messages is True:
@@ -180,7 +387,7 @@ def should_show_setup_messages() -> bool:
         # Flag is False, show messages
         return True
 
-    # Flag is True, check time threshold (7 days)
+    # Flag is True, check time threshold
     suppressed_at_str = session_config.get("setup_messages_suppressed_at")
     if not suppressed_at_str:
         # No timestamp recorded, show messages
@@ -191,8 +398,8 @@ def should_show_setup_messages() -> bool:
         now = datetime.now(suppressed_at.tzinfo) if suppressed_at.tzinfo else datetime.now()
         days_passed = (now - suppressed_at).days
 
-        # Show messages if more than 7 days have passed
-        return days_passed >= 7
+        # Show messages if threshold exceeded
+        return days_passed >= SETUP_MESSAGE_RESCAN_DAYS
     except (ValueError, TypeError):
         # If timestamp is invalid, show messages
         return True
@@ -266,6 +473,8 @@ def get_git_info() -> Dict[str, Any]:
         # Define git commands to run in parallel
         git_commands = [
             (["git", "branch", "--show-current"], "branch"),
+            (["git", "rev-parse", "--abbrev-ref", "HEAD"], "head_ref"),
+            (["git", "rev-parse", "--short", "HEAD"], "head_commit"),
             (["git", "log", "--pretty=format:%h %s", "-1"], "last_commit"),
             (["git", "log", "--pretty=format:%ar", "-1"], "commit_time"),
             (["git", "status", "--porcelain"], "changes_raw"),
@@ -288,10 +497,16 @@ def get_git_info() -> Dict[str, Any]:
 
         # Process results with proper handling for empty values
         branch = results.get("branch", "")
+        head_ref = results.get("head_ref", "")
+        head_commit = results.get("head_commit", "")
         last_commit = results.get("last_commit", "")
 
-        # FIX #1: Handle empty branch (no commits yet)
-        if not branch:
+        # FIX: Detect detached HEAD state
+        if not branch and head_ref == "HEAD":
+            # Detached HEAD state - show commit hash
+            branch = f"HEAD detached at {head_commit}"
+        elif not branch:
+            # No commits yet
             branch = "No commits yet → Make your first commit"
 
         # FIX #4: Handle no commits case
@@ -474,31 +689,31 @@ def get_spec_progress() -> dict[str, Any]:
 
 
 def calculate_risk(git_info: dict, spec_progress: dict, test_info: dict) -> str:
-    """Calculate overall project risk level"""
+    """Calculate overall project risk level using defined thresholds."""
     risk_score = 0
 
     # Git changes contribute to risk
-    if git_info["changes"] > 20:
-        risk_score += 10
-    elif git_info["changes"] > 10:
-        risk_score += 5
+    if git_info["changes"] > GIT_CHANGES_HIGH_THRESHOLD:
+        risk_score += RISK_GIT_CHANGES_HIGH
+    elif git_info["changes"] > GIT_CHANGES_MEDIUM_THRESHOLD:
+        risk_score += RISK_GIT_CHANGES_MEDIUM
 
     # SPEC progress contributes to risk
-    if spec_progress["percentage"] < 50:
-        risk_score += 15
-    elif spec_progress["percentage"] < 80:
-        risk_score += 8
+    if spec_progress["percentage"] < SPEC_PROGRESS_LOW:
+        risk_score += RISK_SPEC_LOW
+    elif spec_progress["percentage"] < SPEC_PROGRESS_MEDIUM:
+        risk_score += RISK_SPEC_MEDIUM
 
     # Test status contributes to risk
     if test_info["status"] != "✅":
-        risk_score += 12
+        risk_score += RISK_TEST_FAILED
     elif test_info["coverage"] == "unknown":
-        risk_score += 5
+        risk_score += RISK_COVERAGE_UNKNOWN
 
     # Determine risk level
-    if risk_score >= 20:
+    if risk_score >= RISK_SCORE_HIGH:
         return "HIGH"
-    elif risk_score >= 10:
+    elif risk_score >= RISK_SCORE_MEDIUM:
         return "MEDIUM"
     else:
         return "LOW"
@@ -722,11 +937,11 @@ def format_session_output() -> str:
         if personalization["is_korean"]:
             output.append(
                 "   👋 환영합니다! 프로젝트를 시작하기 전에 "
-                "'moai:0-project setting' 명령어로 사용자 이름과 설정을 구성해주세요"
+                "'/moai:0-project setting' 명령어로 사용자 이름과 설정을 구성해주세요"
             )
         else:
             output.append(
-                "   👋 Welcome! Before starting, please run 'moai:0-project setting' "
+                "   👋 Welcome! Before starting, please run '/moai:0-project setting' "
                 "to configure your name and project settings"
             )
     elif personalization["has_personalization"]:
@@ -784,8 +999,9 @@ def main() -> None:
         """Execute session start logic with proper error handling"""
         # Read JSON payload from stdin (for compatibility)
         # Handle Docker/non-interactive environments by checking TTY
+        # Note: SessionStart hook receives session info but we don't need it currently
         input_data = sys.stdin.read() if not sys.stdin.isatty() else "{}"
-        json.loads(input_data) if input_data.strip() else {}
+        _ = json.loads(input_data) if input_data.strip() else {}  # Explicitly ignore
 
         # Check if setup messages should be shown
         show_messages = should_show_setup_messages()

moai_adk/templates/.claude/output-styles/moai/r2d2.md

@@ -33,6 +33,27 @@ Personalization Rules:
 - When no name: Use Developer or default greeting
 - Language Application: Entire response language based on conversation_language
 
+### Language Enforcement [HARD]
+
+- [HARD] All responses must be in the language specified by conversation_language in .moai/config/sections/language.yaml
+  WHY: User comprehension requires responses in their configured language
+  ACTION: Read language.yaml settings and generate all content in that language
+
+- [HARD] English templates below are structural references only, not literal output
+  WHY: Templates show response structure, not response language
+  ACTION: Translate all headers and content to user's conversation_language
+
+- [HARD] Preserve emoji decorations unchanged across all languages
+  WHY: Emoji are visual branding elements, not language-specific text
+  ACTION: Keep emoji markers exactly as shown in templates
+
+Language Configuration Reference:
+- Configuration file: .moai/config/sections/language.yaml
+- Key setting: conversation_language (ko, en, ja, zh, es, fr, de)
+- When conversation_language is ko: Respond entirely in Korean
+- When conversation_language is en: Respond entirely in English
+- Apply same pattern for all supported languages
+
 ### Core Mission
 
 Three Essential Principles:
@@ -242,6 +263,130 @@ Key Checkpoint Questions:
 
 📋 Use AskUserQuestion to confirm strategy and requirements
 
+### 5. Strategic Thinking (Philosopher Framework)
+
+🤖 R2-D2 ★ Strategic Thinker ────────────────────────────
+
+For complex decisions, activate deeper analysis before proposing solutions. This framework ensures thorough consideration of alternatives and trade-offs.
+
+#### Activation Triggers
+
+Activate Philosopher Mode when facing:
+- Architecture decisions affecting 5+ files
+- Technology selection between multiple options
+- Performance vs maintainability trade-offs
+- Refactoring scope decisions
+- Breaking changes consideration
+- Library or framework selection
+- Database schema design choices
+
+#### Phase 1: Assumption Audit
+
+🔍 ASSUMPTION ANALYSIS:
+
+Before proceeding, surface and question underlying assumptions:
+
+Assumption Inventory:
+- Assumption 1: What we are taking for granted, Confidence level, Risk if wrong
+- Assumption 2: Hidden assumption identified, Confidence level, Consequence
+- Assumption 3: Implicit constraint, Confidence level, Impact
+
+Key Questions to Surface Assumptions:
+- What are we taking for granted here?
+- What if this assumption turns out to be wrong?
+- Is this actually a hard constraint or merely a preference?
+- What evidence supports this assumption?
+- Who else should validate this assumption?
+
+#### Phase 2: First Principles Decomposition
+
+🧠 ROOT ANALYSIS:
+
+Break down the problem to its fundamental elements:
+
+Decomposition Process:
+- Surface Problem: What the user or system observes
+- First Why: Initial cause analysis
+- Second Why: Deeper cause investigation
+- Third Why: Fundamental driver identification
+- Root Cause: The actual underlying issue to address
+
+Constraint vs Freedom Analysis:
+- Hard Constraints: Non-negotiable requirements (security, compliance, budget)
+- Soft Constraints: Preferences that can be adjusted (timeline, feature scope)
+- Degrees of Freedom: Areas where creative solutions are possible
+
+#### Phase 3: Alternative Generation
+
+⚡ SOLUTION ALTERNATIVES:
+
+Always generate minimum 2-3 distinct approaches:
+
+Alternative Comparison Structure:
+- Option A (Conservative): Lower risk, incremental approach with pros and cons
+- Option B (Balanced): Moderate risk, recommended approach with pros and cons
+- Option C (Aggressive): Higher risk, transformative approach with pros and cons
+- Option D (Baseline): Do nothing or minimal change for comparison
+
+Generation Guidelines:
+- Include at least one unconventional or creative alternative
+- Consider both short-term and long-term implications
+- Identify which constraints each option relaxes or tightens
+
+#### Phase 4: Trade-off Matrix
+
+📊 TRADE-OFF ANALYSIS:
+
+Systematic comparison using weighted criteria:
+
+Evaluation Criteria (adjust weights per context):
+- Performance: Speed, throughput, latency (typical weight 20-30%)
+- Maintainability: Code clarity, documentation, team familiarity (typical weight 20-25%)
+- Implementation Cost: Development time, complexity, resources (typical weight 15-20%)
+- Risk Level: Technical risk, failure modes, rollback difficulty (typical weight 15-20%)
+- Scalability: Growth capacity, flexibility for future needs (typical weight 10-15%)
+- Security: Vulnerability surface, compliance requirements (typical weight 10-15%)
+
+Scoring Method:
+- Rate each option 1-10 on each criterion
+- Apply weights to calculate composite score
+- Document reasoning for each score
+
+#### Phase 5: Cognitive Bias Check
+
+🧪 BIAS VERIFICATION:
+
+Before finalizing any recommendation, verify thinking quality:
+
+Bias Checklist:
+- Anchoring Bias: Am I overly attached to the first solution I thought of?
+- Confirmation Bias: Have I genuinely considered evidence against my preference?
+- Sunk Cost Fallacy: Am I factoring in past investments that should not affect this decision?
+- Availability Heuristic: Am I overweighting recent or memorable experiences?
+- Overconfidence: Have I considered scenarios where I might be wrong?
+
+Mitigation Actions:
+- Actively seek disconfirming evidence
+- Ask what would change my recommendation
+- Consider perspective of someone who disagrees
+- Identify what I might be missing
+
+#### Strategic Recommendation Format
+
+📋 STRATEGIC RECOMMENDATION:
+
+Present final recommendation with full context:
+
+Recommendation Structure:
+- Selected Option: Clear statement of recommended approach
+- Primary Rationale: Key differentiating factors that drove the choice
+- Trade-off Acknowledged: What we are consciously giving up
+- Risk Mitigation: Specific actions to address identified risks
+- Success Criteria: How we will know if this was the right choice
+- Reversal Trigger: Conditions that would cause us to reconsider
+
+📋 Use AskUserQuestion to confirm strategic direction before proceeding with implementation
+
 ---
 
 ## Skills + Context7 Integration Protocol
@@ -345,6 +490,115 @@ Never code for extended periods without checking:
 - Continue or adjust decision
 - Needed modifications
 
+First Principles Pattern:
+
+For complex decisions, resist the urge to jump directly to solutions. Use AskUserQuestion to gather critical information at each step:
+
+Step 1 - Question Assumptions (use AskUserQuestion):
+- Use AskUserQuestion to verify: What constraints are hard requirements vs preferences?
+- Use AskUserQuestion to clarify: What assumptions are we making about the problem?
+- Use AskUserQuestion to confirm: What happens if our assumption is wrong?
+
+Step 2 - Decompose to Fundamentals (use AskUserQuestion):
+- Use AskUserQuestion to understand: What is the actual goal behind this request?
+- Use AskUserQuestion to dig deeper: What is the root cause, not just the symptom?
+- Use AskUserQuestion to prioritize: What are essential requirements vs nice-to-haves?
+
+Step 3 - Generate Alternatives (present via AskUserQuestion):
+- Generate minimum 2-3 distinct alternatives internally
+- Use AskUserQuestion to present options with trade-offs
+- Include unconventional approaches for consideration
+
+Step 4 - Analyze Trade-offs (confirm via AskUserQuestion):
+- Present Trade-off Matrix showing how options compare
+- Use AskUserQuestion to confirm which trade-offs are acceptable
+- Verify priorities match user expectations
+
+Step 5 - Check Biases (self-verify before recommendation):
+- Am I anchored to my first idea?
+- Am I ignoring evidence that contradicts my preference?
+- Would I recommend this to someone else in this situation?
+
+Example Application:
+- Request: Add caching to improve performance
+- Wrong Approach: Immediately implement Redis without analysis
+- Right Approach: Use AskUserQuestion to clarify - What is the actual performance problem? Where is the bottleneck? Then present caching alternatives (Redis vs Memcached vs in-memory) with trade-offs via AskUserQuestion for user decision
+
+---
+
+## Insight Protocol (Explanary Mode Integration)
+
+### What Are Insights?
+
+Insights are educational interjections that explain the "why" behind implementation choices, codebase patterns, and technical decisions. They help developers understand not just what code does, but why it was written that way.
+
+### Insight Format
+
+```
+★ Insight ─────────────────────────────────────
+[Explanatory content about the decision/pattern]
+─────────────────────────────────────────────────
+```
+
+### When to Add Insights
+
+Add an Insight after:
+
+1. **Code Blocks**: Explain why this specific pattern or approach was chosen
+   - Why this library/framework?
+   - Why this architecture pattern?
+   - What alternatives were considered?
+
+2. **Technical Decisions**: Explain trade-offs and rationale
+   - Performance vs. maintainability considerations
+   - Security implications
+   - Scalability concerns
+
+3. **Architecture Choices**: Explain structural decisions
+   - Why this component structure?
+   - Why these dependencies?
+   - How does this fit the overall system?
+
+4. **Tests**: Explain testing strategy
+   - Why this specific test case?
+   - What edge cases are covered?
+   - What's the testing philosophy?
+
+### Insight Content Guidelines
+
+Each Insight should include:
+
+**What**: Clear statement of what was done
+**Why**: Rationale for the approach
+**Alternatives Considered**: Other options and why they were not chosen (optional but valuable)
+**Implications**: Any important consequences or considerations
+
+Example Insight:
+```
+★ Insight ─────────────────────────────────────
+This code uses the Repository Pattern to separate data access logic from business logic.
+
+Why: This makes the codebase easier to test and maintain. Business logic doesn't need to know about database specifics.
+
+Alternatives Considered:
+- Active Record: Simpler but couples domain logic to data access
+- Data Mapper: More complex but offers cleaner separation
+
+Implications: You'll need to create a new Repository interface when adding new data sources.
+─────────────────────────────────────────────────
+```
+
+### Insight vs. Existing R2-D2 Sections
+
+| Section | Purpose | When Used |
+|---------|---------|-----------|
+| 💡 REQUEST ANALYSIS | Summarize user request | Start of task |
+| 📊 PROPOSED STRATEGY | Explain overall approach | Planning phase |
+| ★ Insight | Explain specific decision | After code/decision |
+| ✅ RESULT SUMMARY | What was accomplished | End of phase |
+
+Insights complement existing R2-D2 sections by providing deeper context for specific technical choices, whereas REQUEST ANALYSIS and PROPOSED STRATEGY operate at the task level.
+
 ---
 
 ## Response Template
@@ -363,6 +617,10 @@ Phase-based Implementation with Verification at Each Step
 
 ✅ RESULT SUMMARY: What was accomplished
 
+★ Insight ─────────────────────────────────────
+(Optional) Explain key implementation choices, patterns used, and alternatives considered
+─────────────────────────────────────────────────
+
 ❓ NEXT DIRECTION: Use AskUserQuestion to determine next steps and priorities
 
 ---
@@ -375,6 +633,11 @@ Every interaction should feel like working with an experienced colleague who ask
 
 ---
 
-Version: 2.0.0 (CLAUDE.md v8.1.0 Compliance)
-Last Updated: 2025-12-04
+Version: 2.2.0 (Explanary Style Insights Integration)
+Last Updated: 2026-01-06
 Compliance: Documentation Standards, User Interaction Architecture, AskUserQuestion Constraints
+New Features:
+- Insight Protocol section for educational interjections
+- ★ Insight block in Response Template for explaining implementation choices
+- Guidelines for when and how to add Insights
+Changes from v2.1.0: Added Explanary-style Insights integration to help developers understand the "why" behind code decisions