buildlog 0.6.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

buildlog/render/cursor.py

@@ -0,0 +1,105 @@
+"""Render skills to Cursor rules format.
+
+Creates .cursor/rules/buildlog-rules.mdc with YAML frontmatter and
+Markdown body containing learned rules.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from buildlog.render.tracking import get_promoted_ids, track_promoted
+
+if TYPE_CHECKING:
+    from buildlog.skills import Skill
+
+
+class CursorRenderer:
+    """Creates .cursor/rules/buildlog-rules.mdc for Cursor IDE."""
+
+    def __init__(self, path: Path | None = None, tracking_path: Path | None = None):
+        """Initialize renderer.
+
+        Args:
+            path: Path to .mdc rules file. Defaults to .cursor/rules/buildlog-rules.mdc.
+            tracking_path: Path to promoted.json tracking file.
+                Defaults to .buildlog/promoted.json.
+        """
+        self.path = path or Path(".cursor/rules/buildlog-rules.mdc")
+        self.tracking_path = tracking_path or Path(".buildlog/promoted.json")
+
+    def render(self, skills: list[Skill]) -> str:
+        """Render skills to Cursor .mdc rules file.
+
+        Overwrites the file with all promoted skills (not append-only) since
+        Cursor reads the entire file on each invocation.
+
+        Args:
+            skills: List of skills to render.
+
+        Returns:
+            Confirmation message.
+        """
+        if not skills:
+            return "No skills to promote"
+
+        # Filter out already-promoted skills
+        already_promoted = get_promoted_ids(self.tracking_path)
+        new_skills = [s for s in skills if s.id not in already_promoted]
+
+        if not new_skills:
+            return f"All {len(skills)} skills already promoted"
+
+        # Group by category
+        by_category: dict[str, list[Skill]] = {}
+        for skill in new_skills:
+            by_category.setdefault(skill.category, []).append(skill)
+
+        category_titles = {
+            "architectural": "Architectural",
+            "workflow": "Workflow",
+            "tool_usage": "Tool Usage",
+            "domain_knowledge": "Domain Knowledge",
+        }
+
+        # Build MDC content with YAML frontmatter
+        lines = [
+            "---",
+            "description: Buildlog-learned rules for code quality",
+            "alwaysApply: true",
+            "---",
+            "",
+            "# Learned Rules",
+            "",
+            f"*Auto-generated by buildlog on {datetime.now().strftime('%Y-%m-%d')}*",
+            "",
+        ]
+
+        for category, cat_skills in by_category.items():
+            title = category_titles.get(category, category.replace("_", " ").title())
+            lines.append(f"## {title}")
+            lines.append("")
+            for skill in cat_skills:
+                conf = skill.confidence
+                freq = skill.frequency
+                lines.append(
+                    f"- **{skill.rule}** (confidence: {conf}, frequency: {freq})"
+                )
+            lines.append("")
+
+        content = "\n".join(lines)
+
+        # Write file
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(content)
+
+        # Track promoted skill IDs
+        track_promoted(new_skills, self.tracking_path)
+
+        skipped = len(skills) - len(new_skills)
+        msg = f"Wrote {len(new_skills)} rules to {self.path}"
+        if skipped > 0:
+            msg += f" ({skipped} already promoted, skipped)"
+        return msg

buildlog/render/tracking.py

@@ -10,7 +10,26 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from buildlog.skills import Skill
 
-__all__ = ["track_promoted"]
+__all__ = ["track_promoted", "get_promoted_ids"]
+
+
+def get_promoted_ids(tracking_path: Path) -> set[str]:
+    """Get the set of already-promoted skill IDs.
+
+    Args:
+        tracking_path: Path to the tracking JSON file.
+
+    Returns:
+        Set of skill IDs that have been promoted.
+    """
+    if not tracking_path.exists():
+        return set()
+
+    try:
+        tracking = json.loads(tracking_path.read_text())
+        return set(tracking.get("skill_ids", []))
+    except json.JSONDecodeError:
+        return set()
 
 
 def track_promoted(skills: list[Skill], tracking_path: Path) -> None:

buildlog/render/windsurf.py

@@ -0,0 +1,95 @@
+"""Render skills to Windsurf rules format.
+
+Creates .windsurf/rules/buildlog-rules.md with learned rules in
+plain Markdown format.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from buildlog.render.tracking import get_promoted_ids, track_promoted
+from buildlog.skills import _to_imperative
+
+if TYPE_CHECKING:
+    from buildlog.skills import Skill
+
+
+class WindsurfRenderer:
+    """Creates .windsurf/rules/buildlog-rules.md for Windsurf IDE."""
+
+    def __init__(self, path: Path | None = None, tracking_path: Path | None = None):
+        """Initialize renderer.
+
+        Args:
+            path: Path to rules file. Defaults to .windsurf/rules/buildlog-rules.md.
+            tracking_path: Path to promoted.json tracking file.
+                Defaults to .buildlog/promoted.json.
+        """
+        self.path = path or Path(".windsurf/rules/buildlog-rules.md")
+        self.tracking_path = tracking_path or Path(".buildlog/promoted.json")
+
+    def render(self, skills: list[Skill]) -> str:
+        """Render skills to Windsurf rules file.
+
+        Overwrites the file with all promoted skills.
+
+        Args:
+            skills: List of skills to render.
+
+        Returns:
+            Confirmation message.
+        """
+        if not skills:
+            return "No skills to promote"
+
+        # Filter out already-promoted skills
+        already_promoted = get_promoted_ids(self.tracking_path)
+        new_skills = [s for s in skills if s.id not in already_promoted]
+
+        if not new_skills:
+            return f"All {len(skills)} skills already promoted"
+
+        # Group by category
+        by_category: dict[str, list[Skill]] = {}
+        for skill in new_skills:
+            by_category.setdefault(skill.category, []).append(skill)
+
+        category_titles = {
+            "architectural": "Architectural",
+            "workflow": "Workflow",
+            "tool_usage": "Tool Usage",
+            "domain_knowledge": "Domain Knowledge",
+        }
+
+        # Build Markdown content
+        lines = [
+            f"## Learned Rules (buildlog {datetime.now().strftime('%Y-%m-%d')})",
+            "",
+        ]
+
+        for category, cat_skills in by_category.items():
+            title = category_titles.get(category, category.replace("_", " ").title())
+            lines.append(f"### {title}")
+            lines.append("")
+            for skill in cat_skills:
+                rule = _to_imperative(skill.rule, skill.confidence)
+                lines.append(f"- {rule}")
+            lines.append("")
+
+        content = "\n".join(lines)
+
+        # Write file
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(content)
+
+        # Track promoted skill IDs
+        track_promoted(new_skills, self.tracking_path)
+
+        skipped = len(skills) - len(new_skills)
+        msg = f"Wrote {len(new_skills)} rules to {self.path}"
+        if skipped > 0:
+            msg += f" ({skipped} already promoted, skipped)"
+        return msg

