sf-forcekit 1.0.0

package/templates/ai-dir/scripts/update_state.py

@@ -0,0 +1,1406 @@
+#!/usr/bin/env python3
+import os
+import sys
+import re
+import glob
+import json
+import subprocess
+from datetime import datetime
+
+# Paths
+AI_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PROJECT_ROOT = os.path.dirname(AI_DIR)
+CURRENT_STATE_PATH = os.path.join(AI_DIR, 'current-state.md')
+INVENTORY_PATH = os.path.join(AI_DIR, 'inventory.md')
+
+def print_help():
+    print("""Salesforce AI Context Helper Tool
+Usage:
+  python3 .ai/scripts/update_state.py scan
+    Scans the force-app directory and updates inventory.md automatically.
+
+  python3 .ai/scripts/update_state.py sync-org [--target-org <alias>]
+    Queries the Salesforce org to fetch active org details (edition, org ID, instance, my domain) and limits (API requests, storage), updating org-context.md and current-state.md automatically.
+
+  python3 .ai/scripts/update_state.py check [--files "<file1,file2>"]
+    Performs static analysis (linting) on Apex/JS files for design violations (hardcoded IDs, missing USER_MODE, DML in loops, etc.).
+
+  python3 .ai/scripts/update_state.py verify --type object|field|class|flow --name <name> [--object <object_name>] [--target-org <alias>] [--force]
+    Queries the Salesforce org via CLI to verify if metadata exists.
+
+  python3 .ai/scripts/update_state.py cache-schema [--target-org <alias>]
+    Pre-caches all custom objects, custom fields, and primary standard fields from the org to prevent hallucinations offline.
+
+  python3 .ai/scripts/update_state.py session-start --agent <name> --goal "<goal>"
+    Logs the start of a new session in current-state.md.
+
+  python3 .ai/scripts/update_state.py session-end --summary "<summary>" [--files "<file1,file2>"]
+    Logs the end of a session, lists files changed, and updates tasks.
+
+  python3 .ai/scripts/update_state.py task-add "<description>" [--priority P0|P1|P2] [--deps "<deps>"]
+    Adds a task to upcoming in current-state.md.
+
+  python3 .ai/scripts/update_state.py task-start "<description>" [--branch <branch>]
+    Moves a task to In Progress in current-state.md.
+
+  python3 .ai/scripts/update_state.py task-complete "<description>" [--files "<file1,file2>"]
+    Moves a task to Recently Completed in current-state.md.
+
+  python3 .ai/scripts/update_state.py decision "<decision>" --rationale "<rationale>"
+    Logs a design decision in current-state.md.
+
+  python3 .ai/scripts/update_state.py blocker "<blocker>" --impact "<impact>" --severity High|Medium|Low
+    Logs a blocker in current-state.md.
+
+  python3 .ai/scripts/update_state.py blocker-resolve "<blocker>"
+    Resolves/removes a blocker in current-state.md.
+
+  python3 .ai/scripts/update_state.py clean
+    Removes local org-context.local.md, clears metadata-cache, and resets
+    current-state.md to prepare the project for open source distribution.
+""")
+
+def get_target_org():
+    local_path = os.path.join(AI_DIR, 'org-context.local.md')
+    org_context_path = local_path if os.path.exists(local_path) else os.path.join(AI_DIR, 'org-context.md')
+    if os.path.exists(org_context_path):
+        content = read_file(org_context_path)
+        match = re.search(r'\|\s*(?:\*\*)?Org Alias(?:\*\*)?\s*\|\s*`?([^`|\s]+)`?\s*\|', content, re.IGNORECASE)
+        if match:
+            val = match.group(1).strip()
+            if val and val != '<!--' and val != '-->' and val != '[Insert' and 'YOUR_' not in val.upper() and '<' not in val:
+                return val
+    return None
+
+def get_default_sf_org():
+    try:
+        res = subprocess.run(["sf", "config", "get", "target-org", "--json"], capture_output=True, text=True, check=False)
+        if res.returncode == 0:
+            data = json.loads(res.stdout)
+            results = data.get('result', [])
+            if isinstance(results, list) and results:
+                return results[0].get('value')
+            elif isinstance(results, dict):
+                return results.get('value')
+    except Exception:
+        pass
+    return None
+
+def get_cache_path(category):
+    return os.path.join(AI_DIR, 'metadata-cache', f"{category}.json")
+
+def read_cache(category):
+    path = get_cache_path(category)
+    if os.path.exists(path):
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except Exception:
+            return {}
+    return {}
+
+def write_cache(category, data):
+    os.makedirs(os.path.join(AI_DIR, 'metadata-cache'), exist_ok=True)
+    path = get_cache_path(category)
+    with open(path, 'w', encoding='utf-8') as f:
+        json.dump(data, f, indent=2)
+
+def strip_comments(content):
+    content = re.sub(r'/\*[\s\S]*?\*/', '', content)
+    content = re.sub(r'//.*$', '', content, flags=re.MULTILINE)
+    return content
+
+def get_line_number(full_text, char_index):
+    return full_text[:char_index].count('\n') + 1
+
+def extract_loop_body(text, loop_start_idx):
+    header_start = text.find('(', loop_start_idx)
+    if header_start == -1:
+        return "", loop_start_idx
+    paren_count = 1
+    idx = header_start + 1
+    while paren_count > 0 and idx < len(text):
+        if text[idx] == '(':
+            paren_count += 1
+        elif text[idx] == ')':
+            paren_count -= 1
+        idx += 1
+    if paren_count != 0:
+        return "", loop_start_idx
+    non_ws_idx = idx
+    while non_ws_idx < len(text) and text[non_ws_idx].isspace():
+        non_ws_idx += 1
+    if non_ws_idx >= len(text):
+        return "", loop_start_idx
+    if text[non_ws_idx] == '{':
+        brace_count = 1
+        current_idx = non_ws_idx + 1
+        while brace_count > 0 and current_idx < len(text):
+            if text[current_idx] == '{':
+                brace_count += 1
+            elif text[current_idx] == '}':
+                brace_count -= 1
+            current_idx += 1
+        if brace_count == 0:
+            return text[non_ws_idx:current_idx], non_ws_idx
+    else:
+        semi_idx = text.find(';', non_ws_idx)
+        if semi_idx != -1:
+            return text[non_ws_idx:semi_idx+1], non_ws_idx
+    return "", loop_start_idx
+
+def check_file(file_path):
+    issues = []
+    content = read_file(file_path)
+    clean_content = strip_comments(content)
+    
+    is_apex = file_path.endswith('.cls')
+    is_trigger = file_path.endswith('.trigger')
+    
+    if is_apex:
+        # Sharing keyword check (exclude interfaces and tests)
+        if 'interface' not in clean_content.lower() and '@istest' not in content.lower():
+            class_matches = re.finditer(r'\b(?:public|private|global|virtual|abstract)\s+class\s+(\w+)\b', clean_content, re.IGNORECASE)
+            for m in class_matches:
+                class_name = m.group(1)
+                if not re.search(r'\b(?:with|without|inherited)\s+sharing\b', clean_content, re.IGNORECASE):
+                    issues.append({
+                        'rule': 'Sharing Keyword Enforced',
+                        'severity': 'Error',
+                        'message': f"Class '{class_name}' is missing an explicit sharing keyword (with sharing, without sharing, inherited sharing).",
+                        'line': get_line_number(content, m.start())
+                    })
+        
+        # SeeAllData=true check for test classes
+        if '@istest' in content.lower():
+            m = re.search(r'@isTest\s*\(\s*SeeAllData\s*=\s*true\s*\)', content, re.IGNORECASE)
+            if m:
+                issues.append({
+                    'rule': 'SeeAllData Banned',
+                    'severity': 'Error',
+                    'message': "SeeAllData=true is banned in tests. Create test data instead.",
+                    'line': get_line_number(content, m.start())
+                })
+        
+        # Hardcoded endpoint check (exclude tests)
+        if '@istest' not in content.lower():
+            endpoint_matches = re.finditer(r'[\'"]https?://[^\'"]+[\'"]', clean_content, re.IGNORECASE)
+            for m in endpoint_matches:
+                url = m.group(0)
+                if not any(x in url for x in ['soap.sforce.com', 'metadata.tooling', 'schemas.xmlsoap.org']):
+                    issues.append({
+                        'rule': 'No Hardcoded Endpoints',
+                        'severity': 'Error',
+                        'message': f"Hardcoded endpoint URL detected: {url}. Use Named Credentials instead.",
+                        'line': get_line_number(content, m.start())
+                    })
+
+        soql_matches = re.finditer(r'\[\s*(SELECT[\s\S]*?)\]', clean_content, re.IGNORECASE)
+        for m in soql_matches:
+            soql_text = m.group(1)
+            if not re.search(r'\bWITH\s+(?:USER_MODE|SECURITY_ENFORCED|SYSTEM_MODE)\b', soql_text, re.IGNORECASE):
+                issues.append({
+                    'rule': 'Enforce Security in SOQL',
+                    'severity': 'Error',
+                    'message': f"SOQL query missing WITH USER_MODE: {soql_text.strip()[:60]}...",
+                    'line': get_line_number(content, m.start())
+                })
+                
+        catch_matches = re.finditer(r'\bcatch\s*\(\s*\w+\s+\w+\s*\)\s*\{\s*\}', clean_content)
+        for m in catch_matches:
+            issues.append({
+                'rule': 'Swallowed Exception Warning',
+                'severity': 'Warning',
+                'message': "Empty catch block detected. Swallowing exceptions silently is banned.",
+                'line': get_line_number(content, m.start())
+            })
+
+    if is_trigger:
+        # Check trigger logic bulkiness
+        if len(clean_content.split('\n')) > 30:
+            issues.append({
+                'rule': 'Keep Triggers Simple',
+                'severity': 'Warning',
+                'message': "Trigger has more than 30 lines. Triggers should delegate immediately to a handler class.",
+                'line': 1
+            })
+
+    if is_apex or is_trigger:
+        for loop_match in re.finditer(r'\b(for|while)\b\s*\(', clean_content, re.IGNORECASE):
+            loop_body, loop_start_idx = extract_loop_body(clean_content, loop_match.start())
+            if loop_body:
+                soql_in_loop = re.finditer(r'\[\s*(SELECT[\s\S]*?)\]', loop_body, re.IGNORECASE)
+                for sm in soql_in_loop:
+                    issues.append({
+                        'rule': 'No SOQL in Loops',
+                        'severity': 'Error',
+                        'message': f"SOQL query found inside a {loop_match.group(1)} loop: {sm.group(1).strip()[:60]}...",
+                        'line': get_line_number(content, loop_start_idx + sm.start())
+                    })
+                
+                dml_in_loop = re.finditer(r'\b(insert|update|upsert|delete|undelete|merge)\s+(?:new\s+\w+|\w+)\b', loop_body, re.IGNORECASE)
+                for dm in dml_in_loop:
+                    issues.append({
+                        'rule': 'No DML in Loops',
+                        'severity': 'Error',
+                        'message': f"DML statement '{dm.group(1)}' found inside a {loop_match.group(1)} loop.",
+                        'line': get_line_number(content, loop_start_idx + dm.start())
+                    })
+                
+                db_dml_in_loop = re.finditer(r'\bDatabase\.(insert|update|upsert|delete|undelete|merge|convertLead|emptyRecycleBin)\b', loop_body, re.IGNORECASE)
+                for dbm in db_dml_in_loop:
+                    issues.append({
+                        'rule': 'No DML in Loops',
+                        'severity': 'Error',
+                        'message': f"Database DML call 'Database.{dbm.group(1)}' found inside a {loop_match.group(1)} loop.",
+                        'line': get_line_number(content, loop_start_idx + dbm.start())
+                    })
+
+    id_matches = re.finditer(r'\b(001|003|005|006|00Q|012|01t|500|701|801|a[0-9][0-9a-zA-Z])[0-9a-zA-Z]{12}(?:[0-9a-zA-Z]{3})?\b', clean_content)
+    for m in id_matches:
+        issues.append({
+            'rule': 'No Hardcoded IDs',
+            'severity': 'Error',
+            'message': f"Hardcoded Salesforce ID detected: '{m.group(0)}'. Use Custom Labels or Metadata instead.",
+            'line': get_line_number(content, m.start())
+        })
+
+    # LWC directory naming check
+    if '/lwc/' in file_path.replace('\\', '/') and file_path.endswith('.js'):
+        parts = file_path.replace('\\', '/').split('/')
+        try:
+            lwc_idx = parts.index('lwc')
+            if lwc_idx + 1 < len(parts):
+                folder_name = parts[lwc_idx + 1]
+                if folder_name and folder_name[0].isupper():
+                    issues.append({
+                        'rule': 'LWC Naming Standard',
+                        'severity': 'Error',
+                        'message': f"LWC component folder '{folder_name}' must be camelCase, not PascalCase.",
+                        'line': 1
+                    })
+        except ValueError:
+            pass
+
+    return issues
+
+def check_all_files(files_arg=None):
+    if files_arg:
+        file_paths = [f.strip() for f in files_arg.split(',') if f.strip()]
+    else:
+        force_app = os.path.join(PROJECT_ROOT, 'force-app')
+        file_paths = []
+        if os.path.exists(force_app):
+            for ext in ('/**/*.cls', '/**/*.trigger', '/**/*.js'):
+                file_paths.extend(glob.glob(force_app + ext, recursive=True))
+        else:
+            print("Error: 'force-app' directory not found.")
+            sys.exit(1)
+
+    all_issues = {}
+    total_errors = 0
+    total_warnings = 0
+    
+    for file_path in sorted(file_paths):
+        rel_path = os.path.relpath(file_path, PROJECT_ROOT)
+        issues = check_file(file_path)
+        if issues:
+            all_issues[rel_path] = issues
+            for issue in issues:
+                if issue['severity'] == 'Error':
+                    total_errors += 1
+                else:
+                    total_warnings += 1
+
+    if not all_issues:
+        print("✅ No design violations or code quality issues found!")
+        sys.exit(0)
+        
+    print(f"🔍 Found {total_errors} errors and {total_warnings} warnings in {len(all_issues)} files:\n")
+    for file_path, issues in all_issues.items():
+        print(f"📂 {file_path}")
+        for issue in sorted(issues, key=lambda x: x['line']):
+            severity_str = "🔴 ERROR" if issue['severity'] == 'Error' else "🟡 WARNING"
+            print(f"  Line {issue['line']}: [{severity_str}] ({issue['rule']}) {issue['message']}")
+        print()
+        
+    if total_errors > 0:
+        print("❌ Static analysis failed due to design rule errors. Please fix them before deploying.")
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+def verify_metadata(meta_type, meta_name, obj_name=None, target_org_override=None, force=False):
+    if not meta_type or not meta_name:
+        print("Error: --type and --name are required parameters for 'verify'.")
+        sys.exit(1)
+        
+    meta_type = meta_type.lower()
+    if meta_type == 'field' and not obj_name:
+        print("Error: --object <object_name> is required when --type is 'field'.")
+        sys.exit(1)
+
+    category_map = {
+        'object': 'objects',
+        'field': 'fields',
+        'class': 'classes',
+        'flow': 'flows'
+    }
+    category = category_map.get(meta_type)
+    if not category:
+        print(f"Error: Invalid metadata type '{meta_type}'")
+        sys.exit(1)
+        
+    cache_key = f"{obj_name}.{meta_name}" if meta_type == 'field' else meta_name
+    
+    if not force:
+        cache = read_cache(category)
+        if cache_key in cache:
+            entry = cache[cache_key]
+            if entry.get('verified'):
+                print(f"✅ [Cache Hit] Verified: {meta_type} '{cache_key}' exists in Salesforce (last checked {entry.get('verified_at')})")
+                sys.exit(0)
+            else:
+                print(f"❌ [Cache Hit] Verified: {meta_type} '{cache_key}' DOES NOT exist in Salesforce (last checked {entry.get('verified_at')})")
+                sys.exit(1)
+
+    # Determine target org
+    org = target_org_override or get_target_org()
+    if not org:
+        print("Error: Target org not specified. Update Org Alias in .ai/org-context.md, or pass it via --target-org")
+        sys.exit(1)
+
+    # Build query
+    if meta_type == 'object':
+        query = f"SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName = '{meta_name}'"
+    elif meta_type == 'field':
+        query = f"SELECT QualifiedApiName, DataType FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = '{obj_name}' AND QualifiedApiName = '{meta_name}'"
+    elif meta_type == 'class':
+        query = f"SELECT Name, Status FROM ApexClass WHERE Name = '{meta_name}'"
+    elif meta_type == 'flow':
+        query = f"SELECT DeveloperName, Status FROM FlowDefinitionView WHERE DeveloperName = '{meta_name}'"
+
+    cmd = ["sf", "data", "query", "--query", query, "--target-org", org, "--use-tooling-api", "--json"]
+    print(f"Executing Salesforce CLI query targeting '{org}' to verify {meta_type} '{cache_key}'...")
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+        if result.returncode != 0:
+            print(f"Error executing sf CLI: {result.stderr.strip()}")
+            print(f"Ensure that you are logged into target-org '{org}' (run: sf org login web --alias {org})")
+            sys.exit(1)
+            
+        data = json.loads(result.stdout)
+        records = data.get('result', {}).get('records', [])
+        exists = len(records) > 0
+        
+        cache = read_cache(category)
+        cache[cache_key] = {
+            "verified": exists,
+            "verified_at": datetime.now().isoformat()
+        }
+        if exists and meta_type == 'field':
+            cache[cache_key]['dataType'] = records[0].get('DataType', 'Unknown')
+        elif exists and meta_type == 'class':
+            cache[cache_key]['status'] = records[0].get('Status', 'Unknown')
+        write_cache(category, cache)
+        
+        if exists:
+            print(f"✅ Verified: {meta_type} '{cache_key}' exists in Salesforce org '{org}'")
+            sys.exit(0)
+        else:
+            print(f"❌ Verification Failed: {meta_type} '{cache_key}' does not exist in Salesforce org '{org}'")
+            sys.exit(1)
+    except Exception as e:
+        print(f"Error running verification command: {str(e)}")
+        sys.exit(1)
+
+def cache_schema(target_org_override=None):
+    org = target_org_override or get_target_org()
+    if not org:
+        print("Error: Target org not specified. Update Org Alias in .ai/org-context.md, or pass it via --target-org")
+        sys.exit(1)
+
+    print(f"Pre-caching Salesforce schema from org '{org}' to prevent hallucinations...")
+    
+    # Fetch Objects using split queries (avoid disjunctions not supported by Tooling API)
+    objects_queries = [
+        "SELECT QualifiedApiName, Label FROM EntityDefinition WHERE QualifiedApiName LIKE '%__c'",
+        "SELECT QualifiedApiName, Label FROM EntityDefinition WHERE QualifiedApiName IN ('Account', 'Contact', 'Opportunity', 'Lead', 'Case', 'User')"
+    ]
+    
+    objects_cache = read_cache("objects")
+    total_objects = 0
+    print("Fetching custom and standard objects...")
+    for query in objects_queries:
+        cmd = ["sf", "data", "query", "--query", query, "--target-org", org, "--use-tooling-api", "--json"]
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+            if result.returncode == 0:
+                data = json.loads(result.stdout)
+                records = data.get('result', {}).get('records', [])
+                for r in records:
+                    name = r.get('QualifiedApiName')
+                    label = r.get('Label')
+                    if name:
+                        objects_cache[name] = {
+                            "label": label or name,
+                            "verified": True,
+                            "verified_at": datetime.now().isoformat()
+                        }
+                        total_objects += 1
+            else:
+                print(f"Warning: Failed execution for query: {query}. Error: {result.stderr.strip()}")
+        except Exception as e:
+            print(f"Error executing query {query}: {str(e)}")
+            
+    write_cache("objects", objects_cache)
+    print(f"Successfully cached {total_objects} objects.")
+
+    # Fetch Fields using split queries
+    fields_queries = [
+        "SELECT EntityDefinition.QualifiedApiName, QualifiedApiName, DataType, Label FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName LIKE '%__c'",
+        "SELECT EntityDefinition.QualifiedApiName, QualifiedApiName, DataType, Label FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName IN ('Account', 'Contact', 'Opportunity', 'Lead', 'Case')"
+    ]
+    
+    fields_cache = read_cache("fields")
+    total_fields = 0
+    print("Fetching fields (this may take a moment)...")
+    for query in fields_queries:
+        cmd = ["sf", "data", "query", "--query", query, "--target-org", org, "--use-tooling-api", "--json"]
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+            if result.returncode == 0:
+                data = json.loads(result.stdout)
+                records = data.get('result', {}).get('records', [])
+                for r in records:
+                    obj_name = r.get('EntityDefinition', {}).get('QualifiedApiName')
+                    field_name = r.get('QualifiedApiName')
+                    data_type = r.get('DataType')
+                    label = r.get('Label')
+                    if obj_name and field_name:
+                        key = f"{obj_name}.{field_name}"
+                        fields_cache[key] = {
+                            "label": label or field_name,
+                            "dataType": data_type or "Unknown",
+                            "verified": True,
+                            "verified_at": datetime.now().isoformat()
+                        }
+                        total_fields += 1
+            else:
+                print(f"Warning: Failed execution for query: {query}. Error: {result.stderr.strip()}")
+        except Exception as e:
+            print(f"Error executing query {query}: {str(e)}")
+            
+    write_cache("fields", fields_cache)
+    print(f"Successfully cached {total_fields} fields.")
+
+def sync_org(target_org_override=None):
+    org = target_org_override or get_target_org() or get_default_sf_org()
+    if not org:
+        print("Error: Target org not specified and no default target org found. Update Org Alias in .ai/org-context.md, authorize an org via 'sf org login web', or pass it via --target-org")
+        sys.exit(1)
+
+    print(f"Synchronizing Salesforce org details and limits from '{org}'...")
+
+    # 1. sf org display --json
+    cmd_display = ["sf", "org", "display", "--target-org", org, "--json"]
+    org_id = None
+    username = None
+    my_domain = None
+    alias = org
+    
+    try:
+        res = subprocess.run(cmd_display, capture_output=True, text=True, check=False)
+        if res.returncode == 0:
+            data = json.loads(res.stdout)
+            result = data.get('result', {})
+            org_id = result.get('id')
+            username = result.get('username')
+            instance_url = result.get('instanceUrl', '')
+            if instance_url:
+                my_domain = instance_url.replace('https://', '').replace('http://', '').strip('/')
+            alias = result.get('alias') or org
+        else:
+            print(f"Warning: sf org display failed: {res.stderr.strip()}")
+    except Exception as e:
+        print(f"Warning: Failed to run sf org display: {str(e)}")
+
+    # 2. sf data query for Organization details
+    query = "SELECT Name, OrganizationType, InstanceName FROM Organization"
+    cmd_query = ["sf", "data", "query", "--query", query, "--target-org", org, "--json"]
+    org_name = None
+    org_type = None
+    instance_name = None
+    
+    try:
+        res = subprocess.run(cmd_query, capture_output=True, text=True, check=False)
+        if res.returncode == 0:
+            data = json.loads(res.stdout)
+            records = data.get('result', {}).get('records', [])
+            if records:
+                org_name = records[0].get('Name')
+                org_type = records[0].get('OrganizationType')
+                instance_name = records[0].get('InstanceName')
+        else:
+            print(f"Warning: Query to Organization object failed: {res.stderr.strip()}")
+    except Exception as e:
+        print(f"Warning: Failed to query Organization: {str(e)}")
+
+    # 3. sf limits api display --json
+    cmd_limits = ["sf", "limits", "api", "display", "--target-org", org, "--json"]
+    limits_data = {}
+    try:
+        res = subprocess.run(cmd_limits, capture_output=True, text=True, check=False)
+        if res.returncode == 0:
+            data = json.loads(res.stdout)
+            for item in data.get('result', []):
+                name = item.get('name')
+                limits_data[name] = {
+                    'max': item.get('max'),
+                    'remaining': item.get('remaining')
+                }
+        else:
+            print(f"Warning: sf limits api display failed: {res.stderr.strip()}")
+    except Exception as e:
+        print(f"Warning: Failed to display limits: {str(e)}")
+
+    if not org_type:
+        org_type = "Developer Edition"
+    if not instance_name:
+        instance_name = "N/A"
+    if not org_id:
+        org_id = "N/A"
+    if not username:
+        username = "N/A"
+    if not my_domain:
+        my_domain = "N/A"
+
+    api_max = limits_data.get('DailyApiRequests', {}).get('max', 15000)
+    api_rem = limits_data.get('DailyApiRequests', {}).get('remaining', 15000)
+    api_used = api_max - api_rem
+
+    data_max = limits_data.get('DataStorageMB', {}).get('max', 5)
+    data_rem = limits_data.get('DataStorageMB', {}).get('remaining', 5)
+    data_used = data_max - data_rem
+
+    file_max = limits_data.get('FileStorageMB', {}).get('max', 20)
+    file_rem = limits_data.get('FileStorageMB', {}).get('remaining', 20)
+    file_used = file_max - file_rem
+
+    # 4. Update org-context.local.md
+    org_context_path = os.path.join(AI_DIR, 'org-context.md')
+    org_context_local_path = os.path.join(AI_DIR, 'org-context.local.md')
+    
+    if os.path.exists(org_context_path):
+        content = read_file(org_context_path)
+        
+        # Replace Org Details rows
+        content = re.sub(r'^(\|\s*(?:\*\*)?Org Alias(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `{alias}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+        content = re.sub(r'^(\|\s*(?:\*\*)?Username(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `{username}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+        content = re.sub(r'^(\|\s*(?:\*\*)?Edition(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `{org_type}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+        content = re.sub(r'^(\|\s*(?:\*\*)?Instance(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `{instance_name}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+        content = re.sub(r'^(\|\s*(?:\*\*)?Org ID(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `{org_id}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+        content = re.sub(r'^(\|\s*(?:\*\*)?My Domain(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `{my_domain}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+
+        # Replace default target org config
+        content = re.sub(r'^(\|\s*(?:\*\*)?Default target org(?:\*\*)?\s*\|)([^|\r\n]+)(\|)', f'\\1 `--target-org {alias}` \\3', content, flags=re.IGNORECASE | re.MULTILINE)
+
+        # Update Governor limits header and rows in org-context.md
+        content = re.sub(r'## Governor Limits \([^)]*\)', f'## Governor Limits ({org_type})', content)
+        content = re.sub(r'(\|\s*Daily API Requests\s*\|)([^|\r\n]+)(\|)', f'\\1 {api_max:,} \\3', content, flags=re.IGNORECASE)
+        content = re.sub(r'(\|\s*Data Storage\s*\|)([^|\r\n]+)(\|)', f'\\1 {data_max} MB \\3', content, flags=re.IGNORECASE)
+        content = re.sub(r'(\|\s*File Storage\s*\|)([^|\r\n]+)(\|)', f'\\1 {file_max} MB \\3', content, flags=re.IGNORECASE)
+
+        # Replace Connected Orgs / Sandboxes row for this dev org
+        dev_row_pattern = r'\|\s*[^|\r\n]+\(Dev\)\s*\|[^|\r\n]+\|[^|\r\n]+\|\s*Primary dev\s*\|'
+        if re.search(dev_row_pattern, content):
+            content = re.sub(dev_row_pattern, f'| {alias} (Dev) | {org_type} | {username} | Primary dev |', content)
+        else:
+            content = re.sub(r'(\|\s*<insert_org_alias> \(Dev\)\s*\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)(\s*Primary dev\s*\|)',
+                             f'| {alias} (Dev) | {org_type} | {username} | Primary dev |', content)
+
+        # Replace remaining placeholders
+        content = content.replace('<insert_org_alias>', alias)
+        content = content.replace('<insert_edition>', org_type)
+        content = content.replace('<insert_username>', username)
+
+        write_file(org_context_local_path, content)
+        print("Updated .ai/org-context.local.md with active org details and limits.")
+
+    # 5. Update current-state.md
+    current_state_path = os.path.join(AI_DIR, 'current-state.md')
+    if os.path.exists(current_state_path):
+        content = read_file(current_state_path)
+        
+        def get_risk(used, total):
+            if total <= 0: return '🟢'
+            pct = (used / total) * 100
+            if pct >= 80: return '🔴'
+            if pct >= 50: return '🟡'
+            return '🟢'
+
+        api_risk = get_risk(api_used, api_max)
+        data_risk = get_risk(data_used, data_max)
+        file_risk = get_risk(file_used, file_max)
+
+        content = re.sub(r'(\|\s*API Calls \(Daily\)\s*\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)', 
+                         f'\\1 {api_used:,} \\3 {api_max:,} \\5 {api_risk} \\7', content, flags=re.IGNORECASE)
+        content = re.sub(r'(\|\s*Data Storage\s*\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)', 
+                         f'\\1 {data_used} MB \\3 {data_max} MB \\5 {data_risk} \\7', content, flags=re.IGNORECASE)
+        content = re.sub(r'(\|\s*File Storage\s*\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)([^|\r\n]+)(\|)', 
+                         f'\\1 {file_used} MB \\3 {file_max} MB \\5 {file_risk} \\7', content, flags=re.IGNORECASE)
+
+        write_file(current_state_path, content)
+        print("Updated .ai/current-state.md Governor Limit Watch.")
+
+    # 6. Update .gitignore to exclude local org context & cache files
+    gitignore_path = os.path.join(os.path.dirname(AI_DIR), '.gitignore')
+    try:
+        ignores_to_add = ['.ai/org-context.local.md', '.ai/metadata-cache/']
+        existing_lines = []
+        if os.path.exists(gitignore_path):
+            with open(gitignore_path, 'r', encoding='utf-8') as f:
+                existing_lines = f.read().splitlines()
+        
+        added_any = False
+        with open(gitignore_path, 'a', encoding='utf-8') as f:
+            for ignore_item in ignores_to_add:
+                if ignore_item not in existing_lines and f"{ignore_item}/" not in existing_lines:
+                    if not added_any and not existing_lines:
+                        f.write(f"# Salesforce AI Context Local Files\n")
+                    elif not added_any:
+                        f.write(f"\n# Salesforce AI Context Local Files\n")
+                    f.write(f"{ignore_item}\n")
+                    added_any = True
+                    print(f"Added {ignore_item} to .gitignore")
+    except Exception as e:
+        print(f"Warning: Failed to update .gitignore: {str(e)}")
+
+def read_file(path):
+    if not os.path.exists(path):
+        return ""
+    with open(path, 'r', encoding='utf-8') as f:
+        return f.read()
+
+def write_file(path, content):
+    with open(path, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+# --- INVENTORY SCANNING LOGIC ---
+def get_object_label(object_dir):
+    # Try to find object label in object-meta.xml
+    meta_files = glob.glob(os.path.join(object_dir, '*.object-meta.xml'))
+    if meta_files:
+        content = read_file(meta_files[0])
+        label_match = re.search(r'<label>(.*?)</label>', content)
+        if label_match:
+            return label_match.group(1)
+    return ""
+
+def scan_inventory():
+    print("Scanning project metadata...")
+    force_app = os.path.join(PROJECT_ROOT, 'force-app')
+    if not os.path.exists(force_app):
+        print(f"Error: force-app directory not found at {force_app}")
+        sys.exit(1)
+
+    # 1. Custom Objects
+    objects_path = os.path.join(force_app, 'main', 'default', 'objects')
+    objects = []
+    if os.path.exists(objects_path):
+        for name in sorted(os.listdir(objects_path)):
+            full_path = os.path.join(objects_path, name)
+            if os.path.isdir(full_path):
+                label = get_object_label(full_path)
+                objects.append((name, label))
+
+    # 2. LWC
+    lwc_path = os.path.join(force_app, 'main', 'default', 'lwc')
+    lwc_components = []
+    if os.path.exists(lwc_path):
+        for name in sorted(os.listdir(lwc_path)):
+            full_path = os.path.join(lwc_path, name)
+            if os.path.isdir(full_path) and not name.startswith('.'):
+                lwc_components.append(name)
+
+    # 3. Flows
+    flows_path = os.path.join(force_app, 'main', 'default', 'flows')
+    flows = []
+    if os.path.exists(flows_path):
+        for file in sorted(glob.glob(os.path.join(flows_path, '*.flow-meta.xml'))):
+            name = os.path.basename(file).replace('.flow-meta.xml', '')
+            # Try to read flow type and status
+            content = read_file(file)
+            flow_type = "Autolaunched"
+            if '<processType>Flow</processType>' in content:
+                flow_type = "Screen Flow"
+            elif '<processType>Workflow</processType>' in content:
+                flow_type = "Record-Triggered"
+            status = "Active" if '<status>Active</status>' in content else "Draft"
+            flows.append((name, flow_type, status))
+
+    # 4. Permission Sets
+    perms_path = os.path.join(force_app, 'main', 'default', 'permissionsets')
+    permission_sets = []
+    if os.path.exists(perms_path):
+        for file in sorted(glob.glob(os.path.join(perms_path, '*.permissionset-meta.xml'))):
+            name = os.path.basename(file).replace('.permissionset-meta.xml', '')
+            permission_sets.append(name)
+
+    # 5. Triggers
+    triggers_path = os.path.join(force_app, 'main', 'default', 'triggers')
+    triggers = []
+    if os.path.exists(triggers_path):
+        for file in sorted(glob.glob(os.path.join(triggers_path, '*.trigger'))):
+            name = os.path.basename(file).replace('.trigger', '')
+            content = read_file(file)
+            obj_match = re.search(r'on\s+(\w+)\s*\(', content, re.IGNORECASE)
+            obj = obj_match.group(1) if obj_match else "Unknown"
+            triggers.append((name, obj))
+
+    # 6. Apex Classes
+    classes_path = os.path.join(force_app, 'main', 'default', 'classes')
+    apex_classes = {
+        'handlers': [],
+        'services': [],
+        'selectors': [],
+        'controllers': [],
+        'batch_async': [],
+        'utilities': [],
+        'tests': []
+    }
+    if os.path.exists(classes_path):
+        for file in sorted(glob.glob(os.path.join(classes_path, '*.cls'))):
+            name = os.path.basename(file).replace('.cls', '')
+            content = read_file(file)
+            
+            # Simple heuristic classification
+            if name.endswith('Test') or '@isTest' in content.lower():
+                apex_classes['tests'].append(name)
+            elif name.endswith('Handler') or 'TriggerHandler' in content:
+                apex_classes['handlers'].append(name)
+            elif name.endswith('Service'):
+                apex_classes['services'].append(name)
+            elif name.endswith('Selector') or 'Selector' in name:
+                apex_classes['selectors'].append(name)
+            elif name.endswith('Controller'):
+                apex_classes['controllers'].append(name)
+            elif any(x in content for x in ['Database.Batchable', 'Queueable', 'Schedulable']):
+                apex_classes['batch_async'].append(name)
+            else:
+                apex_classes['utilities'].append(name)
+
+    # Now update inventory.md
+    inventory_content = read_file(INVENTORY_PATH)
+    if not inventory_content:
+        print("Error: inventory.md not found or empty.")
+        sys.exit(1)
+
+    # Update Custom Objects
+    obj_rows = ""
+    if objects:
+        for name, label in objects:
+            obj_rows += f"| {name} | {label} | | |\n"
+    else:
+        obj_rows = "| _None_ | | | |\n"
+    inventory_content = re.sub(
+        r'(## Custom Objects\s*\n\s*<!--.*?-->\s*\n\s*\|.*?\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)',
+        r'\1' + obj_rows,
+        inventory_content
+    )
+
+    # Update Triggers
+    trigger_rows = ""
+    if triggers:
+        for name, obj in triggers:
+            trigger_rows += f"| {name} | {obj} | |\n"
+    else:
+        trigger_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(### Triggers\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + trigger_rows,
+        inventory_content
+    )
+
+    # Update Handlers
+    handler_rows = ""
+    if apex_classes['handlers']:
+        for name in apex_classes['handlers']:
+            handler_rows += f"| {name} | | |\n"
+    else:
+        handler_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(### Handlers\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + handler_rows,
+        inventory_content
+    )
+
+    # Update Services
+    service_rows = ""
+    if apex_classes['services']:
+        for name in apex_classes['services']:
+            service_rows += f"| {name} | | |\n"
+    else:
+        service_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(### Services\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + service_rows,
+        inventory_content
+    )
+
+    # Update Selectors
+    selector_rows = ""
+    if apex_classes['selectors']:
+        for name in apex_classes['selectors']:
+            selector_rows += f"| {name} | | |\n"
+    else:
+        selector_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(### Selectors\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + selector_rows,
+        inventory_content
+    )
+
+    # Update Controllers
+    controller_rows = ""
+    if apex_classes['controllers']:
+        for name in apex_classes['controllers']:
+            controller_rows += f"| {name} | | |\n"
+    else:
+        controller_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(### Controllers \(LWC / Aura\)\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + controller_rows,
+        inventory_content
+    )
+
+    # Update Batch/Async
+    batch_rows = ""
+    if apex_classes['batch_async']:
+        for name in apex_classes['batch_async']:
+            batch_rows += f"| {name} | | | |\n"
+    else:
+        batch_rows = "| | | | |\n"
+    inventory_content = re.sub(
+        r'(### Batch / Queueable / Schedulable\s*\n\s*\|.*?\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + batch_rows,
+        inventory_content
+    )
+
+    # Update Utilities
+    utility_rows = ""
+    if apex_classes['utilities']:
+        for name in apex_classes['utilities']:
+            utility_rows += f"| {name} | |\n"
+    else:
+        utility_rows = "| | |\n"
+    inventory_content = re.sub(
+        r'(### Utilities / Helpers\s*\n\s*\|.*?\|.*?\|\n\s*\|.*?\|.*?\|\n)([\s\S]*?)(?=\n###|\Z)',
+        r'\1' + utility_rows,
+        inventory_content
+    )
+
+    # Update Test Classes
+    test_rows = ""
+    if apex_classes['tests']:
+        for name in apex_classes['tests']:
+            test_rows += f"| {name} | | |\n"
+    else:
+        test_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(### Test Classes\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)',
+        r'\1' + test_rows,
+        inventory_content
+    )
+
+    # Update LWC
+    lwc_rows = ""
+    if lwc_components:
+        for name in lwc_components:
+            lwc_rows += f"| {name} | | | |\n"
+    else:
+        lwc_rows = "| | | | |\n"
+    inventory_content = re.sub(
+        r'(## LWC Components\s*\n\s*<!--.*?-->\s*\n\s*\|.*?\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)',
+        r'\1' + lwc_rows,
+        inventory_content
+    )
+
+    # Update Flows
+    flow_rows = ""
+    if flows:
+        for name, flow_type, status in flows:
+            flow_rows += f"| {name} | {flow_type} | | {status} | |\n"
+    else:
+        flow_rows = "| | | | | |\n"
+    inventory_content = re.sub(
+        r'(## Flows\s*\n\s*<!--.*?-->\s*\n\s*\|.*?\|.*?\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)',
+        r'\1' + flow_rows,
+        inventory_content
+    )
+
+    # Update Permission Sets
+    perm_rows = ""
+    if permission_sets:
+        for name in permission_sets:
+            perm_rows += f"| {name} | | |\n"
+    else:
+        perm_rows = "| | | |\n"
+    inventory_content = re.sub(
+        r'(## Permission Sets\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)',
+        r'\1' + perm_rows,
+        inventory_content
+    )
+
+    # Update Scan Info
+    scan_info = f"**Date:** {datetime.today().strftime('%Y-%m-%d')}\n**Agent:** Auto-Scan Script\n**Method:** python3 .ai/scripts/update_state.py scan\n"
+    inventory_content = re.sub(
+        r'(## Last Full Scan\s*\n\s*<!--.*?-->\s*\n)([\s\S]*?)$',
+        r'\1' + scan_info,
+        inventory_content
+    )
+
+    write_file(INVENTORY_PATH, inventory_content)
+    print("inventory.md updated successfully!")
+
+# --- CURRENT STATE UPDATING LOGIC ---
+def session_start(agent, goal):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content:
+        print("Error: current-state.md not found or empty.")
+        sys.exit(1)
+
+    date_str = datetime.today().strftime('%Y-%m-%d')
+    new_entry = f"### {date_str} | {agent} | {goal}\n- 🟡 Session started\n- **Files:** _None_\n\n"
+    
+    # Prepend to Session Log section
+    match = re.search(r'(## Session Log\s*\n\s*<!--[\s\S]*?-->\n\n)', state_content)
+    if match:
+        idx = match.end()
+        state_content = state_content[:idx] + new_entry + state_content[idx:]
+        write_file(CURRENT_STATE_PATH, state_content)
+        print("Session start logged in current-state.md")
+    else:
+        print("Error: Could not locate '## Session Log' in current-state.md")
+
+def session_end(summary, files):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content:
+        print("Error: current-state.md not found.")
+        sys.exit(1)
+
+    date_str = datetime.today().strftime('%Y-%m-%d')
+    # Update files changed list in session log
+    files_str = files if files else "_None_"
+    
+    # Find the first entry in Session Log
+    log_match = re.search(r'(### \d{4}-\d{2}-\d{2} \| [^|]+ \| [^\n]+)\n([\s\S]*?)(?=\n###|\n---|\Z)', state_content)
+    if log_match:
+        header = log_match.group(1)
+        body = log_match.group(2)
+        new_body = f"- ✅ {summary}\n- **Files:** {files_str}\n"
+        state_content = state_content.replace(header + "\n" + body, header + "\n" + new_body)
+
+    # Update Files Changed Table
+    if files:
+        file_list = [f.strip() for f in files.split(',')]
+        table_rows = ""
+        for file in file_list:
+            table_rows += f"| {file} | Modified | Session update |\n"
+        
+        table_match = re.search(r'(## Files Changed This Session\s*\n\s*<!--[\s\S]*?-->\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)', state_content)
+        if table_match:
+            existing = table_match.group(2).strip()
+            if existing and existing != "| | | |":
+                new_table = existing + "\n" + table_rows
+            else:
+                new_table = table_rows
+            state_content = state_content.replace(table_match.group(0), table_match.group(1) + new_table)
+
+    # Clear Files Changed This Session if wanted, or just write
+    write_file(CURRENT_STATE_PATH, state_content)
+    print("Session end logged in current-state.md")
+
+def task_add(desc, priority, deps):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content: sys.exit(1)
+
+    task_row = f"- [ ] {desc} | Priority: {priority} | Dependencies: {deps}\n"
+    match = re.search(r'(### Upcoming\s*\n\s*<!--[\s\S]*?-->\n\n)', state_content)
+    if match:
+        idx = match.end()
+        state_content = state_content[:idx] + task_row + state_content[idx:]
+        write_file(CURRENT_STATE_PATH, state_content)
+        print(f"Task added: {desc}")
+    else:
+        print("Error: Could not locate '### Upcoming' section")
+
+def task_start(desc, branch):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content: sys.exit(1)
+
+    date_str = datetime.today().strftime('%Y-%m-%d')
+    # Remove from Upcoming
+    lines = state_content.split('\n')
+    new_lines = []
+    found = False
+    for line in lines:
+        if desc in line and '- [ ]' in line:
+            found = True
+            continue
+        new_lines.append(line)
+    state_content = '\n'.join(new_lines)
+
+    # Add to In Progress
+    in_progress_row = f"- [/] {desc} | Branch: `{branch}` | Started: {date_str}\n"
+    match = re.search(r'(### In Progress\s*\n\s*<!--[\s\S]*?-->\n\n)', state_content)
+    if match:
+        idx = match.end()
+        state_content = state_content[:idx] + in_progress_row + state_content[idx:]
+        write_file(CURRENT_STATE_PATH, state_content)
+        print(f"Task started: {desc}")
+    else:
+        print("Error: Could not locate '### In Progress' section")
+
+def task_complete(desc, files):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content: sys.exit(1)
+
+    date_str = datetime.today().strftime('%Y-%m-%d')
+    # Remove from In Progress
+    lines = state_content.split('\n')
+    new_lines = []
+    for line in lines:
+        if desc in line and '- [/' in line:
+            continue
+        new_lines.append(line)
+    state_content = '\n'.join(new_lines)
+
+    # Add to Recently Completed
+    completed_row = f"- [x] {desc} | Completed: {date_str} | Files: {files}\n"
+    match = re.search(r'(### Recently Completed\s*\n\s*<!--[\s\S]*?-->\n\n)', state_content)
+    if match:
+        idx = match.end()
+        state_content = state_content[:idx] + completed_row + state_content[idx:]
+        write_file(CURRENT_STATE_PATH, state_content)
+        print(f"Task completed: {desc}")
+    else:
+        print("Error: Could not locate '### Recently Completed' section")
+
+def decision_add(decision, rationale):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content: sys.exit(1)
+
+    date_str = datetime.today().strftime('%Y-%m-%d')
+    row = f"| {date_str} | {decision} | {rationale} |\n"
+    
+    table_match = re.search(r'(## Decisions\s*\n\s*<!--[\s\S]*?-->\s*\n\s*\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)', state_content)
+    if table_match:
+        existing = table_match.group(2).strip()
+        if existing and existing != "| | | |":
+            new_table = row + existing
+        else:
+            new_table = row
+        state_content = state_content.replace(table_match.group(0), table_match.group(1) + new_table)
+        write_file(CURRENT_STATE_PATH, state_content)
+        print(f"Decision logged: {decision}")
+    else:
+        print("Error: Could not find Decisions section")
+
+def blocker_add(blocker, impact, severity):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content: sys.exit(1)
+
+    date_str = datetime.today().strftime('%Y-%m-%d')
+    row = f"| {blocker} | {impact} | {severity} | {date_str} |\n"
+
+    table_match = re.search(r'(## Blockers\s*\n\s*<!--[\s\S]*?-->\s*\n\s*\|.*?\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)', state_content)
+    if table_match:
+        existing = table_match.group(2).strip()
+        if existing and "_None_" not in existing:
+            new_table = row + existing
+        else:
+            new_table = row
+        state_content = state_content.replace(table_match.group(0), table_match.group(1) + new_table)
+        write_file(CURRENT_STATE_PATH, state_content)
+        print(f"Blocker logged: {blocker}")
+    else:
+        print("Error: Could not find Blockers section")
+
+def blocker_resolve(blocker):
+    state_content = read_file(CURRENT_STATE_PATH)
+    if not state_content: sys.exit(1)
+
+    lines = state_content.split('\n')
+    new_lines = []
+    removed = False
+    for line in lines:
+        if blocker in line and '|' in line:
+            removed = True
+            continue
+        new_lines.append(line)
+    state_content = '\n'.join(new_lines)
+    
+    # If table is empty, restore _None_
+    table_match = re.search(r'(## Blockers\s*\n\s*<!--[\s\S]*?-->\s*\n\s*\|.*?\|.*?\|.*?\|.*?\|\n\s*\|.*?\|.*?\|.*?\|.*?\|\n)([\s\S]*?)(?=\n---|\Z)', state_content)
+    if table_match:
+        content = table_match.group(2).strip()
+        if not content:
+            state_content = state_content.replace(table_match.group(0), table_match.group(1) + "| _None_ | | | |\n")
+            
+    write_file(CURRENT_STATE_PATH, state_content)
+    if removed:
+        print(f"Blocker resolved: {blocker}")
+    else:
+        print(f"Blocker not found: {blocker}")
+
+def sanitize_project():
+    print("Sanitizing local and org-specific details for open source sharing...")
+    
+    # 1. Delete local org context
+    local_org_path = os.path.join(AI_DIR, 'org-context.local.md')
+    if os.path.exists(local_org_path):
+        try:
+            os.remove(local_org_path)
+            print(f"Removed local file: {local_org_path}")
+        except Exception as e:
+            print(f"Error removing {local_org_path}: {e}")
+            
+    # 2. Clear metadata-cache directory
+    cache_dir = os.path.join(AI_DIR, 'metadata-cache')
+    if os.path.exists(cache_dir):
+        try:
+            for f in glob.glob(os.path.join(cache_dir, '*')):
+                if os.path.isfile(f):
+                    os.remove(f)
+            os.rmdir(cache_dir)
+            print("Cleared metadata cache.")
+        except Exception as e:
+            print(f"Error clearing metadata cache: {e}")
+
+    # 3. Reset current-state.md to clean template
+    if os.path.exists(CURRENT_STATE_PATH):
+        try:
+            default_current_state = """# Current State
+
+> 🤖 **AUTO-UPDATED BY AI AGENTS** — This file is the project's living memory.
+> Agents MUST update this file as they work (see `rules.md` for protocol).
+> Humans: review periodically, correct if needed.
+
+---
+
+## Project Status
+
+**Last Updated:** 2026-05-22
+**Sprint/Phase:** [Update with current sprint]
+**Overall Status:** 🟢 On Track
+
+---
+
+## Active Work
+
+### In Progress
+
+
+### Upcoming
+
+
+### Recently Completed
+
+
+---
+
+## Blockers
+
+| Blocker | Impact | Severity | Added |
+|---------|--------|----------|-------|
+| _None_ | | | |
+
+---
+
+## Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| | | |
+
+---
+
+## Files Changed This Session
+
+| File | Action | Notes |
+|------|--------|-------|
+| | | |
+
+---
+
+## Environment State
+
+| Environment | Last Deploy | Status | Notes |
+|-------------|-----------|--------|-------|
+| Dev Sandbox | — | 🟢 | |
+| QA Sandbox | — | 🟢 | |
+| UAT Sandbox | — | 🟢 | |
+| Production | — | 🟢 | |
+
+---
+
+## Governor Limit Watch
+
+| Limit | Current Usage | Max | Risk |
+|-------|-------------|-----|------|
+| API Calls (Daily) | 0 | 15,000 | 🟢 |
+| Data Storage | 0 MB | 5 MB | 🟢 |
+| File Storage | 0 MB | 20 MB | 🟢 |
+
+---
+
+## Session Log
+
+<!-- Agent: Prepend a new entry at the TOP of this section every session.
+     Use the format below. This is the project's history. NEVER delete old entries.
+
+### YYYY-MM-DD | Agent Name | Session Goal
+- ✅ What was completed
+- 🟡 What's partially done
+- ❌ What failed and why
+- 💡 Key insight or decision
+- **Files:** comma-separated list of files touched
+-->
+
+### [First session entry will appear here]
+
+_No sessions recorded yet. The AI agent will begin logging here automatically._
+"""
+            write_file(CURRENT_STATE_PATH, default_current_state)
+            print("Reset current-state.md to clean template.")
+        except Exception as e:
+            print(f"Error resetting current-state.md: {e}")
+
+    # 4. Clean inventory.md Last Full Scan
+    if os.path.exists(INVENTORY_PATH):
+        try:
+            inventory_content = read_file(INVENTORY_PATH)
+            if inventory_content:
+                # Reset last scan info to generic details
+                scan_info = "**Date:** 2026-05-22\n**Agent:** Auto-Scan Script\n**Method:** python3 .ai/scripts/update_state.py scan\n"
+                inventory_content = re.sub(
+                    r'(## Last Full Scan\s*\n\s*<!--.*?-->\s*\n)([\s\S]*?)$',
+                    r'\1' + scan_info,
+                    inventory_content
+                )
+                write_file(INVENTORY_PATH, inventory_content)
+                print("Reset inventory.md last scan details.")
+        except Exception as e:
+            print(f"Error resetting inventory.md: {e}")
+            
+    print("Sanitization complete! Repository is safe to commit and share.")
+
+def main():
+    if len(sys.argv) < 2:
+        print_help()
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    
+    if cmd == 'scan':
+        scan_inventory()
+    elif cmd == 'check':
+        files_arg = None
+        args = sys.argv[2:]
+        for i in range(len(args)):
+            if args[i] == '--files' and i + 1 < len(args):
+                files_arg = args[i+1]
+        check_all_files(files_arg)
+    elif cmd == 'verify':
+        meta_type = None
+        meta_name = None
+        obj_name = None
+        target_org = None
+        force = False
+        args = sys.argv[2:]
+        for i in range(len(args)):
+            if args[i] == '--type' and i + 1 < len(args): meta_type = args[i+1]
+            if args[i] == '--name' and i + 1 < len(args): meta_name = args[i+1]
+            if args[i] == '--object' and i + 1 < len(args): obj_name = args[i+1]
+            if args[i] == '--target-org' and i + 1 < len(args): target_org = args[i+1]
+            if args[i] == '--force': force = True
+        verify_metadata(meta_type, meta_name, obj_name, target_org, force)
+    elif cmd == 'cache-schema':
+        target_org = None
+        args = sys.argv[2:]
+        for i in range(len(args)):
+            if args[i] == '--target-org' and i + 1 < len(args): target_org = args[i+1]
+        cache_schema(target_org)
+    elif cmd == 'sync-org':
+        target_org = None
+        args = sys.argv[2:]
+        for i in range(len(args)):
+            if args[i] == '--target-org' and i + 1 < len(args): target_org = args[i+1]
+        sync_org(target_org)
+    elif cmd == 'session-start':
+        agent = 'Agent'
+        goal = ''
+        args = sys.argv[2:]
+        for i in range(len(args)):
+            if args[i] == '--agent' and i + 1 < len(args): agent = args[i+1]
+            if args[i] == '--goal' and i + 1 < len(args): goal = args[i+1]
+        session_start(agent, goal)
+    elif cmd == 'session-end':
+        summary = ''
+        files = ''
+        args = sys.argv[2:]
+        for i in range(len(args)):
+            if args[i] == '--summary' and i + 1 < len(args): summary = args[i+1]
+            if args[i] == '--files' and i + 1 < len(args): files = args[i+1]
+        session_end(summary, files)
+    elif cmd == 'task-add':
+        desc = sys.argv[2]
+        priority = 'P1'
+        deps = 'none'
+        args = sys.argv[3:]
+        for i in range(len(args)):
+            if args[i] == '--priority' and i + 1 < len(args): priority = args[i+1]
+            if args[i] == '--deps' and i + 1 < len(args): deps = args[i+1]
+        task_add(desc, priority, deps)
+    elif cmd == 'task-start':
+        desc = sys.argv[2]
+        branch = 'main'
+        args = sys.argv[3:]
+        for i in range(len(args)):
+            if args[i] == '--branch' and i + 1 < len(args): branch = args[i+1]
+        task_start(desc, branch)
+    elif cmd == 'task-complete':
+        desc = sys.argv[2]
+        files = 'none'
+        args = sys.argv[3:]
+        for i in range(len(args)):
+            if args[i] == '--files' and i + 1 < len(args): files = args[i+1]
+        task_complete(desc, files)
+    elif cmd == 'decision':
+        decision = sys.argv[2]
+        rationale = ''
+        args = sys.argv[3:]
+        for i in range(len(args)):
+            if args[i] == '--rationale' and i + 1 < len(args): rationale = args[i+1]
+        decision_add(decision, rationale)
+    elif cmd == 'blocker':
+        blocker = sys.argv[2]
+        impact = ''
+        severity = 'Medium'
+        args = sys.argv[3:]
+        for i in range(len(args)):
+            if args[i] == '--impact' and i + 1 < len(args): impact = args[i+1]
+            if args[i] == '--severity' and i + 1 < len(args): severity = args[i+1]
+        blocker_add(blocker, impact, severity)
+    elif cmd == 'blocker-resolve':
+        blocker = sys.argv[2]
+        blocker_resolve(blocker)
+    elif cmd == 'clean':
+        sanitize_project()
+    else:
+        print_help()
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()