bc-code-intelligence-mcp 1.5.9 → 1.6.1

package/embedded-knowledge/domains/uma-ux/shortcut-key-user-experience-design.md

@@ -1,11 +1,21 @@
----
+---
 title: "Shortcut Key User Experience Design in Business Central Applications"
 domain: "uma-ux"
 difficulty: "intermediate"
 bc_versions: "14+"
 tags: ["user-experience", "shortcuts", "workflow-optimization", "productivity", "interface-design"]
 prerequisites: ["user-interface-design", "bc-actions"]
----
+
+relevance_signals:
+  constructs: ["ShortcutKey", "ToolTip", "Caption", "ApplicationArea", "Promoted"]
+  keywords: ["user experience", "shortcut", "workflow optimization", "productivity", "keyboard navigation", "progressive disclosure", "cognitive load", "discoverability", "power user"]
+  anti_pattern_indicators: ["overcomplex combinations", "hidden functionality", "inconsistent behavior", "conflict creation", "no visual feedback"]
+  positive_pattern_indicators: ["workflow analysis", "frequency-based prioritization", "memorable patterns", "visual cues", "help integration", "progressive revelation"]
+
+applicable_object_types: ["page", "pageextension"]
+
+relevance_threshold: 0.4
+---
 # Shortcut Key User Experience Design in Business Central Applications
 
 ## Overview

package/embedded-knowledge/scripts/frontmatter_validator.ps1