buildlog/seeds.py

@@ -156,6 +156,36 @@ class SeedFile:
         )
 
 
+def _validate_seed_schema(data: dict) -> bool:
+    """Validate seed file has expected schema structure.
+
+    Defense-in-depth validation for seed files. While yaml.safe_load
+    prevents code execution, this ensures data structure matches expectations.
+
+    Args:
+        data: Parsed YAML data.
+
+    Returns:
+        True if schema is valid, False otherwise.
+    """
+    if not isinstance(data, dict):
+        return False
+
+    # Rules must be a list if present
+    rules = data.get("rules", [])
+    if not isinstance(rules, list):
+        return False
+
+    # Each rule must be a dict with at least a "rule" key
+    for rule in rules:
+        if not isinstance(rule, dict):
+            return False
+        if "rule" not in rule:
+            return False
+
+    return True
+
+
 def load_seed_file(path: Path) -> SeedFile | None:
     """Load a single seed file from disk.
 
@@ -164,6 +194,10 @@ def load_seed_file(path: Path) -> SeedFile | None:
 
     Returns:
         Parsed SeedFile or None if loading fails.
+
+    Note:
+        Uses yaml.safe_load which is safe from code execution attacks.
+        Additional schema validation ensures data structure is as expected.
     """
     if not path.exists():
         logger.warning(f"Seed file not found: {path}")
