buildlog 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

buildlog/core/__init__.py

@@ -2,11 +2,15 @@
 
 from buildlog.core.operations import (
     DiffResult,
+    LearnFromReviewResult,
     PromoteResult,
     RejectResult,
+    ReviewIssue,
+    ReviewLearning,
     StatusResult,
     diff,
     find_skills_by_ids,
+    learn_from_review,
     promote,
     reject,
     status,
@@ -17,9 +21,13 @@ __all__ = [
     "PromoteResult",
     "RejectResult",
     "DiffResult",
+    "ReviewIssue",
+    "ReviewLearning",
+    "LearnFromReviewResult",
     "status",
     "promote",
     "reject",
     "diff",
     "find_skills_by_ids",
+    "learn_from_review",
 ]

buildlog/core/operations.py

@@ -6,12 +6,14 @@ MCP, CLI, HTTP, or any other interface.
 
 from __future__ import annotations
 
+import hashlib
 import json
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Literal
+from typing import Literal, TypedDict
 
+from buildlog.confidence import ConfidenceMetrics, merge_confidence_metrics
 from buildlog.render import get_renderer
 from buildlog.skills import Skill, SkillSet, generate_skills
 
@@ -20,11 +22,15 @@ __all__ = [
     "PromoteResult",
     "RejectResult",
     "DiffResult",
+    "ReviewIssue",
+    "ReviewLearning",
+    "LearnFromReviewResult",
     "status",
     "promote",
     "reject",
     "diff",
     "find_skills_by_ids",
+    "learn_from_review",
 ]
 
 
@@ -108,6 +114,175 @@ class DiffResult:
     """Error message if operation failed."""
 
 
+# -----------------------------------------------------------------------------
+# Review Learning Data Structures
+# -----------------------------------------------------------------------------
+
+
+class ReviewIssueDict(TypedDict, total=False):
+    """Serializable form of ReviewIssue."""
+
+    severity: str
+    category: str
+    description: str
+    rule_learned: str
+    location: str | None
+    why_it_matters: str | None
+    functional_principle: str | None
+
+
+@dataclass
+class ReviewIssue:
+    """A single issue identified during code review.
+
+    Attributes:
+        severity: How serious the issue is (critical/major/minor/nitpick).
+        category: What kind of issue (architectural/workflow/tool_usage/domain_knowledge).
+        description: What's wrong (concrete).
+        rule_learned: The generalizable rule extracted from this issue.
+        location: File:line where the issue was found.
+        why_it_matters: Why this issue matters (consequences).
+        functional_principle: Related FP principle, if applicable.
+    """
+
+    severity: Literal["critical", "major", "minor", "nitpick"]
+    category: Literal["architectural", "workflow", "tool_usage", "domain_knowledge"]
+    description: str
+    rule_learned: str
+    location: str | None = None
+    why_it_matters: str | None = None
+    functional_principle: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ReviewIssue":
+        """Construct from dictionary (e.g., from JSON)."""
+        return cls(
+            severity=data.get("severity", "minor"),
+            category=data.get("category", "workflow"),
+            description=data.get("description", ""),
+            rule_learned=data.get("rule_learned", ""),
+            location=data.get("location"),
+            why_it_matters=data.get("why_it_matters"),
+            functional_principle=data.get("functional_principle"),
+        )
+
+
+class ReviewLearningDict(TypedDict, total=False):
+    """Serializable form of ReviewLearning."""
+
+    id: str
+    rule: str
+    category: str
+    severity: str
+    source: str
+    first_seen: str
+    last_reinforced: str
+    reinforcement_count: int
+    contradiction_count: int
+    functional_principle: str | None
+
+
+@dataclass
+class ReviewLearning:
+    """A learning extracted from review, with confidence tracking.
+
+    Attributes:
+        id: Deterministic hash of rule_learned (category prefix + hash).
+        rule: The generalizable rule text.
+        category: Category of the learning.
+        severity: Severity of the original issue.
+        source: Where this learning came from (e.g., "review:PR#13").
+        first_seen: When this rule was first identified.
+        last_reinforced: When this rule was last seen/reinforced.
+        reinforcement_count: How many times this rule has been seen.
+        contradiction_count: How many times this rule was contradicted.
+        functional_principle: Related FP principle, if applicable.
+    """
+
+    id: str
+    rule: str
+    category: str
+    severity: str
+    source: str
+    first_seen: datetime
+    last_reinforced: datetime
+    reinforcement_count: int = 1
+    contradiction_count: int = 0
+    functional_principle: str | None = None
+
+    def to_confidence_metrics(self) -> ConfidenceMetrics:
+        """Convert to ConfidenceMetrics for scoring."""
+        return ConfidenceMetrics(
+            reinforcement_count=self.reinforcement_count,
+            last_reinforced=self.last_reinforced,
+            contradiction_count=self.contradiction_count,
+            first_seen=self.first_seen,
+        )
+
+    def to_dict(self) -> ReviewLearningDict:
+        """Convert to serializable dictionary."""
+        result: ReviewLearningDict = {
+            "id": self.id,
+            "rule": self.rule,
+            "category": self.category,
+            "severity": self.severity,
+            "source": self.source,
+            "first_seen": self.first_seen.isoformat(),
+            "last_reinforced": self.last_reinforced.isoformat(),
+            "reinforcement_count": self.reinforcement_count,
+            "contradiction_count": self.contradiction_count,
+        }
+        if self.functional_principle:
+            result["functional_principle"] = self.functional_principle
+        return result
+
+    @classmethod
+    def from_dict(cls, data: ReviewLearningDict) -> "ReviewLearning":
+        """Reconstruct from serialized dictionary."""
+        first_seen = datetime.fromisoformat(data["first_seen"])
+        last_reinforced = datetime.fromisoformat(data["last_reinforced"])
+
+        # Ensure timezone awareness
+        if first_seen.tzinfo is None:
+            first_seen = first_seen.replace(tzinfo=timezone.utc)
+        if last_reinforced.tzinfo is None:
+            last_reinforced = last_reinforced.replace(tzinfo=timezone.utc)
+
+        return cls(
+            id=data["id"],
+            rule=data["rule"],
+            category=data["category"],
+            severity=data["severity"],
+            source=data["source"],
+            first_seen=first_seen,
+            last_reinforced=last_reinforced,
+            reinforcement_count=data.get("reinforcement_count", 1),
+            contradiction_count=data.get("contradiction_count", 0),
+            functional_principle=data.get("functional_principle"),
+        )
+
+
+@dataclass
+class LearnFromReviewResult:
+    """Result of learning from a review.
+
+    Attributes:
+        new_learnings: IDs of newly created learnings.
+        reinforced_learnings: IDs of existing learnings that were reinforced.
+        total_issues_processed: Total number of issues processed.
+        source: Review source identifier.
+        message: Human-readable summary.
+        error: Error message if operation failed.
+    """
+
+    new_learnings: list[str]
+    reinforced_learnings: list[str]
+    total_issues_processed: int
+    source: str
+    message: str = ""
+    error: str | None = None
+
+
 def _get_rejected_path(buildlog_dir: Path) -> Path:
     """Get path to rejected.json file."""
     return buildlog_dir / ".buildlog" / "rejected.json"
@@ -386,3 +561,169 @@ def diff(
         already_promoted=len(promoted_ids),
         already_rejected=len(rejected_ids),
     )
+
+
+# -----------------------------------------------------------------------------
+# Review Learning Operations
+# -----------------------------------------------------------------------------
+
+
+def _get_learnings_path(buildlog_dir: Path) -> Path:
+    """Get path to review_learnings.json file."""
+    return buildlog_dir / ".buildlog" / "review_learnings.json"
+
+
+def _generate_learning_id(category: str, rule: str) -> str:
+    """Generate deterministic ID for a learning.
+
+    Uses category prefix + first 10 chars of SHA256 hash.
+    """
+    # Normalize: lowercase, strip whitespace
+    normalized = rule.lower().strip()
+    hash_input = f"{category}:{normalized}".encode("utf-8")
+    hash_hex = hashlib.sha256(hash_input).hexdigest()[:10]
+
+    # Category prefix mapping
+    prefix_map = {
+        "architectural": "arch",
+        "workflow": "wf",
+        "tool_usage": "tool",
+        "domain_knowledge": "dom",
+    }
+    prefix = prefix_map.get(category, category[:4])
+
+    return f"{prefix}-{hash_hex}"
+
+
+def _load_learnings(path: Path) -> dict:
+    """Load learnings from JSON file."""
+    if not path.exists():
+        return {"learnings": {}, "review_history": []}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {"learnings": {}, "review_history": []}
+
+
+def _save_learnings(path: Path, data: dict) -> None:
+    """Save learnings to JSON file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2))
+
+
+def learn_from_review(
+    buildlog_dir: Path,
+    issues: list[dict],
+    source: str | None = None,
+) -> LearnFromReviewResult:
+    """Capture learnings from a code review and update confidence metrics.
+
+    For each issue:
+    1. Generate deterministic ID from rule text
+    2. If exists: reinforce (increment count, update timestamp)
+    3. If new: create ReviewLearning with initial metrics
+    4. Persist to .buildlog/review_learnings.json
+
+    Args:
+        buildlog_dir: Path to buildlog directory.
+        issues: List of review issues with rule_learned field.
+        source: Optional source identifier (defaults to timestamp).
+
+    Returns:
+        LearnFromReviewResult with new/reinforced learning IDs.
+    """
+    if not issues:
+        return LearnFromReviewResult(
+            new_learnings=[],
+            reinforced_learnings=[],
+            total_issues_processed=0,
+            source=source or "",
+            error="No issues provided",
+        )
+
+    # Default source to timestamp
+    now = datetime.now(timezone.utc)
+    if source is None:
+        source = f"review:{now.isoformat()}"
+    elif not source.startswith("review:"):
+        source = f"review:{source}"
+
+    learnings_path = _get_learnings_path(buildlog_dir)
+    data = _load_learnings(learnings_path)
+
+    new_ids: list[str] = []
+    reinforced_ids: list[str] = []
+    processed = 0
+
+    for issue_dict in issues:
+        # Skip issues without rule_learned
+        rule = issue_dict.get("rule_learned", "").strip()
+        if not rule:
+            continue
+
+        # Parse issue
+        issue = ReviewIssue.from_dict(issue_dict)
+        learning_id = _generate_learning_id(issue.category, rule)
+
+        if learning_id in data["learnings"]:
+            # Reinforce existing learning
+            existing_data = data["learnings"][learning_id]
+            existing = ReviewLearning.from_dict(existing_data)
+
+            # Use merge_confidence_metrics pattern
+            updated_metrics = merge_confidence_metrics(
+                existing.to_confidence_metrics(), now
+            )
+
+            # Update the learning
+            existing_data["last_reinforced"] = now.isoformat()
+            existing_data["reinforcement_count"] = updated_metrics.reinforcement_count
+            reinforced_ids.append(learning_id)
+        else:
+            # Create new learning
+            learning = ReviewLearning(
+                id=learning_id,
+                rule=rule,
+                category=issue.category,
+                severity=issue.severity,
+                source=source,
+                first_seen=now,
+                last_reinforced=now,
+                reinforcement_count=1,
+                contradiction_count=0,
+                functional_principle=issue.functional_principle,
+            )
+            data["learnings"][learning_id] = learning.to_dict()
+            new_ids.append(learning_id)
+
+        processed += 1
+
+    # Record in review history
+    data["review_history"].append(
+        {
+            "timestamp": now.isoformat(),
+            "source": source,
+            "issues_count": processed,
+            "new_learning_ids": new_ids,
+            "reinforced_learning_ids": reinforced_ids,
+        }
+    )
+
+    # Persist
+    _save_learnings(learnings_path, data)
+
+    # Build message
+    msg_parts = []
+    if new_ids:
+        msg_parts.append(f"{len(new_ids)} new learning(s)")
+    if reinforced_ids:
+        msg_parts.append(f"{len(reinforced_ids)} reinforced")
+    message = ", ".join(msg_parts) if msg_parts else "No learnings captured"
+
+    return LearnFromReviewResult(
+        new_learnings=new_ids,
+        reinforced_learnings=reinforced_ids,
+        total_issues_processed=processed,
+        source=source,
+        message=message,
+    )

buildlog/mcp/__init__.py

@@ -2,6 +2,7 @@
 
 from buildlog.mcp.tools import (
     buildlog_diff,
+    buildlog_learn_from_review,
     buildlog_promote,
     buildlog_reject,
     buildlog_status,
@@ -12,4 +13,5 @@ __all__ = [
     "buildlog_promote",
     "buildlog_reject",
     "buildlog_diff",
+    "buildlog_learn_from_review",
 ]

buildlog/mcp/server.py

@@ -6,6 +6,7 @@ from mcp.server.fastmcp import FastMCP
 
 from buildlog.mcp.tools import (
     buildlog_diff,
+    buildlog_learn_from_review,
     buildlog_promote,
     buildlog_reject,
     buildlog_status,
@@ -18,6 +19,7 @@ mcp.tool()(buildlog_status)
 mcp.tool()(buildlog_promote)
 mcp.tool()(buildlog_reject)
 mcp.tool()(buildlog_diff)
+mcp.tool()(buildlog_learn_from_review)
 
 
 def main() -> None:

buildlog/mcp/tools.py

@@ -9,7 +9,7 @@ from dataclasses import asdict
 from pathlib import Path
 from typing import Literal
 
-from buildlog.core import diff, promote, reject, status
+from buildlog.core import diff, learn_from_review, promote, reject, status
 
 
 def _validate_skill_ids(skill_ids: list[str]) -> list[str]:
@@ -95,3 +95,48 @@ def buildlog_diff(
     """
     result = diff(Path(buildlog_dir))
     return asdict(result)
+
+
+def buildlog_learn_from_review(
+    issues: list[dict],
+    source: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Capture learnings from code review feedback.
+
+    Call this after a review loop completes to persist learnings.
+    Each issue's rule_learned becomes a tracked learning that gains
+    confidence through reinforcement.
+
+    Args:
+        issues: List of issues with structure:
+            {
+                "severity": "critical|major|minor|nitpick",
+                "category": "architectural|workflow|tool_usage|domain_knowledge",
+                "description": "What's wrong",
+                "rule_learned": "Generalizable rule",
+                "location": "file:line (optional)",
+                "why_it_matters": "Why this matters (optional)",
+                "functional_principle": "FP principle (optional)"
+            }
+        source: Optional identifier (e.g., "PR#13")
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Result with new_learnings, reinforced_learnings, total processed
+
+    Example:
+        buildlog_learn_from_review(
+            issues=[
+                {
+                    "severity": "critical",
+                    "category": "architectural",
+                    "description": "Score bounds not validated",
+                    "rule_learned": "Validate invariants at function boundaries"
+                }
+            ],
+            source="PR#13"
+        )
+    """
+    result = learn_from_review(Path(buildlog_dir), issues, source)
+    return asdict(result)

buildlog/skills.py

@@ -33,6 +33,18 @@ from buildlog.embeddings import EmbeddingBackend, get_backend, get_default_backe
 
 logger = logging.getLogger(__name__)
 
+
+def _load_review_learnings(buildlog_dir: Path) -> dict:
+    """Load review learnings from .buildlog/review_learnings.json."""
+    learnings_path = buildlog_dir / ".buildlog" / "review_learnings.json"
+    if not learnings_path.exists():
+        return {"learnings": {}}
+    try:
+        return json.loads(learnings_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {"learnings": {}}
+
+
 # Configuration constants
 MIN_SIMILARITY_THRESHOLD: Final[float] = 0.7
 HIGH_CONFIDENCE_FREQUENCY: Final[int] = 3
@@ -398,8 +410,9 @@ def generate_skills(
     since_date: date | None = None,
     embedding_backend: str | None = None,
     confidence_config: ConfidenceConfig | None = None,
+    include_review_learnings: bool = True,
 ) -> SkillSet:
-    """Generate skills from buildlog patterns.
+    """Generate skills from buildlog patterns and review learnings.
 
     Args:
         buildlog_dir: Path to the buildlog directory.
@@ -410,6 +423,9 @@ def generate_skills(
         confidence_config: Configuration for continuous confidence scoring.
             If provided, skills will include confidence_score and confidence_tier.
             If None, only discrete confidence levels (high/medium/low) are computed.
+        include_review_learnings: Whether to include learnings from code reviews.
+            When True, loads .buildlog/review_learnings.json and merges
+            review learnings into the skill set.
 
     Returns:
         SkillSet with generated skills.
@@ -468,6 +484,111 @@ def generate_skills(
         skills.sort(key=lambda s: (-s.frequency, s.rule))
         skills_by_category[category] = skills
 
+    # Merge review learnings if requested
+    if include_review_learnings:
+        review_data = _load_review_learnings(buildlog_dir)
+        learnings = review_data.get("learnings", {})
+
+        for learning_id, learning_dict in learnings.items():
+            category = learning_dict.get("category", "workflow")
+            rule = learning_dict.get("rule", "")
+
+            if not rule:
+                continue
+
+            # Parse timestamps for confidence calculation
+            first_seen_str = learning_dict.get("first_seen", "")
+            last_reinforced_str = learning_dict.get("last_reinforced", "")
+
+            try:
+                first_seen = datetime.fromisoformat(first_seen_str)
+                if first_seen.tzinfo is None:
+                    first_seen = first_seen.replace(tzinfo=timezone.utc)
+            except (ValueError, TypeError):
+                first_seen = datetime.now(timezone.utc)
+
+            try:
+                last_reinforced = datetime.fromisoformat(last_reinforced_str)
+                if last_reinforced.tzinfo is None:
+                    last_reinforced = last_reinforced.replace(tzinfo=timezone.utc)
+            except (ValueError, TypeError):
+                last_reinforced = datetime.now(timezone.utc)
+
+            # Get frequency from reinforcement count
+            frequency = learning_dict.get("reinforcement_count", 1)
+
+            # Check for duplicate rules in existing skills (by ID match)
+            existing_skill = None
+            if category in skills_by_category:
+                for skill in skills_by_category[category]:
+                    if skill.id == learning_id:
+                        existing_skill = skill
+                        break
+
+            if existing_skill is not None:
+                # Merge: boost the existing skill's frequency
+                existing_skill = Skill(
+                    id=existing_skill.id,
+                    category=existing_skill.category,
+                    rule=existing_skill.rule,
+                    frequency=existing_skill.frequency + frequency,
+                    confidence=existing_skill.confidence,
+                    sources=existing_skill.sources
+                    + [learning_dict.get("source", "review")],
+                    tags=existing_skill.tags,
+                    confidence_score=existing_skill.confidence_score,
+                    confidence_tier=existing_skill.confidence_tier,
+                )
+                # Replace in list
+                skills_by_category[category] = [
+                    existing_skill if s.id == existing_skill.id else s
+                    for s in skills_by_category[category]
+                ]
+            else:
+                # Create new skill from review learning
+                review_conf_score: float | None = None
+                review_conf_tier: str | None = None
+
+                if confidence_config is not None and t_now is not None:
+                    metrics = ConfidenceMetrics(
+                        reinforcement_count=frequency,
+                        last_reinforced=last_reinforced,
+                        contradiction_count=learning_dict.get("contradiction_count", 0),
+                        first_seen=first_seen,
+                    )
+                    review_conf_score = calculate_continuous_confidence(
+                        metrics, confidence_config, t_now
+                    )
+                    review_conf_tier = get_confidence_tier(
+                        review_conf_score, confidence_config
+                    ).value
+
+                # Calculate discrete confidence from most recent date
+                discrete_confidence = _calculate_confidence(
+                    frequency, last_reinforced.date()
+                )
+
+                skill = Skill(
+                    id=learning_id,
+                    category=category,
+                    rule=rule,
+                    frequency=frequency,
+                    confidence=discrete_confidence,
+                    sources=[learning_dict.get("source", "review")],
+                    tags=_extract_tags(rule),
+                    confidence_score=review_conf_score,
+                    confidence_tier=review_conf_tier,
+                )
+
+                # Add to category
+                if category not in skills_by_category:
+                    skills_by_category[category] = []
+                skills_by_category[category].append(skill)
+
+        # Re-sort categories after adding review learnings
+        for category in skills_by_category:
+            skills_by_category[category].sort(key=lambda s: (-s.frequency, s.rule))
+
     return SkillSet(
         generated_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         source_entries=result.entry_count,

{buildlog-0.3.0.dist-info → buildlog-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildlog
-Version: 0.3.0
+Version: 0.4.0
 Summary: Engineering notebook for AI-assisted development
 Project-URL: Homepage, https://github.com/Peleke/buildlog-template
 Project-URL: Repository, https://github.com/Peleke/buildlog-template
@@ -678,6 +678,7 @@ The MCP server lets Claude Code interact with your buildlog rules directly. Your
 | `buildlog_promote` | Write rules to CLAUDE.md, settings.json, or **Agent Skills** |
 | `buildlog_reject` | Mark rules to exclude from future suggestions |
 | `buildlog_diff` | Show rules pending review (not yet promoted/rejected) |
+| `buildlog_learn_from_review` | Capture learnings from code review feedback |
 
 ### Promotion Targets via MCP
 
@@ -717,6 +718,136 @@ Claude: [calls buildlog_promote with target="skill"]
 
 ---
 
+## Review Learning System
+
+Beyond manual buildlog entries, buildlog can **learn from code reviews** in real-time. Every review becomes a teaching moment—rules get extracted, persisted, and gain confidence through reinforcement.
+
+### How It Works
+
+```mermaid
+flowchart LR
+    A["Code Review"] --> B["Extract Rules"]
+    B --> C["learn_from_review()"]
+    C --> D["Persist to<br/>.buildlog/review_learnings.json"]
+    D --> E["Rules gain confidence<br/>through reinforcement"]
+    E --> F["Inject into<br/>future sessions"]
+```
+
+### The MCP Tool
+
+```python
+buildlog_learn_from_review(
+    issues=[
+        {
+            "severity": "critical",
+            "category": "architectural",
+            "description": "No bounds validation on score input",
+            "rule_learned": "Validate invariants at function boundaries"
+        }
+    ],
+    source="PR#42"
+)
+```
+
+When the same rule is learned from multiple reviews, its confidence increases automatically.
+
+### Reviewer Skills (The Brutal Feedback Loop)
+
+buildlog ships with **ruthless reviewer personas** that output structured JSON compatible with `buildlog_learn_from_review()`. Every review teaches the system.
+
+| Skill | Trigger | Focus |
+|-------|---------|-------|
+| **Ruthless Reviewer** | `review`, `code review` | Code quality, FP principles, invariants |
+| **Test Terrorist** | `test review`, `coverage audit` | ALL test types: unit, integration, E2E, contract, property-based |
+| **Security Karen** | `security review`, `owasp` | OWASP Top 10, input validation, auth |
+| **Review Gauntlet** | `gauntlet`, `destroy my code` | All three reviewers in sequence |
+
+#### The Review Gauntlet
+
+Run all three reviewers for maximum brutality:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     THE REVIEW GAUNTLET                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   Your Code                                                     │
+│       │                                                         │
+│       ▼                                                         │
+│   ┌──────────────────┐                                          │
+│   │  RUTHLESS        │  "Is this pure? Would it compile        │
+│   │  REVIEWER        │   in Haskell?"                           │
+│   └────────┬─────────┘                                          │
+│            ▼                                                    │
+│   ┌──────────────────┐                                          │
+│   │  TEST            │  "Where are your contract tests?        │
+│   │  TERRORIST       │   Show me the Gherkin."                  │
+│   └────────┬─────────┘                                          │
+│            ▼                                                    │
+│   ┌──────────────────┐                                          │
+│   │  SECURITY        │  "I need to speak to your security      │
+│   │  KAREN           │   manager about this SQL query."         │
+│   └────────┬─────────┘                                          │
+│            ▼                                                    │
+│   Combined Issues → buildlog_learn_from_review()               │
+│            ▼                                                    │
+│   Future sessions get smarter                                   │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Each reviewer outputs structured JSON:
+
+```json
+{
+  "verdict": "BLOCKED",
+  "issues": [
+    {
+      "severity": "critical",
+      "category": "architectural",
+      "location": "src/api/handler.py:45",
+      "description": "Score bounds not validated",
+      "rule_learned": "Validate invariants at function boundaries",
+      "functional_principle": "Parse, don't validate"
+    }
+  ]
+}
+```
+
+After review, call `buildlog_learn_from_review(issues=...)` to persist the learnings.
+
+### Test Terrorist Coverage
+
+The Test Terrorist knows ALL test types:
+
+| Layer | Test Types |
+|-------|-----------|
+| **Fundamentals** | Unit, Integration, E2E, Smoke |
+| **User Flows** | BDD scenarios, persistence tests |
+| **Advanced** | Contract (Pact), Property-based (Hypothesis), Metamorphic, Statistical, Mutation |
+| **Specialized** | Chaos, Load/Performance, Accessibility |
+
+**Contract tests are NON-NEGOTIABLE** for service boundaries. The Test Terrorist will find your missing ones.
+
+### Security Karen's OWASP Obsession
+
+Security Karen audits against OWASP Top 10 (2021):
+
+- **A01**: Broken Access Control
+- **A02**: Cryptographic Failures
+- **A03**: Injection
+- **A04**: Insecure Design
+- **A05**: Security Misconfiguration
+- **A06**: Vulnerable Components
+- **A07**: Auth Failures
+- **A08**: Integrity Failures
+- **A09**: Logging Failures
+- **A10**: SSRF
+
+Plus: secrets management, input validation, API security, error handling.
+
+---
+
 ## Philosophy
 
 ### 1. Write Fast, Not Pretty

{buildlog-0.3.0.dist-info → buildlog-0.4.0.dist-info}/RECORD

@@ -3,28 +3,28 @@ buildlog/cli.py,sha256=cmg77_RVJx8mdtStApS1KXxBUUB8Id6psHZjtHo33iE,14350
 buildlog/confidence.py,sha256=EOkPxIH1_y7k6B3Hl7Wn0iR2qK_lumvOyyyqUdafXVY,9382
 buildlog/distill.py,sha256=fqXW_YyBFIFhwIWhnR-TQ7U65gypqG-mcAzNBr-qaag,11262
 buildlog/embeddings.py,sha256=vPydWjJVkYp172zFou-lJ737qsu6vRMQAMs143RGIpA,12364
-buildlog/skills.py,sha256=ZR3cTn19WCCB2DjDRN2jyJOhXs7FazDkulRXYAZnquU,24757
+buildlog/skills.py,sha256=C_tqspj9lVRkjF-g-KpKt8WoQ-Xq0e0l1VtXly_Naks,30055
 buildlog/stats.py,sha256=2WdHdmzUNGobtWngmm9nA_UmqM7DQeAnZL8_rLQN8aw,13256
-buildlog/core/__init__.py,sha256=07N1gRiPQQTBtLp9rsEErh39sgXWZSlEKWBn708SoQk,412
-buildlog/core/operations.py,sha256=o01z2Sy0fgiBK6Z90Lkg6ACoqihH3-HC-hkPBSdj9mA,10656
-buildlog/mcp/__init__.py,sha256=Eaoa7aRWa428ORxyvneH1cKW7XxuBpF4qvM9mTEH7Ds,268
-buildlog/mcp/server.py,sha256=sgEMYBYq1tNKddvtyTpQ_M1dZHj7FhePDzwz7saIPH0,512
-buildlog/mcp/tools.py,sha256=KbO1NjogCWHECTIzFYSeAikJGG8fIMDNDOBicdKXDdY,2818
+buildlog/core/__init__.py,sha256=ifByeEE3sM13EHWIKNAOjNc3zx_4qYEfyXdB4Woumuw,594
+buildlog/core/operations.py,sha256=Q9wX8kfnpDBAC8ySHYXZi3vA9w0vuOyzOYl6JYB6YyM,22006
+buildlog/mcp/__init__.py,sha256=jCLNUkYFrDcPd5dY9xbaaVANl-ZzdPim1BykgGY7f7U,334
+buildlog/mcp/server.py,sha256=vlfXlRvGfoXBhkHv2y5e1jc7JH2Hkv7G1obSdxlQ14w,583
+buildlog/mcp/tools.py,sha256=Rfk3dS4bLflvaUa5O2YLdvBx354ZQ_Lfy-Uoaz_AjGo,4397
 buildlog/render/__init__.py,sha256=VxJWEmcX7pSiC3W-ytsHv9gNVUr4hJrVHBW084kEnAI,1993
 buildlog/render/base.py,sha256=gQfvOsH1zttAo10xtEyNsAbqZ4NRSPiDihO-aiGgTsw,533
 buildlog/render/claude_md.py,sha256=Z_E6MbJyVM_hJSoB4KL2rvbt5UEQHekTpJijj106lsI,2624
 buildlog/render/settings_json.py,sha256=4DS5OWksPrFCa7MIgWIu0t4rxYmItpMdGfTqMX3aMNs,2495
 buildlog/render/skill.py,sha256=_7umIS1Ms1oQ2_PopYueFjX41nMq1p28yJp6DhXFdgU,5981
 buildlog/render/tracking.py,sha256=6O0RIU-1gjVG-_S5dmXLz6RCMsQoHOR2u5___UpqXEo,1294
-buildlog-0.3.0.data/data/share/buildlog/copier.yml,sha256=A-1JKV59kOe0BQosGUBgRCg7iQozP_qyA3zfoHwpBKY,927
-buildlog-0.3.0.data/data/share/buildlog/post_gen.py,sha256=XFlo40LuPpAsBhIRRRtHqvU3_5POss4L401hp35ijhw,1744
-buildlog-0.3.0.data/data/share/buildlog/template/buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-buildlog-0.3.0.data/data/share/buildlog/template/buildlog/2026-01-01-example.md,sha256=7x9sKmydfmfKyNz9hV7MtYnQJuBwbxNanbPOcpQDDZQ,7040
-buildlog-0.3.0.data/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md,sha256=osclytWwl5jUiTgSpuT4cT3h3oPvCkZ5GPCnFuJZNcY,3802
-buildlog-0.3.0.data/data/share/buildlog/template/buildlog/_TEMPLATE.md,sha256=CUvxgcx1-9XT_EdQ8e_vnuPq_h-u1uhXJgForJU2Pso,2932
-buildlog-0.3.0.data/data/share/buildlog/template/buildlog/assets/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-buildlog-0.3.0.dist-info/METADATA,sha256=v2RWbkwAEgpZtshu6jiqr5X9cV713Ml_SGhhVywmLLA,24188
-buildlog-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-buildlog-0.3.0.dist-info/entry_points.txt,sha256=BMFclPOomp_sgaa0OqBg6LfqCMlqzjZV88ww5TrPPoo,87
-buildlog-0.3.0.dist-info/licenses/LICENSE,sha256=fAgt-akug9nAwIj6M-SIf8u3ck-T7pJTwfmy9vWYASk,1074
-buildlog-0.3.0.dist-info/RECORD,,
+buildlog-0.4.0.data/data/share/buildlog/copier.yml,sha256=A-1JKV59kOe0BQosGUBgRCg7iQozP_qyA3zfoHwpBKY,927
+buildlog-0.4.0.data/data/share/buildlog/post_gen.py,sha256=XFlo40LuPpAsBhIRRRtHqvU3_5POss4L401hp35ijhw,1744
+buildlog-0.4.0.data/data/share/buildlog/template/buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildlog-0.4.0.data/data/share/buildlog/template/buildlog/2026-01-01-example.md,sha256=7x9sKmydfmfKyNz9hV7MtYnQJuBwbxNanbPOcpQDDZQ,7040
+buildlog-0.4.0.data/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md,sha256=osclytWwl5jUiTgSpuT4cT3h3oPvCkZ5GPCnFuJZNcY,3802
+buildlog-0.4.0.data/data/share/buildlog/template/buildlog/_TEMPLATE.md,sha256=CUvxgcx1-9XT_EdQ8e_vnuPq_h-u1uhXJgForJU2Pso,2932
+buildlog-0.4.0.data/data/share/buildlog/template/buildlog/assets/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildlog-0.4.0.dist-info/METADATA,sha256=adRpA8HpJlbAFLk7UCbHPqhWXNU7Xp9WEfYo-e4GqXI,30019
+buildlog-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+buildlog-0.4.0.dist-info/entry_points.txt,sha256=BMFclPOomp_sgaa0OqBg6LfqCMlqzjZV88ww5TrPPoo,87
+buildlog-0.4.0.dist-info/licenses/LICENSE,sha256=fAgt-akug9nAwIj6M-SIf8u3ck-T7pJTwfmy9vWYASk,1074
+buildlog-0.4.0.dist-info/RECORD,,