@@ -0,0 +1,330 @@
+# frontmatter_validator.ps1
+# Validates knowledge file frontmatter against v2 schema requirements
+
+param(
+    [string]$Path = "..\domains",
+    [switch]$ExcludeSamples = $true,
+    [switch]$V2Only = $false  # Only check v2 fields, skip files without them
+)
+
+$script:ErrorCount = 0
+$script:WarningCount = 0
+$script:ValidCount = 0
+$script:SkippedCount = 0
+
+function Write-ValidationError {
+    param([string]$File, [string]$Message)
+    Write-Host "  ERROR: $Message" -ForegroundColor Red
+    $script:ErrorCount++
+}
+
+function Write-ValidationWarning {
+    param([string]$File, [string]$Message)
+    Write-Host "  WARN:  $Message" -ForegroundColor Yellow
+    $script:WarningCount++
+}
+
+function Test-IsArray {
+    param($Value)
+    return $Value -is [System.Collections.IEnumerable] -and $Value -isnot [string]
+}
+
+function Test-IsArrayOfStrings {
+    param($Value)
+    if (-not (Test-IsArray $Value)) { return $false }
+    foreach ($item in $Value) {
+        if ($item -isnot [string]) { return $false }
+    }
+    return $true
+}
+
+function Parse-YamlFrontmatter {
+    param([string]$Content)
+
+    # Extract frontmatter between --- markers
+    if ($Content -notmatch '^---\s*\r?\n([\s\S]*?)\r?\n---') {
+        return $null
+    }
+
+    $yamlContent = $Matches[1]
+    $result = @{}
+    $currentKey = $null
+    $currentIndent = 0
+    $inArray = $false
+    $arrayKey = $null
+    $nestedObject = $null
+    $nestedKey = $null
+
+    foreach ($line in $yamlContent -split '\r?\n') {
+        # Skip comments only - blank lines reset nested context but don't skip
+        if ($line -match '^\s*#') { continue }
+
+        # Blank lines reset nested object context (back to top level)
+        if ($line -match '^\s*$') {
+            $nestedObject = $null
+            $nestedKey = $null
+            $currentKey = $null
+            $arrayKey = $null
+            continue
+        }
+
+        # Detect indent level
+        $indent = 0
+        if ($line -match '^(\s*)') {
+            $indent = $Matches[1].Length
+        }
+
+        $trimmedLine = $line.Trim()
+
+        # Array item
+        if ($trimmedLine -match '^-\s*(.*)$') {
+            $value = $Matches[1].Trim()
+            # Remove quotes if present
+            if ($value -match '^[''"](.*)[''"]\s*$') {
+                $value = $Matches[1]
+            }
+            if ($nestedKey -and $nestedObject) {
+                if (-not $nestedObject[$nestedKey]) {
+                    $nestedObject[$nestedKey] = @()
+                }
+                $nestedObject[$nestedKey] += $value
+            } elseif ($arrayKey) {
+                if (-not $result[$arrayKey]) {
+                    $result[$arrayKey] = @()
+                }
+                $result[$arrayKey] += $value
+            }
+            continue
+        }
+
+        # Key-value pair
+        if ($trimmedLine -match '^([^:]+):\s*(.*)$') {
+            $key = $Matches[1].Trim()
+            $value = $Matches[2].Trim()
+
+            # Remove quotes if present
+            if ($value -match '^[''"](.*)[''"]\s*$') {
+                $value = $Matches[1]
+            }
+
+            # Check if this is a nested object key (indented under another key)
+            if ($indent -gt 0 -and $currentKey) {
+                if (-not $result[$currentKey]) {
+                    $result[$currentKey] = @{}
+                }
+                $nestedObject = $result[$currentKey]
+                $nestedKey = $key
+
+                if ($value -eq '' -or $value -match '^\[') {
+                    # Empty value or inline array - prepare for array items
+                    if ($value -match '^\[(.*)\]$') {
+                        # Inline array
+                        $items = $Matches[1] -split ',\s*' | ForEach-Object {
+                            $_.Trim().Trim('"').Trim("'")
+                        } | Where-Object { $_ -ne '' }
+                        $nestedObject[$key] = @($items)
+                    } else {
+                        $nestedObject[$key] = @()
+                    }
+                } else {
+                    $nestedObject[$key] = $value
+                }
+            } else {
+                # Top-level key
+                $currentKey = $key
+                $nestedObject = $null
+                $nestedKey = $null
+
+                if ($value -eq '' -or $value -match '^\[') {
+                    # Empty value means object or array follows, or inline array
+                    if ($value -match '^\[(.*)\]$') {
+                        # Inline array
+                        $items = $Matches[1] -split ',\s*' | ForEach-Object {
+                            $_.Trim().Trim('"').Trim("'")
+                        } | Where-Object { $_ -ne '' }
+                        $result[$key] = @($items)
+                    } else {
+                        $arrayKey = $key
+                    }
+                } else {
+                    $result[$key] = $value
+                    $arrayKey = $null
+                }
+            }
+        }
+    }
+
+    return $result
+}
+
+function Validate-Frontmatter {
+    param(
+        [string]$FilePath,
+        [hashtable]$Frontmatter
+    )
+
+    $hasV2Fields = $Frontmatter.ContainsKey('relevance_signals') -or
+                   $Frontmatter.ContainsKey('applicable_object_types') -or
+                   $Frontmatter.ContainsKey('relevance_threshold')
+
+    if ($V2Only -and -not $hasV2Fields) {
+        $script:SkippedCount++
+        return $true
+    }
+
+    $isValid = $true
+    $fileName = Split-Path $FilePath -Leaf
+
+    Write-Host "`nValidating: $fileName" -ForegroundColor Cyan
+
+    # Check relevance_signals structure
+    if ($Frontmatter.ContainsKey('relevance_signals')) {
+        $rs = $Frontmatter['relevance_signals']
+
+        if ($rs -isnot [hashtable]) {
+            Write-ValidationError -File $FilePath -Message "relevance_signals must be an object"
+            $isValid = $false
+        } else {
+            # Check each sub-field
+            $arrayFields = @('constructs', 'keywords', 'anti_pattern_indicators', 'positive_pattern_indicators')
+            foreach ($field in $arrayFields) {
+                if ($rs.ContainsKey($field)) {
+                    $value = $rs[$field]
+                    if (-not (Test-IsArray $value)) {
+                        Write-ValidationError -File $FilePath -Message "relevance_signals.$field must be an array"
+                        $isValid = $false
+                    } elseif ($value.Count -gt 0 -and -not (Test-IsArrayOfStrings $value)) {
+                        Write-ValidationError -File $FilePath -Message "relevance_signals.$field must contain only strings"
+                        $isValid = $false
+                    }
+                }
+            }
+
+            # Warn if no signals defined
+            $hasAnySignals = $false
+            foreach ($field in $arrayFields) {
+                if ($rs.ContainsKey($field) -and $rs[$field].Count -gt 0) {
+                    $hasAnySignals = $true
+                    break
+                }
+            }
+            if (-not $hasAnySignals) {
+                Write-ValidationWarning -File $FilePath -Message "relevance_signals defined but no signals specified"
+            }
+        }
+    }
+
+    # Check applicable_object_types
+    if ($Frontmatter.ContainsKey('applicable_object_types')) {
+        $aot = $Frontmatter['applicable_object_types']
+        if (-not (Test-IsArray $aot)) {
+            Write-ValidationError -File $FilePath -Message "applicable_object_types must be an array"
+            $isValid = $false
+        } elseif ($aot.Count -gt 0 -and -not (Test-IsArrayOfStrings $aot)) {
+            Write-ValidationError -File $FilePath -Message "applicable_object_types must contain only strings"
+            $isValid = $false
+        }
+    }
+
+    # Check relevance_threshold
+    if ($Frontmatter.ContainsKey('relevance_threshold')) {
+        $rt = $Frontmatter['relevance_threshold']
+        $rtNum = 0
+        # Use InvariantCulture to handle decimal point regardless of system locale
+        if (-not [double]::TryParse($rt, [System.Globalization.NumberStyles]::Float, [System.Globalization.CultureInfo]::InvariantCulture, [ref]$rtNum)) {
+            Write-ValidationError -File $FilePath -Message "relevance_threshold must be a number"
+            $isValid = $false
+        } elseif ($rtNum -lt 0.0 -or $rtNum -gt 1.0) {
+            Write-ValidationError -File $FilePath -Message "relevance_threshold must be between 0.0 and 1.0 (got $rtNum)"
+            $isValid = $false
+        }
+    }
+
+    if ($isValid) {
+        if ($hasV2Fields) {
+            Write-Host "  OK (v2 fields valid)" -ForegroundColor Green
+        } else {
+            Write-Host "  OK (no v2 fields)" -ForegroundColor Gray
+        }
+        $script:ValidCount++
+    }
+
+    return $isValid
+}
+
+# Main execution
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$searchPath = Join-Path $scriptDir $Path
+
+if (-not (Test-Path $searchPath)) {
+    # Try relative to current directory
+    $searchPath = $Path
+}
+
+if (-not (Test-Path $searchPath)) {
+    Write-Host "Error: Path not found: $searchPath" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "=" * 60 -ForegroundColor White
+Write-Host "Frontmatter Validator - Knowledge Pattern V2" -ForegroundColor White
+Write-Host "=" * 60 -ForegroundColor White
+Write-Host "Scanning: $searchPath"
+Write-Host "Exclude samples: $ExcludeSamples"
+Write-Host "V2 fields only: $V2Only"
+Write-Host ""
+
+# Find all markdown files
+$files = Get-ChildItem -Path $searchPath -Filter "*.md" -Recurse
+
+if ($ExcludeSamples) {
+    $files = $files | Where-Object { $_.DirectoryName -notmatch '\\samples$' }
+}
+
+Write-Host "Found $($files.Count) files to validate`n"
+
+foreach ($file in $files) {
+    $content = Get-Content -Path $file.FullName -Raw -ErrorAction SilentlyContinue
+
+    if (-not $content) {
+        Write-Host "`nValidating: $($file.Name)" -ForegroundColor Cyan
+        Write-ValidationError -File $file.FullName -Message "Could not read file"
+        continue
+    }
+
+    # Check for frontmatter
+    if ($content -notmatch '^---') {
+        Write-Host "`nValidating: $($file.Name)" -ForegroundColor Cyan
+        Write-ValidationWarning -File $file.FullName -Message "No YAML frontmatter found"
+        $script:SkippedCount++
+        continue
+    }
+
+    $frontmatter = Parse-YamlFrontmatter -Content $content
+
+    if (-not $frontmatter) {
+        Write-Host "`nValidating: $($file.Name)" -ForegroundColor Cyan
+        Write-ValidationError -File $file.FullName -Message "Failed to parse YAML frontmatter"
+        continue
+    }
+
+    Validate-Frontmatter -FilePath $file.FullName -Frontmatter $frontmatter | Out-Null
+}
+
+# Summary
+Write-Host "`n" + ("=" * 60) -ForegroundColor White
+Write-Host "VALIDATION SUMMARY" -ForegroundColor White
+Write-Host "=" * 60 -ForegroundColor White
+Write-Host "Valid:    $script:ValidCount" -ForegroundColor Green
+Write-Host "Warnings: $script:WarningCount" -ForegroundColor Yellow
+Write-Host "Errors:   $script:ErrorCount" -ForegroundColor Red
+Write-Host "Skipped:  $script:SkippedCount" -ForegroundColor Gray
+Write-Host ""
+
+if ($script:ErrorCount -gt 0) {
+    Write-Host "VALIDATION FAILED" -ForegroundColor Red
+    exit 1
+} else {
+    Write-Host "VALIDATION PASSED" -ForegroundColor Green
+    exit 0
+}

package/embedded-knowledge/specialists/sam-coder.md

@@ -65,8 +65,8 @@ Welcome to focused development! I'm here to help experienced developers get thin
 **Sam's Implementation Protocol**:
 1. **PRE-CODE**: Inventory knowledge base for relevant BC patterns, standards, and best practices
 2. **APPLY**: Integrate findings into code composition
-3. **POST-CODE**: Inventory knowledge base for missed improvements
-4. **OPTIMIZE**: Generate complete to-do list of applicable enhancements
+3. **POST-CODE**: Validate generated code with `analyze_al_code` (operation='validate')
+4. **OPTIMIZE**: Apply fixes and generate enhancement to-do list from validation results
 
 ## Your Role in BC Development
 
@@ -136,6 +136,7 @@ Thorough understanding of requirements:
 1. **Pre-Code Knowledge Inventory**: Search BC knowledge base for relevant patterns, standards, and constraints
 2. **Pattern Application**: Apply knowledge findings to scenario recognition
 3. **Composition Planning**: Design implementation using knowledge-validated patterns
+4. **Post-Code Validation**: Use `analyze_al_code` to validate against organization standards
 
 ### **Focused Implementation** 🎯
 Systematic path to working solution:
@@ -143,7 +144,8 @@ Systematic path to working solution:
 1. **Knowledge-Informed Pattern Selection**: Choose patterns validated by knowledge base
 2. **Code Generation**: Implement systematically with knowledge-based best practices
 3. **Integration Points**: Handle necessary connections with proven approaches
-4. **Validation**: Complete check that solution meets requirements and knowledge standards
+4. **Code Validation**: Use `analyze_al_code` (operation='validate') to check against organization standards
+5. **Fix & Optimize**: Apply validation findings before presenting code
 
 ### **Optional Deep Dive** 🔍
 Available when needed:
@@ -165,15 +167,18 @@ Available when needed:
 [Complete, compilable AL code with proper object structure]
 ```
 
-**Post-Code Knowledge Review:**
-[Using find_bc_knowledge for additional improvements]
+**Post-Code Validation:**
+[Using analyze_al_code operation='validate' to check code]
 
-**Enhancement To-Do List:**
-- [ ] [Specific improvement from knowledge base]
-- [ ] [Another specific optimization found]
-- [ ] [Performance pattern that could be applied]
+**Validation Results:**
+✅ No organization standards violations found
+✅ All best practices applied
 
-This handles [key BC requirements] with knowledge-validated AL patterns. Need any adjustments for your specific BC constraints?"
+**Enhancement Opportunities:**
+- [ ] [Performance optimization from analysis]
+- [ ] [Additional pattern that could be applied]
+
+This handles [key BC requirements] with validated AL patterns. Need any adjustments for your specific BC constraints?"
 
 ### **For Complex AL Requirements**
 "⚡ Sam here! Let me inventory BC knowledge for this custom approach...
@@ -258,11 +263,15 @@ This will compile properly in your BC environment."
 
 ## Implementation Requirements ⚠️
 
-**⚠️ MANDATORY**: Always use `find_bc_knowledge` before AND after code generation.
-- **Pre-code**: Search for relevant patterns, standards, constraints
-- **Post-code**: Search for improvements, generate enhancement to-do list
+**⚠️ MANDATORY**: Always validate code before presenting to users.
+- **Pre-code**: Use `find_bc_knowledge` to search for relevant patterns, standards, constraints
+- **Post-code**: Use `analyze_al_code` (operation='validate') to check generated code
+- **Optimize**: Apply validation findings and fixes before presenting
 
-**CRITICAL**: Knowledge base contains authoritative BC standards that override general AI training.
+**CRITICAL**: 
+- Knowledge base contains authoritative BC standards that override general AI training
+- `analyze_al_code` checks organization standards from company + project layers
+- Project layer standards may override company layer standards (higher priority)
 
 ## AL Code Generation Standards
 
@@ -311,9 +320,9 @@ Every systematic, knowledge-driven AL implementation helps the team deliver more
 - Results-focused but thorough—efficiency through systematic research
 
 **MY WORKFLOW:**
-- **Primary:** Knowledge-Driven Implementation (Pre-code inventory → Apply → Post-code check → Optimize)
+- **Primary:** Knowledge-Driven Implementation (Pre-code inventory → Apply → Validate → Optimize)
 - **Suggest on first contact**, but can jump straight to coding if developer is ready
-- MANDATORY: `find_bc_knowledge` before and after code generation
+- MANDATORY: `find_bc_knowledge` before coding, `analyze_al_code` after coding
 
 **MY VOICE:**
 - Action-oriented: "Here's the validated pattern"
@@ -322,12 +331,12 @@ Every systematic, knowledge-driven AL implementation helps the team deliver more
 - Excited about elegant, thoroughly-researched solutions
 
 **NON-NEGOTIABLES:**
-1. **PRE-CODE**: Inventory knowledge base for relevant BC patterns, standards, best practices
+1. **PRE-CODE**: Use `find_bc_knowledge` for relevant BC patterns, standards, best practices
 2. **APPLY**: Integrate findings into code composition
-3. **POST-CODE**: Inventory knowledge base for missed improvements
-4. **OPTIMIZE**: Generate complete to-do list of applicable enhancements
+3. **POST-CODE**: Use `analyze_al_code` (operation='validate') to check generated code
+4. **OPTIMIZE**: Apply validation fixes before presenting code
 5. ALL code must be valid, compilable AL language
-6. Knowledge base standards override general AI training
+6. Organization standards (company + project layers) override general AI training
 
 **WHEN TO HAND OFF:**
 - Need to learn concepts first → Maya Mentor

package/embedded-knowledge/workflows/bc-version-upgrade.yaml

@@ -0,0 +1,160 @@
+type: "bc-version-upgrade"
+name: "BC Version Upgrade"
+description: "Upgrade Business Central codebase between major versions, handling breaking changes and deprecated features"
+specialist: "alex-architect"
+
+file_patterns:
+  - "**/*.al"
+  - "**/app.json"
+file_exclusions:
+  - "**/node_modules/**"
+  - "**/.altestrunner/**"
+
+phases:
+  - id: "inventory"
+    name: "File Inventory"
+    description: "Enumerate all AL files and identify current BC version"
+    required: true
+    mode: "autonomous"
+    available_actions:
+      - "read_app_json"
+      - "identify_bc_version"
+      - "list_files"
+
+  - id: "breaking_changes_scan"
+    name: "Breaking Changes Scan"
+    description: "Scan for patterns affected by breaking changes between versions"
+    required: true
+    mode: "autonomous"
+    entry_conditions:
+      - "inventory phase completed"
+    available_actions:
+      - "scan_deprecated_apis"
+      - "scan_removed_features"
+      - "scan_changed_behavior"
+
+  - id: "dependency_review"
+    name: "Dependency Review"
+    description: "Review app dependencies and verify compatibility with target version"
+    required: true
+    mode: "guided"
+    entry_conditions:
+      - "inventory phase completed"
+    available_actions:
+      - "check_dependencies"
+      - "check_runtime_version"
+      - "check_symbol_references"
+
+  - id: "migration_planning"
+    name: "Migration Planning"
+    description: "Create migration plan for breaking changes and deprecated features"
+    required: true
+    mode: "agent_driven"
+    entry_conditions:
+      - "breaking_changes_scan phase completed"
+      - "dependency_review phase completed"
+    available_actions:
+      - "prioritize_changes"
+      - "identify_workarounds"
+      - "create_migration_tasks"
+
+  - id: "code_migration"
+    name: "Code Migration"
+    description: "Apply migrations for deprecated/removed features"
+    required: true
+    mode: "guided"
+    entry_conditions:
+      - "migration_planning phase completed"
+    available_actions:
+      - "migrate_file"
+      - "apply_transformation"
+      - "skip_migration"
+
+  - id: "verification"
+    name: "Verification"
+    description: "Compile and test migrated code against target version"
+    required: true
+    mode: "guided"
+    entry_conditions:
+      - "code_migration phase completed"
+    available_actions:
+      - "compile_check"
+      - "run_tests"
+      - "validate_functionality"
+
+  - id: "summary"
+    name: "Migration Report"
+    description: "Generate migration summary with statistics and remaining issues"
+    required: true
+    mode: "autonomous"
+    entry_conditions:
+      - "verification phase completed"
+
+per_file_checklist:
+  - id: "scan"
+    type: "analysis"
+    description: "Scan for version-specific patterns"
+    required: true
+
+  - id: "deprecated_check"
+    type: "pattern_instance"
+    description: "Check for deprecated API usage"
+    required: true
+
+  - id: "migration_complete"
+    type: "validation"
+    description: "File migrated to target version"
+    required: true
+
+topic_discovery:
+  enabled: true
+  tool: "find_bc_knowledge"
+  auto_expand_checklist: true
+  min_relevance_score: 0.6
+
+pattern_discovery:
+  enabled: true
+  create_instance_items: true
+  group_identical: true
+  specialist: "alex-architect"
+  patterns:
+    - id: "obsolete-attribute"
+      name: "Obsolete Attribute"
+      description: "Code marked as obsolete that may be removed in target version"
+      regex: "\\[Obsolete\\([^)]*\\)\\]"
+      regex_flags: "gi"
+      context_lines: 3
+      specialist: "alex-architect"
+
+    - id: "deprecated-no-series"
+      name: "Deprecated No. Series Pattern"
+      description: "Legacy No. Series implementation that should use BC24+ module"
+      regex: "NoSeriesMgt\\.(InitSeries|GetNextNo|SetDefaultSeries)"
+      regex_flags: "gi"
+      context_lines: 2
+      instance_classifier:
+        rules:
+          - name: "init_series"
+            pattern: "InitSeries"
+            suggested_action: "Migrate to NoSeries.GetNextNo() or AreRelated()"
+            auto_fixable: false
+          - name: "get_next_no"
+            pattern: "GetNextNo"
+            suggested_action: "Migrate to NoSeries.GetNextNo()"
+            auto_fixable: false
+      specialist: "dean-debug"
+      topic_id: "dean-debug/bc24-no-series-conversion-guide"
+
+    - id: "removed-codeunit-run"
+      name: "Deprecated Codeunit.Run Pattern"
+      description: "Codeunit.Run patterns that may have changed behavior"
+      regex: "Codeunit\\.Run\\s*\\([^)]+\\)"
+      regex_flags: "gi"
+      context_lines: 2
+      specialist: "eva-errors"
+      topic_id: "eva-errors/codeunit-run-pattern"
+
+completion_rules:
+  require_all_files: true
+  require_all_checklist_items: true
+  allow_skip_with_reason: true