torusguard 1.0.0 → 1.3.0

package/.torusguard/scripts/memory_engine.py

@@ -19,21 +19,43 @@ from typing import Dict, List, Any, Optional, Tuple
 # Ensure UTF-8 stdout/stderr on Windows consoles
 if sys.stdout and hasattr(sys.stdout, "reconfigure"):
     try:
-        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        getattr(sys.stdout, "reconfigure")(encoding="utf-8", errors="replace")
     except Exception:
         pass
 if sys.stderr and hasattr(sys.stderr, "reconfigure"):
     try:
-        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        getattr(sys.stderr, "reconfigure")(encoding="utf-8", errors="replace")
     except Exception:
         pass
 
-VERSION = "1.0.0"
+VERSION = "1.1.0"
 DEFAULT_TOKEN_BUDGET = 2000
 DEFAULT_TTL_DAYS = 90
 DEFAULT_DECAY_RATE = 0.15
 
 
+def _utc_now() -> datetime.datetime:
+    """Return timezone-aware current UTC datetime."""
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+def _utc_now_iso() -> str:
+    """Return ISO 8601 formatted UTC timestamp string ending with 'Z'."""
+    return datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _parse_iso_utc(ts_str: str) -> datetime.datetime:
+    """Parse ISO timestamp string and guarantee timezone-aware UTC datetime."""
+    clean = ts_str.replace("Z", "+00:00")
+    try:
+        dt = datetime.datetime.fromisoformat(clean)
+    except ValueError:
+        dt = datetime.datetime.fromisoformat(clean.split(".")[0] + "+00:00")
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=datetime.timezone.utc)
+    return dt
+
+
 def find_project_root(start_dir: Optional[str] = None) -> Path:
     """Detect project root directory by searching for standard repo root markers."""
     current = Path(start_dir or os.getcwd()).resolve()
@@ -104,13 +126,13 @@ def ensure_memory_structure(root_dir: Optional[Path] = None) -> Dict[str, Path]:
             "active_patterns_count": 0,
             "fix_rate_percentage": None,
             "top_vulnerabilities": [],