@@ -171,7 +205,14 @@ def load_seed_file(path: Path) -> SeedFile | None:
 
     try:
         with open(path) as f:
+            # yaml.safe_load is safe - no arbitrary code execution
             data = yaml.safe_load(f)
+
+        # Validate schema before parsing
+        if not _validate_seed_schema(data):
+            logger.error(f"Invalid seed file schema: {path}")
+            return None
+
         return SeedFile.from_dict(data)
     except (yaml.YAMLError, KeyError, TypeError) as e:
         logger.error(f"Failed to parse seed file {path}: {e}")

buildlog/skills.py

@@ -23,7 +23,10 @@ import re
 from dataclasses import dataclass, field
 from datetime import date, datetime, timezone
 from pathlib import Path
-from typing import Final, Literal, TypedDict
+from typing import TYPE_CHECKING, Final, Literal, TypedDict
+
+if TYPE_CHECKING:
+    from buildlog.llm import LLMBackend
 
 from buildlog.confidence import ConfidenceConfig, ConfidenceMetrics
 from buildlog.confidence import calculate_confidence as calculate_continuous_confidence
@@ -83,6 +86,10 @@ class SkillDict(_SkillDictRequired, total=False):
     antipattern: str  # What does violation look like?
     rationale: str  # Why does this matter?
     persona_tags: list[str]  # Which reviewers use this rule?
+    # LLM-extracted scoring fields
+    severity: str  # critical/major/minor/info
+    scope: str  # global/module/function
+    applicability: list[str]  # contexts where relevant
 
 
 class SkillSetDict(TypedDict):
@@ -115,6 +122,9 @@ class Skill:
         antipattern: What does violation look like? (defensibility)
         rationale: Why does this rule matter? (defensibility)
         persona_tags: Which reviewer personas use this rule?
+        severity: How bad is ignoring this rule? (critical/major/minor/info)
+        scope: How broadly does this rule apply? (global/module/function)
+        applicability: Contexts where this rule is relevant.
     """
 
     id: str
@@ -131,6 +141,10 @@ class Skill:
     antipattern: str | None = None
     rationale: str | None = None
     persona_tags: list[str] = field(default_factory=list)
+    # LLM-extracted scoring
+    severity: str | None = None
+    scope: str | None = None
+    applicability: list[str] = field(default_factory=list)
 
     def to_dict(self) -> SkillDict:
         """Convert to dictionary for serialization.
@@ -159,6 +173,12 @@ class Skill:
             result["rationale"] = self.rationale
         if self.persona_tags:
             result["persona_tags"] = self.persona_tags
+        if self.severity is not None:
+            result["severity"] = self.severity
+        if self.scope is not None:
+            result["scope"] = self.scope
+        if self.applicability:
+            result["applicability"] = self.applicability
         return result
 
 
@@ -326,6 +346,7 @@ def _deduplicate_insights(
     patterns: list[PatternDict],
     threshold: float = MIN_SIMILARITY_THRESHOLD,
     backend: EmbeddingBackend | None = None,
+    llm_backend: LLMBackend | None = None,
 ) -> list[tuple[str, int, list[str], date | None, date | None]]:
     """Deduplicate similar insights into merged rules.
 
@@ -366,9 +387,17 @@ def _deduplicate_insights(
     results: list[tuple[str, int, list[str], date | None, date | None]] = []
 
     for group in groups:
-        # Use the shortest insight as the canonical rule (often cleaner)
-        canonical = min(group, key=lambda p: len(p["insight"]))
-        rule = canonical["insight"]
+        # Use LLM to select canonical form if available and group has >1 member
+        if llm_backend is not None and len(group) > 1:
+            try:
+                candidates = [p["insight"] for p in group]
+                rule = llm_backend.select_canonical(candidates)
+            except Exception:
+                canonical = min(group, key=lambda p: len(p["insight"]))
+                rule = canonical["insight"]
+        else:
+            canonical = min(group, key=lambda p: len(p["insight"]))
+            rule = canonical["insight"]
         frequency = len(group)
         sources = sorted(set(p["source"] for p in group))
 
@@ -434,6 +463,7 @@ def generate_skills(
     embedding_backend: str | None = None,
     confidence_config: ConfidenceConfig | None = None,
     include_review_learnings: bool = True,
+    llm: bool = False,
 ) -> SkillSet:
     """Generate skills from buildlog patterns and review learnings.
 
