skillpool 4.3.0__tar.gz

skillpool-4.3.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: skillpool
+Version: 4.3.0
+Summary: Skill Pool V4.3 — AI Agent Skill Governance & Delivery Platform
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: fastmcp>=0.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: graph
+Requires-Dist: numpy>=1.24; extra == "graph"
+Requires-Dist: scipy>=1.10; extra == "graph"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-bdd>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"

skillpool-4.3.0/README.md

@@ -0,0 +1,100 @@
+# SkillPool v4.3.0
+
+> AI Agent Skill Governance & Delivery Platform — MCP Resources/Tools/Prompts architecture
+
+## Quick Start
+
+```bash
+# Install (editable)
+pip install -e .
+
+# CLI
+skillpool --version
+skillpool inspect S09
+
+# MCP Server (stdio)
+skillpool-mcp
+```
+
+## Architecture (V4.3 Dual-Channel)
+
+| Channel | Transport | Purpose |
+|---------|-----------|---------|
+| CLI | Start Hook | Materialization — one-time SKILL.md file writes |
+| MCP Resources | stdio | Read-only context delivery (skill definitions, audit, bugs) |
+| MCP Tools | stdio | State-changing governance actions (register, gate, heal) |
+| MCP Prompts | stdio | User-controlled templates (review, skill context) |
+
+## MCP Resources (Read-Only)
+
+| URI | Description |
+|-----|-------------|
+| `skill://list` | All skills metadata (L0 tier, ~50 tokens/skill) |
+| `skill://{id}/summary` | Medium detail (L1 tier, ~200 tokens) |
+| `skill://{id}/definition` | Full SKILL.md content (L2 tier) |
+| `skill://{id}/manifest.yaml` | Dependencies, conflicts, veto rules |
+| `skill://{id}/x-execution` | Execution method + input/output schema |
+| `skill://graph` | Skill dependency DAG |
+| `audit://records` | Audit hash chain (read-only, immutable) |
+| `bug://list` | BugCollector defect records |
+
+## MCP Tools (Governance Actions)
+
+| Tool | Description |
+|------|-------------|
+| `gate_check` | Gate decision (ALLOW/GUARD/ESCALATE/DENY) |
+| `telemetry_report` | Report telemetry event |
+| `audit_verify` | Verify audit hash chain integrity |
+| `security_scan` | Pre-materialization security gate |
+| `healing_scan` | Scan bugs for recurring defects, propose healing |
+| `healing_execute` | Execute healing with BDD verify + auto-rollback |
+| `skill_register` | Register skill candidate into Registry |
+| `skill_transition` | Transition skill lifecycle state |
+| `evolution_trigger` | Record defect triggering evolution |
+| `evolution_proposal` | Create recommendation-only evolution proposal |
+| `monitor_evaluate` | Five-dimension skill evaluation |
+| `health_check` | System health check |
+| `review_trigger` | Trigger review checkpoint (L1-L4) |
+
+## MCP Prompts (User-Controlled)
+
+| Prompt | Description |
+|--------|-------------|
+| `skill_context {skill_id}` | Inject skill definition + dependencies |
+| `trigger_review` | Multi-dimension review (uses MCP Resources) |
+| `gate_status {skill_id}` | Check gate decision for a skill |
+
+## Security Architecture
+
+Three-layer pre-materialization security gate:
+1. **Hook layer**: SecurityScanner — YAML safety + dangerous pattern scanning
+2. **MCP layer**: `gate_check` tool — complexity assessment + profile matching
+3. **Audit layer**: Immutable hash chain — all actions recorded, tamper-evident
+
+Timeout degradation: `gate_check` → DENY, `telemetry` → silent, `health_check` → DEGRADED
+
+## Key Modules
+
+| Module | Description |
+|--------|-------------|
+| Lifecycle | 9-state skill lifecycle state machine |
+| Profile | Agent capability profiles (Claude Code/Codex/Hermes) |
+| Gate | Gate management + complexity assessment |
+| Materializer | CSDF → SKILL.md materialization engine (14 mapping rules) |
+| LazySkillLoader | L0/L1/L2 tiered loading with cache + thread safety |
+| Resolver | Skill chain resolution + DAG + circuit breaker + rate limiter |
+| Review | Review trigger + VETO V1-V6 + L1-L4 checkpoints |
+| BugCollector | 4-stage defect pipeline (Capture→Enrich→Filter→Persist) |
+| SelfHealingLoop | BugCollector → Evolver → BDD verify → auto-rollback |
+| SecurityScanner | YAML safety + dangerous pattern scanning + signature placeholder |
+| Audit | 34-field OTel audit + SHA-256 hash chain |
+| Evolver | Defect accumulation + Add/Merge/Discard evolution |
+| Registry | Skill registry + supply chain evidence + 9-state lifecycle |
+
+## Test Baseline
+
+1027 tests passing (V4.3.0)
+
+## License
+
+MIT