-            "last_updated": datetime.datetime.utcnow().isoformat() + "Z"
+            "last_updated": _utc_now_iso()
         }, indent=2), encoding="utf-8")
 
     if not paths["context"].exists():
         initial_context = {
             "version": VERSION,
-            "generated_at": datetime.datetime.utcnow().isoformat() + "Z",
+            "generated_at": _utc_now_iso(),
             "token_estimate": 0,
             "max_token_budget": DEFAULT_TOKEN_BUDGET,
             "project_profile": {
@@ -156,8 +178,8 @@ def record_event(
         raise ValueError(f"Invalid event_type: {event_type}. Must be one of {valid_types}")
 
     paths = ensure_memory_structure(root_dir)
-    now_utc = datetime.datetime.utcnow()
-    timestamp_iso = now_utc.isoformat() + "Z"
+    now_utc = _utc_now()
+    timestamp_iso = _utc_now_iso()
     event_id = f"evt-{now_utc.strftime('%Y%m%d%H%M%S')}-{uuid.uuid4().hex[:8]}"
 
     # Sanitize file_path to be relative to project root
@@ -251,7 +273,17 @@ def distill_patterns(root_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
     events = load_all_events(root_dir)
     patterns: List[Dict[str, Any]] = []
 
-    if not events:
+    # Preserve existing golden_fix_recipe patterns
+    if paths["patterns"].exists():
+        try:
+            prev_patterns = json.loads(paths["patterns"].read_text(encoding="utf-8"))
+            for p in prev_patterns:
+                if p.get("pattern_type") == "golden_fix_recipe":
+                    patterns.append(p)
+        except Exception:
+            pass
+
+    if not events and not patterns:
         paths["patterns"].write_text("[]", encoding="utf-8")
         compute_context_window(root_dir=root_dir)
         return patterns
@@ -288,7 +320,7 @@ def distill_patterns(root_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
     # 1. Distill Recurring Fixes & Security Idioms
     for (rule_id, fix_strat), fix_evts in rule_fixes.items():
         occurrences = len(fix_evts)
-        affected_files = sorted(list({e.get("file_path") for e in fix_evts if e.get("file_path")}))
+        affected_files = sorted(list({str(e["file_path"]) for e in fix_evts if e.get("file_path")}))
         verified_count = sum(1 for e in fix_evts if e.get("verification_result") == "fixed")
 
         # Confidence amplification logic
@@ -298,8 +330,8 @@ def distill_patterns(root_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
             base_confidence = min(98, base_confidence + 5)
 
         pattern_type = "security_idiom" if occurrences >= 3 and verified_count >= 2 else "recurring_fix"
-        timestamps = [e.get("timestamp") for e in fix_evts if e.get("timestamp")]
-        first_seen = min(timestamps) if timestamps else datetime.datetime.utcnow().isoformat() + "Z"
+        timestamps: List[str] = [str(e["timestamp"]) for e in fix_evts if e.get("timestamp")]
+        first_seen = min(timestamps) if timestamps else _utc_now_iso()
         last_seen = max(timestamps) if timestamps else first_seen
 
         patterns.append({
@@ -322,9 +354,9 @@ def distill_patterns(root_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
     for rule_id, find_evts in rule_findings.items():
         occurrences = len(find_evts)
         if occurrences >= 2:
-            affected_files = sorted(list({e.get("file_path") for e in find_evts if e.get("file_path")}))
-            timestamps = [e.get("timestamp") for e in find_evts if e.get("timestamp")]
-            first_seen = min(timestamps) if timestamps else datetime.datetime.utcnow().isoformat() + "Z"
+            affected_files = sorted(list({str(e["file_path"]) for e in find_evts if e.get("file_path")}))
+            timestamps: List[str] = [str(e["timestamp"]) for e in find_evts if e.get("timestamp")]
+            first_seen = min(timestamps) if timestamps else _utc_now_iso()
             last_seen = max(timestamps) if timestamps else first_seen
 
             confidence = min(90, 55 + (occurrences * 5))
@@ -347,11 +379,11 @@ def distill_patterns(root_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
     # 3. Distill False Positive Classes
     for rule_id, fp_evts in false_positives.items():
         occurrences = len(fp_evts)
-        affected_files = sorted(list({e.get("file_path") for e in fp_evts if e.get("file_path")}))
+        affected_files = sorted(list({str(e["file_path"]) for e in fp_evts if e.get("file_path")}))
         reasons = [e.get("suppression_reason") for e in fp_evts if e.get("suppression_reason")]
         summary_reason = reasons[-1] if reasons else "Suppressed by team policy"
-        timestamps = [e.get("timestamp") for e in fp_evts if e.get("timestamp")]
-        first_seen = min(timestamps) if timestamps else datetime.datetime.utcnow().isoformat() + "Z"
+        timestamps: List[str] = [str(e["timestamp"]) for e in fp_evts if e.get("timestamp")]
+        first_seen = min(timestamps) if timestamps else _utc_now_iso()
         last_seen = max(timestamps) if timestamps else first_seen
 
         patterns.append({
@@ -373,9 +405,9 @@ def distill_patterns(root_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
     # 4. Distill Regression Watch Entries
     for rule_id, reg_evts in regressions.items():
         occurrences = len(reg_evts)
-        affected_files = sorted(list({e.get("file_path") for e in reg_evts if e.get("file_path")}))
-        timestamps = [e.get("timestamp") for e in reg_evts if e.get("timestamp")]
-        first_seen = min(timestamps) if timestamps else datetime.datetime.utcnow().isoformat() + "Z"
+        affected_files = sorted(list({str(e["file_path"]) for e in reg_evts if e.get("file_path")}))
+        timestamps: List[str] = [str(e["timestamp"]) for e in reg_evts if e.get("timestamp")]
+        first_seen = min(timestamps) if timestamps else _utc_now_iso()
         last_seen = max(timestamps) if timestamps else first_seen
 
         patterns.append({
@@ -414,7 +446,7 @@ def decay_stale_entries(
     Reduces confidence to prevent stale architectural advice.
     """
     paths = ensure_memory_structure(root_dir)
-    now = datetime.datetime.utcnow()
+    now = _utc_now()
 
     # Read config from decay.json if available
     try:
@@ -439,9 +471,7 @@ def decay_stale_entries(
         if not chk_str:
             continue
         try:
-            # Parse ISO date string (strip Z if present)
-            clean_ts = chk_str.rstrip("Z")
-            last_dt = datetime.datetime.fromisoformat(clean_ts)
+            last_dt = _parse_iso_utc(chk_str)
             days_elapsed = (now - last_dt).days
 
             if days_elapsed >= ttl_days:
@@ -450,7 +480,7 @@ def decay_stale_entries(
                 new_conf = max(10, old_conf - reduction)
                 if new_conf != old_conf:
                     pat["confidence"] = new_conf
-                    pat["decay_checkpoint"] = now.isoformat() + "Z"
+                    pat["decay_checkpoint"] = _utc_now_iso()
                     decayed_count += 1
         except Exception:
             continue
@@ -536,21 +566,168 @@ def get_project_profile(root_dir: Optional[Path] = None) -> Dict[str, Any]:
         "fixes_verified_count": verified_fixed_count,
         "fix_rate_percentage": fix_rate,
         "top_vulnerabilities": top_vulns,
-        "last_updated": datetime.datetime.utcnow().isoformat() + "Z"
+        "last_updated": _utc_now_iso()
     }
-
     paths["profile"].write_text(json.dumps(profile, indent=2), encoding="utf-8")
     return profile
 
 
+def compute_proximity_score(
+    pattern: Dict[str, Any],
+    target_file: Optional[str] = None,
+    target_rule_id: Optional[str] = None
+) -> int:
+    """
+    Compute file proximity and rule relevance score (0-100) for a memory pattern against a target query.
+    Enables file-scoped and rule-scoped context ranking.
+    """
+    score = 0
+    if not target_file and not target_rule_id:
+        return score
+
+    pat_rule = pattern.get("rule_id", "")
+    affected_files = [str(f).replace("\\", "/") for f in pattern.get("affected_files", [])]
+
+    # 1. Rule ID relevance: exact match = +40, family match (e.g. TG-DB-) = +20
+    if target_rule_id:
+        if pat_rule == target_rule_id:
+            score += 40
+        elif pat_rule and pat_rule.split("-")[:2] == target_rule_id.split("-")[:2]:
+            score += 20
+
+    # 2. File path relevance
+    if target_file:
+        norm_target = str(target_file).replace("\\", "/")
+        target_path = Path(norm_target)
+        target_ext = target_path.suffix.lower()
+        target_parts = set(p.lower() for p in target_path.parts if p not in (".", ".."))
+
+        best_file_score = 0
+        for aff in affected_files:
+            aff_score = 0
+            aff_path = Path(aff)
+            if aff == norm_target:
+                best_file_score = 50
+                break
+            # Same directory or subpath
+            if aff_path.parent == target_path.parent and str(target_path.parent) not in (".", ""):
+                aff_score = max(aff_score, 30)
+            elif any(part in target_parts for part in (p.lower() for p in aff_path.parts if p not in (".", ".."))):
+                aff_score = max(aff_score, 15)
+            # Extension match
+            if target_ext and aff_path.suffix.lower() == target_ext:
+                aff_score = max(aff_score, aff_score + 10)
+
+            if aff_score > best_file_score:
+                best_file_score = aff_score
+
+        # Also check file_type in recipe or pattern metadata
+        pat_file_type = pattern.get("file_type") or pattern.get("recipe_data", {}).get("file_type")
+        if pat_file_type and target_ext and pat_file_type.lower() == target_ext and best_file_score == 0:
+            best_file_score = 10
+
+        score += best_file_score
+
+    return min(score, 100)
+
+
+def record_golden_recipe(
+    rule_id: str,
+    before_snippet: str,
+    after_snippet: str,
+    diff_snippet: str,
+    file_type: str = ".py",
+    framework: Optional[str] = None,
+    description: str = "Verified AST remediation recipe",
+    additions: Optional[int] = None,
+    deletions: Optional[int] = None,
+    root_dir: Optional[Path] = None
+) -> Dict[str, Any]:
+    """
+    Store or update a verified Golden Fix Recipe adhering to Ponytail bounds (<=35 add, <=25 del).
+    """
+    paths = ensure_memory_structure(root_dir)
+
+    if additions is None:
+        additions = sum(1 for line in diff_snippet.splitlines() if line.startswith("+") and not line.startswith("+++"))
+    if deletions is None:
+        deletions = sum(1 for line in diff_snippet.splitlines() if line.startswith("-") and not line.startswith("---"))
+
+    if additions > 35 or deletions > 25:
+        raise ValueError(f"Recipe exceeds Ponytail bounds: +{additions}/35 add, -{deletions}/25 del")
+
+    recipe_hash = hashlib.sha256(diff_snippet.strip().encode("utf-8")).hexdigest()[:8]
+    recipe_id = f"recipe-{rule_id}-{recipe_hash}"
+    timestamp = _utc_now_iso()
+
+    recipe = {
+        "recipe_id": recipe_id,
+        "rule_id": rule_id,
+        "file_type": file_type,
+        "framework": framework,
+        "description": description,
+        "before_snippet": before_snippet.strip(),
+        "after_snippet": after_snippet.strip(),
+        "diff_snippet": diff_snippet.strip(),
+        "ponytail_metrics": {
+            "additions": additions,
+            "deletions": deletions
+        },
+        "verified_count": 1,
+        "last_verified": timestamp
+    }
+
+    patterns: List[Dict[str, Any]] = []
+    if paths["patterns"].exists():
+        try:
+            patterns = json.loads(paths["patterns"].read_text(encoding="utf-8"))
+        except Exception:
+            patterns = []
+
+    for p in patterns:
+        if p.get("pattern_type") == "golden_fix_recipe" and p.get("recipe_id") == recipe_id:
+            count = p.get("verified_count", 1) + 1
+            p["verified_count"] = count
+            recipe["verified_count"] = count
+            p["last_verified"] = timestamp
+            p["confidence"] = min(99, p.get("confidence", 85) + 5)
+            p["recipe_data"] = recipe
+            paths["patterns"].write_text(json.dumps(patterns, indent=2), encoding="utf-8")
+            return p
+
+    recipe_pattern: Dict[str, Any] = {
+        "pattern_id": f"PAT-RECIPE-{recipe_id}",
+        "rule_id": rule_id,
+        "pattern_type": "golden_fix_recipe",
+        "recipe_id": recipe_id,
+        "file_type": file_type,
+        "framework": framework,
+        "description": description,
+        "recipe_data": recipe,
+        "confidence": 90,
+        "occurrences": 1,
+        "affected_files": [],
+        "first_seen": timestamp,
+        "last_seen": timestamp
+    }
+    patterns.append(recipe_pattern)
+    paths["patterns"].write_text(json.dumps(patterns, indent=2), encoding="utf-8")
+    return recipe_pattern
+
+
 def compute_context_window(
     max_tokens: int = DEFAULT_TOKEN_BUDGET,
+    target_role: str = "all",
+    target_file: Optional[str] = None,
+    rule_id: Optional[str] = None,
+    target_rule_id: Optional[str] = None,
     root_dir: Optional[Path] = None
 ) -> Dict[str, Any]:
     """
-    Build the pre-computed, token-budgeted context window as structured JSON cards.
-    Guarantees strict token enforcement <= max_tokens.
+    Build the pre-computed or role-tailored context window as structured JSON cards.
+    Guarantees strict token enforcement <= max_tokens with proximity and role weighting.
     """
+    rule_id = target_rule_id or rule_id
     paths = ensure_memory_structure(root_dir)
     profile = get_project_profile(root_dir=root_dir)
 
@@ -561,77 +738,140 @@ def compute_context_window(
         except Exception:
             patterns = []
 
-    # Sort patterns by priority: regressions (95) -> idioms (90) -> recurring fixes (85) -> FP (80) -> common vulns (70)
-    type_priority = {
-        "regression_watch": 95,
-        "security_idiom": 90,
-        "recurring_fix": 85,
-        "false_positive_class": 80,
-        "common_vulnerability": 70
+    # Persona-tailored base priority matrices
+    role_priority_matrices = {
+        "all": {
+            "regression_watch": 95,
+            "golden_fix_recipe": 90,
+            "security_idiom": 85,
+            "recurring_fix": 80,
+            "false_positive_class": 75,
+            "common_vulnerability": 70
+        },
+        "auditor": {
+            "false_positive_class": 100,
+            "common_vulnerability": 95,
+            "regression_watch": 90,
+            "recurring_fix": 80,
+            "security_idiom": 60,
+            "golden_fix_recipe": 40
+        },
+        "remediator": {
+            "golden_fix_recipe": 115,
+            "security_idiom": 100,
+            "recurring_fix": 90,
+            "regression_watch": 80,
+            "common_vulnerability": 60,
+            "false_positive_class": 50
+        },
+        "reviewer": {
+            "regression_watch": 115,
+            "false_positive_class": 95,
+            "golden_fix_recipe": 85,
+            "recurring_fix": 75,
+            "security_idiom": 65,
+            "common_vulnerability": 55
+        }
     }
 
+    type_priority = role_priority_matrices.get(target_role, role_priority_matrices["all"])
+
     # Generate Candidate Cards
     cards: List[Dict[str, Any]] = []
     card_idx = 1
 
-    # 1. Project Profile Card (Priority: 100)
+    # 1. Project Profile Card (Always top priority)
     cards.append({
         "card_id": f"CARD-{card_idx:03d}",
         "card_type": "profile",
-        "priority": 100,
+        "type": "profile",
+        "priority": 150,
+        "proximity_score": 0,
         "title": "Project Security Posture & DNA",
         "summary": f"Stack: {', '.join(profile.get('stack') or ['Generic'])}; Total Events: {profile.get('total_events', 0)}; Fix Rate: {profile.get('fix_rate_percentage')}%",
         "card_data": {
             "stack": profile.get("stack", []),
             "total_events": profile.get("total_events", 0),
             "fix_rate_percentage": profile.get("fix_rate_percentage"),
-            "top_vulnerabilities": profile.get("top_vulnerabilities", [])
+            "top_vulnerabilities": profile.get("top_vulnerabilities", []),
+            "target_role": target_role
         }
     })
     card_idx += 1
 
-    # Sort patterns by type priority then confidence then occurrences
-    sorted_patterns = sorted(
-        patterns,
-        key=lambda p: (
-            type_priority.get(p.get("pattern_type", ""), 50),
-            p.get("confidence", 0),
-            p.get("occurrences", 0)
+    # Score patterns: base priority + proximity score
+    scored_patterns = []
+    for pat in patterns:
+        ptype = pat.get("pattern_type", "pattern")
+        base_prio = type_priority.get(ptype, 50)
+        proximity = compute_proximity_score(pat, target_file=target_file, target_rule_id=rule_id)
+        effective_prio = base_prio + proximity
+        scored_patterns.append((effective_prio, proximity, pat))
+
+    # Sort patterns by effective priority -> confidence -> occurrences
+    scored_patterns.sort(
+        key=lambda x: (
+            x[0],
+            x[2].get("confidence", 0),
+            x[2].get("occurrences", 0)
         ),
         reverse=True
     )
 
-    for pat in sorted_patterns:
+    for eff_prio, prox_score, pat in scored_patterns:
         ptype = pat.get("pattern_type", "pattern")
         card_type = "pattern"
+        title = f"[{pat.get('rule_id')}] {pat.get('pattern_type')}: {pat.get('description', '')[:60]}"
+        summary = pat.get("description", "")
+        card_data: Dict[str, Any] = {
+            "rule_id": pat.get("rule_id"),
+            "pattern_type": pat.get("pattern_type"),
+            "confidence": pat.get("confidence"),
+            "occurrences": pat.get("occurrences"),
+            "affected_files": pat.get("affected_files", [])[:5]
+        }
+
         if ptype == "regression_watch":
             card_type = "regression_watch"
         elif ptype == "false_positive_class":
-            card_type = "false_positive"
+            card_type = "false_positive_suppression"
+        elif ptype == "common_vulnerability":
+            card_type = "common_vulnerability"
         elif ptype == "security_idiom":
             card_type = "fix_idiom"
+            card_data["fix_strategy"] = pat.get("fix_strategy")
+        elif ptype == "golden_fix_recipe":
+            card_type = "golden_recipe"
+            recipe_obj = pat.get("recipe_data", {})
+            title = f"[{pat.get('rule_id')}] Golden Recipe: {pat.get('description', '')[:50]}"
+            card_data["diff_snippet"] = recipe_obj.get("diff_snippet", "")
+            card_data["ponytail_metrics"] = recipe_obj.get("ponytail_metrics", {})
+            card_data["framework"] = recipe_obj.get("framework")
 
         cards.append({
             "card_id": f"CARD-{card_idx:03d}",
             "card_type": card_type,
-            "priority": type_priority.get(ptype, 60),
-            "title": f"[{pat.get('rule_id')}] {pat.get('pattern_type')}: {pat.get('description', '')[:60]}",
-            "summary": pat.get("description", ""),
-            "card_data": {
-                "rule_id": pat.get("rule_id"),
-                "pattern_type": pat.get("pattern_type"),
-                "fix_strategy": pat.get("fix_strategy"),
-                "confidence": pat.get("confidence"),
-                "occurrences": pat.get("occurrences"),
-                "affected_files": pat.get("affected_files", [])[:5]
-            }
+            "type": card_type,
+            "priority": eff_prio,
+            "proximity_score": prox_score,
+            "title": title,
+            "summary": summary,
+            "card_data": card_data
         })
         card_idx += 1
 
     # Build Context Window Payload
     context = {
         "version": VERSION,
-        "generated_at": datetime.datetime.utcnow().isoformat() + "Z",
+        "generated_at": _utc_now_iso(),
+        "role": target_role,
+        "target_role": target_role,
+        "target_query": {
+            "file": target_file,
+            "rule_id": rule_id
+        },
+        "target_file": target_file,
+        "rule_id": rule_id,
         "token_estimate": 0,
         "max_token_budget": max_tokens,
         "project_profile": {
@@ -645,27 +885,43 @@ def compute_context_window(
     }
 
     # Token budget enforcement: Drop lowest-priority cards until within limit
-    # Always keep at least the profile card (cards[0])
     while len(context["cards"]) > 1 and estimate_tokens(context) > max_tokens:
         context["cards"].pop()
 
     context["token_estimate"] = estimate_tokens(context)
 
-    # Persist context.json
-    paths["context"].write_text(json.dumps(context, indent=2), encoding="utf-8")
+    # Persist default context.json if generating for role="all" without filters
+    if target_role == "all" and not target_file and not rule_id:
+        paths["context"].write_text(json.dumps(context, indent=2), encoding="utf-8")
+
     return context
 
 
-def get_context(root_dir: Optional[Path] = None) -> Dict[str, Any]:
-    """Retrieve the current pre-computed context window."""
-    paths = ensure_memory_structure(root_dir)
-    if paths["context"].exists():
-        try:
-            return json.loads(paths["context"].read_text(encoding="utf-8"))
-        except Exception:
-            pass
+def get_context(
+    target_role: str = "all",
+    target_file: Optional[str] = None,
+    rule_id: Optional[str] = None,
+    max_tokens: int = DEFAULT_TOKEN_BUDGET,
+    root_dir: Optional[Path] = None
+) -> Dict[str, Any]:
+    """Retrieve or compute persona-tailored and file-scoped context window."""
+    if target_role == "all" and not target_file and not rule_id:
+        paths = ensure_memory_structure(root_dir)
+        if paths["context"].exists():
+            try:
+                data = json.loads(paths["context"].read_text(encoding="utf-8"))
+                if data.get("version") == VERSION:
+                    return data
+            except Exception:
+                pass
 
-    return compute_context_window(root_dir=root_dir)
+    return compute_context_window(
+        max_tokens=max_tokens,
+        target_role=target_role,
+        target_file=target_file,
+        rule_id=rule_id,
+        root_dir=root_dir
+    )
 
 
 def record_false_positive(
@@ -688,45 +944,70 @@ def record_false_positive(
     return evt
 
 
-def export_memory(target_path: str, root_dir: Optional[Path] = None) -> Dict[str, Any]:
+def export_memory(
+    target_path: Optional[Any] = None,
+    target_file: Optional[Any] = None,
+    sanitized: bool = False,
+    root_dir: Optional[Path] = None
+) -> Dict[str, Any]:
     """
     Export memory to an external file for team sharing.
-    Per user choice: retain code hashes for high-fidelity matching, but sanitize absolute paths.
+    Supports sanitized mode for safe repository version control (strips absolute paths & secrets).
     """
     paths = ensure_memory_structure(root_dir)
     events = load_all_events(root_dir)
     profile = get_project_profile(root_dir=root_dir)
 
-    patterns = []
+    patterns: List[Dict[str, Any]] = []
     if paths["patterns"].exists():
         try:
             patterns = json.loads(paths["patterns"].read_text(encoding="utf-8"))
         except Exception:
             pass
 
-    decay_cfg = {}
+    decay_cfg: Dict[str, Any] = {}
     if paths["decay"].exists():
         try:
             decay_cfg = json.loads(paths["decay"].read_text(encoding="utf-8"))
         except Exception:
             pass
 
+    if sanitized:
+        sanitized_events = []
+        for e in events:
+            ce = dict(e)
+            if "file_path" in ce and ce["file_path"]:
+                ce["file_path"] = Path(ce["file_path"]).name
+            sanitized_events.append(ce)
+        events = sanitized_events
+
+        sanitized_patterns = []
+        for p in patterns:
+            cp = dict(p)
+            if "affected_files" in cp:
+                cp["affected_files"] = [Path(f).name for f in cp["affected_files"]]
+            sanitized_patterns.append(cp)
+        patterns = sanitized_patterns
+
     export_payload = {
         "format": "torusguard-memory-bundle",
-        "schema_version": "1.0.0",
-        "exported_at": datetime.datetime.utcnow().isoformat() + "Z",
+        "schema_version": VERSION,
+        "sanitized": sanitized,
+        "exported_at": _utc_now_iso(),
         "project_profile": profile,
         "decay_config": decay_cfg,
         "patterns": patterns,
         "events": events
     }
 
-    out_file = Path(target_path).resolve()
+    dest = target_file or target_path or "torusguard-memory-export.json"
+    out_file = Path(dest).resolve()
     out_file.parent.mkdir(parents=True, exist_ok=True)
     out_file.write_text(json.dumps(export_payload, indent=2), encoding="utf-8")
 
     return {
         "target_path": str(out_file),
+        "sanitized": sanitized,
         "exported_events_count": len(events),
         "exported_patterns_count": len(patterns)
     }
@@ -767,35 +1048,34 @@ def import_memory(source_path: str, merge: bool = True, root_dir: Optional[Path]
 
 
 def compact_events(older_than_days: int = 30, root_dir: Optional[Path] = None) -> int:
-    """
-    Compact loose event JSON files older than older_than_days into compacted_archive.json.
-    Prevents filesystem inode saturation while preserving full history.
-    """
+    """Archive events older than older_than_days into compacted_archive.json."""
     paths = ensure_memory_structure(root_dir)
-    cutoff = datetime.datetime.utcnow() - datetime.timedelta(days=older_than_days)
+    cutoff = _utc_now() - datetime.timedelta(days=older_than_days)
 
     archived: List[Dict[str, Any]] = []
+    archived_ids = set()
+
     if paths["compacted"].exists():
         try:
-            with open(paths["compacted"], "r", encoding="utf-8") as f:
-                data = json.load(f)
-                if isinstance(data, list):
-                    archived = data
+            archived = json.loads(paths["compacted"].read_text(encoding="utf-8"))
+            for item in archived:
+                eid = item.get("event_id")
+                if eid:
+                    archived_ids.add(eid)
         except Exception:
             archived = []
 
-    archived_ids = {e.get("event_id") for e in archived if e.get("event_id")}
     compacted_count = 0
-
-    for item in sorted(paths["events"].glob("*.json")):
+    for item in paths["events"].glob("*.json"):
         if item.name == "compacted_archive.json":
             continue
         try:
-            with open(item, "r", encoding="utf-8") as f:
-                evt = json.load(f)
-            ts_str = evt.get("timestamp", "").rstrip("Z")
-            evt_dt = datetime.datetime.fromisoformat(ts_str) if ts_str else None
-            if evt_dt and evt_dt < cutoff:
+            evt = json.loads(item.read_text(encoding="utf-8"))
+            ts_str = evt.get("timestamp")
+            if not ts_str:
+                continue
+            ts = _parse_iso_utc(ts_str)
+            if ts < cutoff:
                 eid = evt.get("event_id")
                 if eid and eid not in archived_ids:
                     archived.append(evt)
@@ -811,11 +1091,116 @@ def compact_events(older_than_days: int = 30, root_dir: Optional[Path] = None) -
     return compacted_count
 
 
+def install_git_hook(root_dir: Optional[Path] = None) -> Dict[str, Any]:
+    """Install a pre-commit git hook running TorusGuard diff_guard."""
+    base = Path(root_dir or find_project_root()).resolve()
+    git_dir = base / ".git"
+    if not git_dir.exists():
+        raise RuntimeError(f"Not a git repository: {base}")
+
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    pre_commit_hook = hooks_dir / "pre-commit"
+
+    hook_content = (
+        "#!/bin/sh\n"
+        "# TorusGuard Autonomous Security & Regression Guard\n"
+        "python .torusguard/scripts/diff_guard.py --pre-commit\n"
+        "EXIT_CODE=$?\n"
+        "if [ $EXIT_CODE -ne 0 ]; then\n"
+        "    echo \"[BLOCKED] Commit rejected by TorusGuard diff security guardrails.\"\n"
+        "    exit $EXIT_CODE\n"
+        "fi\n"
+        "exit 0\n"
+    )
+
+    pre_commit_hook.write_text(hook_content, encoding="utf-8")
+    try:
+        os.chmod(pre_commit_hook, 0o755)
+    except Exception:
+        pass
+
+    return {
+        "status": "installed",
+        "hook_path": str(pre_commit_hook)
+    }
+
+
+def uninstall_git_hook(root_dir: Optional[Path] = None) -> Dict[str, Any]:
+    """Uninstall the TorusGuard pre-commit git hook."""
+    base = Path(root_dir or find_project_root()).resolve()
+    pre_commit_hook = base / ".git" / "hooks" / "pre-commit"
+    if pre_commit_hook.exists():
+        content = pre_commit_hook.read_text(encoding="utf-8", errors="replace")
+        if "TorusGuard" in content:
+            pre_commit_hook.unlink()
+            return {"status": "uninstalled", "hook_path": str(pre_commit_hook)}
+        else:
+            return {"status": "skipped", "reason": "Pre-commit hook does not belong to TorusGuard"}
+    return {"status": "not_found"}
+
+
+def learn_from_git(commit_range: str = "HEAD~10..HEAD", root_dir: Optional[Path] = None) -> Dict[str, Any]:
+    """Ingest developer security fixes from git commits into local memory."""
+    import subprocess
+    base = Path(root_dir or find_project_root()).resolve()
+    learned_events = []
+
+    try:
+        res = subprocess.run(
+            ["git", "log", "-n", "10", "--pretty=format:%H|||%s", "--name-only"],
+            cwd=str(base),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace"
+        )
+        output = res.stdout
+    except Exception as e:
+        return {"commits_scanned": 0, "learned_events_count": 0, "events_recorded": 0, "error": str(e)}
+
+    current_hash = ""
+    current_subject = ""
+    for line in output.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if "|||" in line:
+            parts = line.split("|||", 1)
+            current_hash = parts[0]
+            current_subject = parts[1]
+        else:
+            file_mod = line
+            sub_lower = current_subject.lower()
+            if any(k in sub_lower for k in ["security", "fix", "vuln", "cve", "sanitize", "auth", "tenant"]):
+                evt = record_event(
+                    "pattern_learned",
+                    {
+                        "source": "git_history",
+                        "commit_hash": current_hash[:8],
+                        "commit_message": current_subject,
+                        "file_path": file_mod
+                    },
+                    root_dir=base
+                )
+                learned_events.append(evt)
+
+    if learned_events:
+        distill_patterns(root_dir=base)
+
+    return {
+        "commits_scanned": 10,
+        "learned_events_count": len(learned_events),
+        "events_recorded": len(learned_events)
+    }
+
+
 # ─── Command Line Interface ──────────────────────────────────────────────────
 def main():
     parser = argparse.ArgumentParser(description="TorusGuard Security Memory Engine")
     parser.add_argument("--action", required=True, choices=[
-        "record", "distill", "context", "profile", "decay", "fp", "export", "import", "compact", "status"
+        "record", "distill", "context", "profile", "decay", "fp", "export", "import", "compact", "status",
+        "recipe", "hook-install", "hook-uninstall", "learn"
     ], help="Action to perform")
     parser.add_argument("--root", help="Project root directory override")
     parser.add_argument("--type", help="Event type (audit_finding, fix_applied, etc.)")
@@ -827,8 +1212,13 @@ def main():
     parser.add_argument("--strategy", help="Fix strategy description")
     parser.add_argument("--result", choices=["fixed", "regressed", "partial", "not_tested"])
     parser.add_argument("--reason", help="Suppression reason for false positive")
+    parser.add_argument("--role", choices=["all", "auditor", "remediator", "reviewer"], default="all", help="Target agent role for context generation")
     parser.add_argument("--target", help="Export target path")
     parser.add_argument("--source", help="Import source path")
+    parser.add_argument("--sanitized", action="store_true", help="Sanitize paths & secrets for export")
+    parser.add_argument("--before", help="Before code snippet for golden recipe")
+    parser.add_argument("--after", help="After code snippet for golden recipe")
+    parser.add_argument("--diff", help="Diff snippet for golden recipe")
     parser.add_argument("--ttl", type=int, default=DEFAULT_TTL_DAYS, help="Decay TTL in days")
     parser.add_argument("--older-than", type=int, default=30, help="Compaction age in days")
     parser.add_argument("--json", action="store_true", help="Output raw JSON")
@@ -862,7 +1252,12 @@ def main():
             print(f"Distilled {len(pats)} active patterns.")
 
     elif args.action == "context":
-        ctx = get_context(root_dir=root)
+        ctx = get_context(
+            target_role=args.role,
+            target_file=args.file,
+            rule_id=args.rule_id,
+            root_dir=root
+        )
         print(json.dumps(ctx, indent=2))
 
     elif args.action == "profile":
@@ -880,11 +1275,38 @@ def main():
         evt = record_false_positive(args.rule_id, file_path=args.file, reason=args.reason or "False positive", root_dir=root)
         print(f"Suppressed false positive for {args.rule_id}")
 
+    elif args.action == "recipe":
+        if not args.rule_id or not args.diff:
+            print("Error: --rule-id and --diff are required for recipe action", file=sys.stderr)
+            sys.exit(1)
+        rec = record_golden_recipe(
+            rule_id=args.rule_id,
+            before_snippet=args.before or "",
+            after_snippet=args.after or "",
+            diff_snippet=args.diff,
+            file_type=Path(args.file).suffix if args.file else ".py",
+            description=args.strategy or "Verified AST remediation recipe",
+            root_dir=root
+        )
+        print(json.dumps(rec, indent=2) if args.json else f"Recorded golden recipe: {rec['recipe_id']}")
+
+    elif args.action == "hook-install":
+        res_h = install_git_hook(root_dir=root)
+        print(json.dumps(res_h, indent=2) if args.json else f"Git pre-commit hook installed: {res_h['hook_path']}")
+
+    elif args.action == "hook-uninstall":
+        res_u = uninstall_git_hook(root_dir=root)
+        print(json.dumps(res_u, indent=2) if args.json else f"Git pre-commit hook {res_u['status']}")
+
+    elif args.action == "learn":
+        res_l = learn_from_git(root_dir=root)
+        print(json.dumps(res_l, indent=2) if args.json else f"Learned {res_l['learned_events_count']} events from git history.")
+
     elif args.action == "export":
         if not args.target:
             print("Error: --target is required for export action", file=sys.stderr)
             sys.exit(1)
-        res = export_memory(args.target, root_dir=root)
+        res = export_memory(args.target, sanitized=args.sanitized, root_dir=root)
         print(json.dumps(res, indent=2) if args.json else f"Exported {res['exported_events_count']} events to {res['target_path']}")
 
     elif args.action == "import":