@@ -449,12 +479,21 @@ def generate_skills(
         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.
+        llm: If True and an LLM backend is available, use LLM for extraction,
+            canonical selection, and scoring. Falls back gracefully.
 
     Returns:
         SkillSet with generated skills.
     """
+    # Resolve LLM backend if requested
+    llm_backend = None
+    if llm:
+        from buildlog.llm import get_llm_backend
+
+        llm_backend = get_llm_backend(buildlog_dir=buildlog_dir)
+
     # Get distilled patterns
-    result = distill_all(buildlog_dir, since=since_date)
+    result = distill_all(buildlog_dir, since=since_date, llm=llm)
 
     # Get embedding backend
     backend = (
@@ -471,7 +510,9 @@ def generate_skills(
 
     for category in CATEGORIES:
         patterns = result.patterns.get(category, [])
-        deduplicated = _deduplicate_insights(patterns, backend=backend)
+        deduplicated = _deduplicate_insights(
+            patterns, backend=backend, llm_backend=llm_backend
+        )
 
         skills: list[Skill] = []
         for rule, frequency, sources, most_recent, earliest in deduplicated:
@@ -490,6 +531,25 @@ def generate_skills(
                     confidence_score, confidence_config
                 ).value
 
+            # LLM scoring for severity/scope/applicability
+            severity: str | None = None
+            scope: str | None = None
+            applicability_tags: list[str] = []
+            if llm_backend is not None:
+                try:
+                    scoring = llm_backend.score_rule(rule, category)
+                    severity = scoring.severity
+                    scope = scoring.scope
+                    applicability_tags = scoring.applicability
+                except Exception:
+                    pass  # Keep defaults (None/empty)
+
+            # Apply severity weighting to confidence score
+            if confidence_score is not None and severity is not None:
+                from buildlog.confidence import apply_severity_weight
+
+                confidence_score = apply_severity_weight(confidence_score, severity)
+
             skill = Skill(
                 id=_generate_skill_id(category, rule),
                 category=category,
@@ -500,6 +560,9 @@ def generate_skills(
                 tags=_extract_tags(rule),
                 confidence_score=confidence_score,
                 confidence_tier=confidence_tier,
+                severity=severity,
+                scope=scope,
+                applicability=applicability_tags,
             )
             skills.append(skill)
 

{buildlog-0.6.1.data → buildlog-0.8.0.data}/data/share/buildlog/copier.yml

@@ -20,10 +20,6 @@ update_claude_md:
   help: Add buildlog instructions to CLAUDE.md if it exists?
   default: true
 
-# Post-generation tasks
-_tasks:
-  - "{{ 'python3 post_gen.py' if update_claude_md else 'echo Skipping CLAUDE.md update' }}"
-
 _message_after_copy: |
   Build journal installed!
 

buildlog-0.8.0.data/data/share/buildlog/template/buildlog/_TEMPLATE_QUICK.md

@@ -0,0 +1,21 @@
+# Build Journal: [TITLE]
+
+**Date:** [YYYY-MM-DD]
+**Duration:** [X hours]
+
+## What I Did
+
+[What you built, fixed, or changed. 2-3 sentences.]
+
+## What Went Wrong
+
+[Mistakes, surprises, dead ends. Be specific — these become rules.]
+
+## What I Learned
+
+### Improvements
+
+- [One thing to do differently next time]
+- [One thing that worked well to repeat]
+
+*More sections: see _TEMPLATE.md for the full format.*

buildlog-0.8.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: buildlog
+Version: 0.8.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
+Author: Peleke Sengstacke
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,buildlog,development,documentation,journal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: copier>=9.0.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pymupdf>=1.26.7
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40.0; extra == 'all'
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: ollama>=0.4.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: flake8>=7.0.0; extra == 'dev'
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
+Provides-Extra: engine
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40.0; extra == 'llm'
+Requires-Dist: ollama>=0.4.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# buildlog
+
+### The Only Agent Learning System You Can Prove Works
+
+[![PyPI](https://img.shields.io/pypi/v/buildlog?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/buildlog/)
+[![Python](https://img.shields.io/pypi/pyversions/buildlog?style=for-the-badge&logo=python&logoColor=white)](https://python.org/)
+[![CI](https://img.shields.io/github/actions/workflow/status/Peleke/buildlog-template/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI)](https://github.com/Peleke/buildlog-template/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue?style=for-the-badge&logo=github)](https://peleke.github.io/buildlog-template/)
+
+**Falsifiable claims. Measurable outcomes. No vibes.**
+
+<img src="assets/hero-banner-perfectdeliberate.png" alt="buildlog - The Only Agent Learning System You Can Prove Works" width="800"/>
+
+> **RE: The art** — Yes, it's AI-generated. Yes, that's hypocritical for a project about rigor over vibes. Looking for an actual artist to pay for a real logo. If you know someone good, [open an issue](https://github.com/Peleke/buildlog-template/issues) or DM me. Budget exists.
+
+**[Read the full documentation](https://peleke.github.io/buildlog-template/)**
+
+</div>
+
+---
+
+Everyone's building "agent memory." Blog posts announce breakthroughs. Products ship with "learning" in the tagline. Ask them one question: **How do you know it works?**
+
+buildlog gives you the infrastructure to answer with data. It captures engineering knowledge from work sessions, extracts rules, selects which rules to surface using a Thompson Sampling bandit, and measures impact via Repeated Mistake Rate (RMR) across tracked experiments.
+
+## Features
+
+- **Structured capture** — Document work sessions as entries with mistakes, decisions, and outcomes
+- **Rule extraction** — Distill and deduplicate patterns into actionable rules
+- **Thompson Sampling bandit** — Automatic rule selection that balances exploration and exploitation
+- **Experiment tracking** — Sessions, mistakes, RMR calculation with statistical rigor
+- **Review gauntlet** — Curated reviewer personas (Security Karen, Test Terrorist) with HITL checkpoints
+- **Multi-agent support** — Render rules to Claude Code, Cursor, GitHub Copilot, Windsurf, Continue.dev
+- **MCP server** — Full Claude Code integration via `buildlog-mcp`
+
+## Quick Start
+
+```bash
+uv pip install buildlog   # or: pip install buildlog (inside a venv)
+buildlog init
+buildlog new my-feature
+buildlog distill && buildlog skills
+buildlog experiment start
+# ... work ...
+buildlog experiment end
+buildlog experiment report
+```
+
+## Documentation
+
+| Section | Description |
+|---------|------------|
+| [Installation](https://peleke.github.io/buildlog-template/getting-started/installation/) | Setup, extras, and initialization |
+| [Quick Start](https://peleke.github.io/buildlog-template/getting-started/quick-start/) | Full pipeline walkthrough |
+| [Core Concepts](https://peleke.github.io/buildlog-template/getting-started/concepts/) | The problem, the claim, and the metric |
+| [CLI Reference](https://peleke.github.io/buildlog-template/guides/cli-reference/) | Every command documented |
+| [MCP Integration](https://peleke.github.io/buildlog-template/guides/mcp-integration/) | Claude Code setup and available tools |
+| [Experiments](https://peleke.github.io/buildlog-template/guides/experiments/) | Running and measuring experiments |
+| [Review Gauntlet](https://peleke.github.io/buildlog-template/guides/review-gauntlet/) | Reviewer personas and the gauntlet loop |
+| [Multi-Agent Setup](https://peleke.github.io/buildlog-template/guides/multi-agent/) | Render rules to any AI coding agent |
+| [Theory](https://peleke.github.io/buildlog-template/theory/00-background/) | The math behind Thompson Sampling |
+| [Philosophy](https://peleke.github.io/buildlog-template/philosophy/) | Principles and honest limitations |
+
+## Contributing
+
+```bash
+git clone https://github.com/Peleke/buildlog-template
+cd buildlog-template
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+```
+
+We're especially interested in better context representations, credit assignment approaches, statistical methodology improvements, and real-world experiment results (positive or negative).
+
+## License
+
+MIT License — see [LICENSE](./LICENSE)
+
+---
+
+<div align="center">
+
+**"Agent learning" without measurement is just prompt engineering with extra steps.**
+
+**buildlog is measurement.**
+
+</div>