skillpool-4.3.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skillpool"
+version = "4.3.0"
+description = "Skill Pool V4.3 — AI Agent Skill Governance & Delivery Platform"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+dependencies = [
+    "click>=8.0",
+    "pydantic>=2.0",
+    "fastmcp>=0.2.0",
+    "pyyaml>=6.0",
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+graph = ["numpy>=1.24", "scipy>=1.10"]
+dev = ["pytest>=7.0", "pytest-cov>=4.0", "pytest-xdist>=3.0", "pytest-asyncio>=0.21", "pytest-bdd>=7.0", "ruff>=0.1"]
+
+[project.scripts]
+skillpool = "skillpool.cli:main"
+skillpool-mcp = "skillpool.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["skillpool"]
+branch = true
+omit = [
+    "*/skillpool/cli.py",           # Click CLI — tested via subprocess
+    "*/skillpool/__main__.py",      # Entry point
+    "*/skillpool/adapters/*",       # Adapter stubs (not yet implemented)
+    "*/skillpool/bridge/*",         # Bridge module (WIP)
+    "*/skillpool/csdf.py",          # CSDF standalone (covered via materializer)
+    "*/skillpool/quality.py",       # Quality module (placeholder)
+    "*/skillpool/synergy/detector.py",  # 2-line re-export
+    "*/skillpool/mcp_server.py",    # FastMCP server — tested via E2E, not unit-cov
+]
+
+[tool.coverage.report]
+fail_under = 90
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"

skillpool-4.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skillpool-4.3.0/src/skillpool/__init__.py

@@ -0,0 +1,74 @@
+"""SkillPool — Skill lifecycle management system."""
+
+from skillpool.audit import AuditLayer, AuditRecord, AuditUnavailableError, log_event
+from skillpool.clawmem_client import ClawMemClient
+from skillpool.cost import CostManager
+from skillpool.evolver import EvolverLayer, EvolutionProposal, DefectSeverity
+from skillpool.gate import GateManager
+
+# graph is lazy-imported via __getattr__ (numpy/scipy are optional)
+from skillpool.health import HealthManager
+from skillpool.lifecycle import SkillLifecycleState
+from skillpool.materializer import Materializer
+from skillpool.monitor import MonitorLayer, TelemetryBridge, FiveDimensionEvaluation
+from skillpool.paradigm import ParadigmRegistry
+from skillpool.profile import AgentCapabilityProfile
+from skillpool.registry import Registry, SkillRecord, SkillStatus
+from skillpool.resolver import SkillResolver
+from skillpool.review import ReviewManager
+from skillpool.telemetry import TelemetryBridge as CoreTelemetryBridge
+
+
+def __getattr__(name: str):
+    """Lazy import for graph module (numpy/scipy are optional dependencies)."""
+    if name in ("personalized_pagerank", "reverse_ppr"):
+        from skillpool.graph import personalized_pagerank, reverse_ppr  # noqa: F401
+
+        return locals().get(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Audit
+    "AuditLayer",
+    "AuditRecord",
+    "AuditUnavailableError",
+    "log_event",
+    # ClawMem
+    "ClawMemClient",
+    # Cost
+    "CostManager",
+    # Evolver
+    "EvolverLayer",
+    "EvolutionProposal",
+    "DefectSeverity",
+    # Gate
+    "GateManager",
+    # Graph
+    "personalized_pagerank",
+    "reverse_ppr",
+    # Health
+    "HealthManager",
+    # Lifecycle
+    "SkillLifecycleState",
+    # Materializer
+    "Materializer",
+    # Monitor
+    "MonitorLayer",
+    "TelemetryBridge",
+    "FiveDimensionEvaluation",
+    # Paradigm
+    "ParadigmRegistry",
+    # Profile
+    "AgentCapabilityProfile",
+    # Registry
+    "Registry",
+    "SkillRecord",
+    "SkillStatus",
+    # Resolver
+    "SkillResolver",
+    # Review
+    "ReviewManager",
+    # Core telemetry
+    "CoreTelemetryBridge",
+]

skillpool-4.3.0/src/skillpool/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running skillpool as: python -m skillpool"""
+
+from skillpool.cli import main
+
+if __name__ == "__main__":
+    main()

skillpool-4.3.0/src/skillpool/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""SkillPool Agent Adapters — unified interface for agent runtime integration."""
+
+from .base import AgentAdapter
+from .claude_adapter import ClaudeAdapter
+from .codex_adapter import CodexAdapter
+from .hermes_adapter import HermesAdapter
+
+__all__ = ["AgentAdapter", "ClaudeAdapter", "CodexAdapter", "HermesAdapter"]

skillpool-4.3.0/src/skillpool/adapters/base.py

@@ -0,0 +1,41 @@
+"""SkillPool Agent Adapter — Base class for agent runtime integration."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from skillpool.csdf import CSDFDocument
+from skillpool.materializer import MaterializationResult, Materializer
+
+
+class AgentAdapter(ABC):
+    """Base class for agent-specific skill adapters.
+
+    Subclasses must implement:
+    - render_skill: format a CSDF document for the target agent
+    - install_skill: place the rendered skill in the agent's runtime directory
+    - verify_skill: confirm the skill is accessible to the agent
+    """
+
+    def __init__(self, materializer: Materializer | None = None, state_dir: Path = Path(".skillpool")) -> None:
+        self.materializer = materializer or Materializer(state_dir)
+
+    @abstractmethod
+    def render_skill(self, doc: CSDFDocument) -> str:
+        """Render a CSDF document into the agent's native format."""
+        ...
+
+    @abstractmethod
+    def install_skill(self, doc: CSDFDocument, target_dir: Path) -> MaterializationResult:
+        """Render and install a skill into the agent's runtime directory."""
+        ...
+
+    @abstractmethod
+    def verify_skill(self, name: str, target_dir: Path) -> bool:
+        """Verify a skill is installed and accessible."""
+        ...
+
+    def materialize_and_install(self, doc: CSDFDocument, target_dir: Path) -> MaterializationResult:
+        """Convenience: render + install in one call."""
+        return self.install_skill(doc, target_dir)

skillpool-4.3.0/src/skillpool/adapters/claude_adapter.py

@@ -0,0 +1,36 @@
+"""Claude Agent Adapter — skill integration for Claude runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from skillpool.csdf import CSDFDocument
+from skillpool.materializer import MaterializationResult, Materializer
+
+from .base import AgentAdapter
+
+
+class ClaudeAdapter(AgentAdapter):
+    """Adapter for Claude agent runtime.
+
+    Claude expects SKILL.md files with ### When to use / ### Instructions.
+    """
+
+    def __init__(self, materializer: Materializer | None = None, state_dir: Path = Path(".skillpool")) -> None:
+        super().__init__(materializer, state_dir)
+        self.agent_type = "claude"
+
+    def render_skill(self, doc: CSDFDocument) -> str:
+        """Render CSDF as Claude-compatible SKILL.md."""
+        triggers = "\n".join(f"- {t}" for t in doc.triggers) if doc.triggers else "- (none)"
+        return f"# {doc.name}\n\n{doc.description}\n\n### When to use\n{triggers}\n\n### Instructions\n{doc.body}\n"
+
+    def install_skill(self, doc: CSDFDocument, target_dir: Path) -> MaterializationResult:
+        """Materialize and install skill into Claude skills directory."""
+        output_path = target_dir / f"{doc.name}.md"
+        return self.materializer.materialize(doc, agent_type=self.agent_type, output_path=output_path)
+
+    def verify_skill(self, name: str, target_dir: Path) -> bool:
+        """Check if a Claude skill file exists and is non-empty."""
+        skill_file = target_dir / f"{name}.md"
+        return skill_file.exists() and skill_file.stat().st_size > 0

skillpool-4.3.0/src/skillpool/adapters/codex_adapter.py

@@ -0,0 +1,92 @@
+"""Codex Agent Adapter — skill integration for Codex runtime."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from skillpool.config import get_data_dir
+from skillpool.csdf import CSDFDocument
+from skillpool.materializer import MaterializationResult, Materializer
+
+from .base import AgentAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class CodexAdapter(AgentAdapter):
+    """Adapter for Codex agent runtime.
+
+    Codex expects SKILL.md files with ## Triggers / ## Instructions sections.
+    Startup hook auto-registers skills from ~/.skillpool/skills/ on init.
+    """
+
+    def __init__(self, materializer: Materializer | None = None, state_dir: Path = Path(".skillpool")) -> None:
+        super().__init__(materializer, state_dir)
+        self.agent_type = "codex"
+        self._skills_dir = get_data_dir() / "skills"
+
+    def render_skill(self, doc: CSDFDocument) -> str:
+        """Render CSDF as Codex-compatible SKILL.md."""
+        triggers = "\n".join(f"- {t}" for t in doc.triggers) if doc.triggers else "- (none)"
+        return f"# {doc.name}\n\n{doc.description}\n\n## Triggers\n{triggers}\n\n## Instructions\n{doc.body}\n"
+
+    def install_skill(self, doc: CSDFDocument, target_dir: Path) -> MaterializationResult:
+        """Materialize and install skill into Codex skills directory."""
+        output_path = target_dir / f"{doc.name}.md"
+        return self.materializer.materialize(doc, agent_type=self.agent_type, output_path=output_path)
+
+    def verify_skill(self, name: str, target_dir: Path) -> bool:
+        """Check if a Codex skill file exists and is non-empty."""
+        skill_file = target_dir / f"{name}.md"
+        return skill_file.exists() and skill_file.stat().st_size > 0
+
+    def on_startup(self, target_dir: Path | None = None) -> dict[str, bool]:
+        """Startup hook: auto-register all skills from SkillPool.
+
+        Called when Codex initializes to sync skills from ~/.skillpool/skills/
+        to the Codex skills directory.
+
+        Args:
+            target_dir: Codex skills directory (defaults to ~/.codex/skills/).
+
+        Returns:
+            Dict mapping skill_id to install success status.
+        """
+        from skillpool.materializer.csdf_loader import load_csdf
+
+        target = target_dir or Path.home() / ".codex" / "skills"
+        target.mkdir(parents=True, exist_ok=True)
+
+        results: dict[str, bool] = {}
+
+        if not self._skills_dir.exists():
+            logger.info("Codex startup hook: no skills directory found at %s", self._skills_dir)
+            return results
+
+        # Scan for CSDF YAML files
+        for yaml_file in sorted(self._skills_dir.glob("*.yaml")):
+            if yaml_file.name == "skill_graph.yaml":
+                continue
+            skill_id = yaml_file.stem.split("-")[0]
+            try:
+                csdf_data = load_csdf(skill_id, self._skills_dir)
+                if csdf_data is None:
+                    continue
+                doc = CSDFDocument(**csdf_data)
+                # Render and write directly (bypass broken install_skill)
+                rendered = self.render_skill(doc)
+                output_path = target / f"{doc.name}.md"
+                output_path.write_text(rendered, encoding="utf-8")
+                success = output_path.exists() and output_path.stat().st_size > 0
+                results[skill_id] = success
+                if success:
+                    logger.debug("Codex startup hook: installed %s", skill_id)
+                else:
+                    logger.warning("Codex startup hook: failed to install %s (empty file)", skill_id)
+            except Exception as e:
+                logger.error("Codex startup hook: error installing %s: %s", skill_id, e)
+                results[skill_id] = False
+
+        logger.info("Codex startup hook: registered %d/%d skills", sum(results.values()), len(results))
+        return results

skillpool-4.3.0/src/skillpool/adapters/hermes_adapter.py

@@ -0,0 +1,38 @@
+"""Hermes Agent Adapter — skill integration for Hermes TUI runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from skillpool.csdf import CSDFDocument
+from skillpool.materializer import MaterializationResult, Materializer
+
+from .base import AgentAdapter
+
+
+class HermesAdapter(AgentAdapter):
+    """Adapter for Hermes TUI agent runtime.
+
+    Hermes is a TUI agent that reads skills from ~/.hermes/skills/.
+    Format: SKILL.md with ## When to use / ## Instructions sections,
+    matching the directory-based skill layout Hermes expects.
+    """
+
+    def __init__(self, materializer: Materializer | None = None, state_dir: Path = Path(".skillpool")) -> None:
+        super().__init__(materializer, state_dir)
+        self.agent_type = "hermes"
+
+    def render_skill(self, doc: CSDFDocument) -> str:
+        """Render CSDF as Hermes-compatible SKILL.md."""
+        triggers = "\n".join(f"- {t}" for t in doc.triggers) if doc.triggers else "- (none)"
+        return f"# {doc.name}\n\n{doc.description}\n\n## When to use\n{triggers}\n\n## Instructions\n{doc.body}\n"
+
+    def install_skill(self, doc: CSDFDocument, target_dir: Path) -> MaterializationResult:
+        """Materialize and install skill into Hermes skills directory."""
+        output_path = target_dir / f"{doc.name}.md"
+        return self.materializer.materialize(doc, agent_type=self.agent_type, output_path=output_path)
+
+    def verify_skill(self, name: str, target_dir: Path) -> bool:
+        """Check if a Hermes skill file exists and is non-empty."""
+        skill_file = target_dir / f"{name}.md"
+        return skill_file.exists() and skill_file.stat().st_size > 0