specsmith 0.10.1.dev283__tar.gz → 0.10.1.dev287__tar.gz

{specsmith-0.10.1.dev283 → specsmith-0.10.1.dev287}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.10.1.dev283
+Version: 0.10.1.dev287
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.10.1.dev283 → specsmith-0.10.1.dev287}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.10.1.dev283"
+version = "0.10.1.dev287"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

{specsmith-0.10.1.dev283 → specsmith-0.10.1.dev287}/src/specsmith/cli.py

@@ -7965,16 +7965,20 @@ main.add_command(rules_group)
 # ---------------------------------------------------------------------------
 try:
     from specsmith.commands.intelligence import (
+        compliance_group,
         datasources_group,
         models_group,
         profiles_group,
         providers_group,
+        session_group,
     )
 
     main.add_command(providers_group)
     main.add_command(profiles_group)
     main.add_command(datasources_group)
     main.add_command(models_group)
+    main.add_command(compliance_group)
+    main.add_command(session_group)
 except Exception:  # noqa: BLE001
     pass  # graceful degradation if commands module has issues
 

{specsmith-0.10.1.dev283 → specsmith-0.10.1.dev287}/src/specsmith/commands/intelligence.py

@@ -290,3 +290,127 @@ def models_rank(role: str, provider_type: str) -> None:
     click.echo(f"Top models for '{role}':")
     for model, score in ranked[:10]:
         click.echo(f"  {score:5.1f}  {model}")
+
+
+# ---------------------------------------------------------------------------
+# specsmith compliance
+# ---------------------------------------------------------------------------
+
+
+@click.group("compliance")
+def compliance_group() -> None:
+    """Compliance scoring, gaps, and traceability."""
+
+
+@compliance_group.command("summary")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--json-output", "as_json", is_flag=True)
+def compliance_summary(project_dir: str, as_json: bool) -> None:
+    """Show overall compliance score and coverage."""
+    from specsmith.compliance import get_compliance_summary
+
+    s = get_compliance_summary(project_dir)
+    if as_json:
+        click.echo(json.dumps(s.to_dict(), indent=2))
+    else:
+        click.echo(f"  Requirements: {s.covered_requirements}/{s.total_requirements} covered")
+        click.echo(f"  Tests:        {s.total_tests}")
+        click.echo(f"  Coverage:     {s.requirement_coverage_pct}%")
+        click.echo(f"  Score:        {s.compliance_score}%")
+        if s.uncovered_requirements:
+            click.echo(f"  Uncovered:    {', '.join(s.uncovered_requirements[:10])}")
+
+
+@compliance_group.command("gaps")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def compliance_gaps(project_dir: str) -> None:
+    """Show uncovered requirements and orphaned tests."""
+    from specsmith.compliance import get_compliance_summary
+
+    s = get_compliance_summary(project_dir)
+    if s.uncovered_requirements:
+        click.echo(f"Uncovered requirements ({len(s.uncovered_requirements)}):")
+        for r in s.uncovered_requirements:
+            click.echo(f"  \u2717 {r}")
+    else:
+        click.echo("\u2713 All requirements have test coverage.")
+    if s.orphaned_tests:
+        click.echo(f"\nOrphaned tests ({len(s.orphaned_tests)}):")
+        for t in s.orphaned_tests:
+            click.echo(f"  \u26a0 {t}")
+
+
+@compliance_group.command("trace")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--json-output", "as_json", is_flag=True)
+def compliance_trace(project_dir: str, as_json: bool) -> None:
+    """Show REQ \u2192 TEST traceability matrix."""
+    from specsmith.compliance import get_compliance_summary
+
+    s = get_compliance_summary(project_dir)
+    if as_json:
+        click.echo(json.dumps(s.trace_matrix, indent=2))
+    else:
+        for entry in s.trace_matrix:
+            icon = "\u2713" if entry["covered"] else "\u2717"
+            tests = ", ".join(entry["tests"]) if entry["tests"] else "(none)"
+            click.echo(f"  {icon} {entry['requirement_id']:<12} \u2192 {tests}")
+
+
+@compliance_group.command("rules")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def compliance_rules(project_dir: str) -> None:
+    """Show governance hard rules status (H1-H14)."""
+    from specsmith.compliance import get_governance_rules_status
+
+    rules = get_governance_rules_status(project_dir)
+    for r in rules:
+        icon = {"ok": "\u2713", "warning": "\u26a0", "violation": "\u2717"}.get(r["status"], "?")
+        click.echo(f"  {icon} {r['id']}: {r['name']}")
+
+
+# ---------------------------------------------------------------------------
+# specsmith session
+# ---------------------------------------------------------------------------
+
+
+@click.group("session")
+def session_group() -> None:
+    """Session lifecycle management."""
+
+
+@session_group.command("info")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--json-output", "as_json", is_flag=True)
+def session_info(project_dir: str, as_json: bool) -> None:
+    """Show current session context."""
+    from specsmith.session_init import init_session
+
+    ctx = init_session(project_dir)
+    if as_json:
+        click.echo(json.dumps(ctx.to_dict(), indent=2))
+    else:
+        gov = "\u2713" if ctx.is_governed else "\u2717"
+        click.echo(f"  Project:    {ctx.project_name}")
+        click.echo(f"  Governed:   {gov}")
+        phase = ctx.phase_emoji
+        label = ctx.phase_label
+        pct = ctx.phase_readiness_pct
+        click.echo(f"  Phase:      {phase} {label} ({pct}%)")
+        click.echo(f"  Health:     {ctx.health_score}%")
+        click.echo(f"  Compliance: {ctx.compliance_score}%")
+        click.echo(f"  Profile:    {ctx.active_profile}")
+        rp = ctx.reachable_providers
+        pc = ctx.provider_count
+        click.echo(f"  Providers:  {rp}/{pc} reachable")
+        click.echo(f"  Session:    {ctx.session_id}")
+        if ctx.needs_import:
+            click.echo(
+                "\n  \u26a0 Not a specsmith project. Run 'specsmith import' to add governance."
+            )
+        if ctx.needs_migration:
+            sv = ctx.spec_version
+            iv = ctx.installed_version
+            click.echo(
+                f"\n  \u26a0 Spec version mismatch ({sv} vs {iv}). Run 'specsmith migrate-project'."
+            )

specsmith-0.10.1.dev287/src/specsmith/compliance.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Compliance scoring and reporting (REQ-224).
+
+Provides compliance summary, requirement gaps, test coverage, and
+traceability matrix. Used by both CLI commands and REST endpoints.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ComplianceSummary:
+    """Overall compliance status for a project."""
+
+    total_requirements: int = 0
+    covered_requirements: int = 0
+    uncovered_requirements: list[str] = field(default_factory=list)
+    total_tests: int = 0
+    orphaned_tests: list[str] = field(default_factory=list)
+    compliance_score: int = 0  # 0-100
+    requirement_coverage_pct: int = 0
+    trace_matrix: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_requirements": self.total_requirements,
+            "covered_requirements": self.covered_requirements,
+            "uncovered_requirements": self.uncovered_requirements,
+            "total_tests": self.total_tests,
+            "orphaned_tests": self.orphaned_tests,
+            "compliance_score": self.compliance_score,
+            "requirement_coverage_pct": self.requirement_coverage_pct,
+            "trace_count": len(self.trace_matrix),
+        }
+
+
+def _parse_requirements(root: Path) -> dict[str, dict[str, str]]:
+    """Parse REQUIREMENTS.md into {req_id: {title, status, ...}}."""
+    req_path = root / "docs" / "REQUIREMENTS.md"
+    if not req_path.is_file():
+        req_path = root / "REQUIREMENTS.md"
+    if not req_path.is_file():
+        return {}
+
+    text = req_path.read_text(encoding="utf-8", errors="replace")
+    reqs: dict[str, dict[str, str]] = {}
+
+    # Parse markdown sections: ## N. Title\n- **ID:** REQ-NNN
+    blocks = re.split(r"\n## ", text)
+    for block in blocks:
+        id_match = re.search(r"\*\*ID:\*\*\s*(REQ-\d+)", block)
+        if not id_match:
+            # Try alternate format: ## REQ-NNN
+            id_match = re.search(r"^(REQ-\d+)", block.strip())
+        if id_match:
+            req_id = id_match.group(1)
+            title_match = re.search(r"\*\*Title:\*\*\s*(.+)", block)
+            status_match = re.search(r"\*\*Status:\*\*\s*(.+)", block)
+            reqs[req_id] = {
+                "id": req_id,
+                "title": title_match.group(1).strip() if title_match else "",
+                "status": status_match.group(1).strip() if status_match else "draft",
+            }
+
+    return reqs
+
+
+def _parse_tests(root: Path) -> dict[str, dict[str, str]]:
+    """Parse TESTS.md into {test_id: {title, requirement_id, ...}}."""
+    test_path = root / "docs" / "TESTS.md"
+    if not test_path.is_file():
+        test_path = root / "TESTS.md"
+    if not test_path.is_file():
+        return {}
+
+    text = test_path.read_text(encoding="utf-8", errors="replace")
+    tests: dict[str, dict[str, str]] = {}
+
+    blocks = re.split(r"\n## ", text)
+    for block in blocks:
+        id_match = re.search(r"\*\*ID:\*\*\s*(TEST-\d+)", block)
+        if not id_match:
+            id_match = re.search(r"^(TEST-\d+)", block.strip())
+        if id_match:
+            test_id = id_match.group(1)
+            req_match = re.search(r"\*\*Requirement(?:\s+ID)?:\*\*\s*(REQ-\d+)", block)
+            title_match = re.search(r"\*\*Title:\*\*\s*(.+)", block)
+            tests[test_id] = {
+                "id": test_id,
+                "title": title_match.group(1).strip() if title_match else "",
+                "requirement_id": req_match.group(1) if req_match else "",
+            }
+
+    return tests
+
+
+def get_compliance_summary(project_dir: str | Path = ".") -> ComplianceSummary:
+    """Compute full compliance summary for a project."""
+    root = Path(project_dir).resolve()
+    reqs = _parse_requirements(root)
+    tests = _parse_tests(root)
+
+    # Build coverage map
+    covered_req_ids: set[str] = set()
+    for test in tests.values():
+        req_id = test.get("requirement_id", "")
+        if req_id and req_id in reqs:
+            covered_req_ids.add(req_id)
+
+    uncovered = [r for r in reqs if r not in covered_req_ids]
+
+    # Find orphaned tests (reference non-existent requirements)
+    orphaned = []
+    for test in tests.values():
+        req_id = test.get("requirement_id", "")
+        if req_id and req_id not in reqs:
+            orphaned.append(f"{test['id']} -> {req_id}")
+
+    total = len(reqs)
+    covered = len(covered_req_ids)
+    coverage_pct = int(covered / total * 100) if total > 0 else 0
+
+    # Build trace matrix
+    trace: list[dict[str, Any]] = []
+    for req_id, req in sorted(reqs.items()):
+        linked_tests = [t["id"] for t in tests.values() if t.get("requirement_id") == req_id]
+        trace.append(
+            {
+                "requirement_id": req_id,
+                "title": req.get("title", ""),
+                "status": req.get("status", ""),
+                "tests": linked_tests,
+                "covered": len(linked_tests) > 0,
+            }
+        )
+
+    return ComplianceSummary(
+        total_requirements=total,
+        covered_requirements=covered,
+        uncovered_requirements=uncovered,
+        total_tests=len(tests),
+        orphaned_tests=orphaned,
+        compliance_score=coverage_pct,
+        requirement_coverage_pct=coverage_pct,
+        trace_matrix=trace,
+    )
+
+
+def get_governance_rules_status(project_dir: str | Path = ".") -> list[dict[str, Any]]:
+    """Return status of hard governance rules (H1-H14)."""
+    root = Path(project_dir).resolve()
+
+    rules = [
+        {"id": "H1", "name": "Ledger required", "description": "No ledger entry = work not done"},
+        {"id": "H2", "name": "Proposal required", "description": "No proposal = no execution"},
+        {
+            "id": "H3",
+            "name": "Cross-platform awareness",
+            "description": "All work must consider every target platform",
+        },
+        {
+            "id": "H4",
+            "name": "Environment isolation",
+            "description": "No system-dependent assumptions",
+        },
+        {"id": "H5", "name": "Explicit startup", "description": "No hidden service logic"},
+        {
+            "id": "H6",
+            "name": "No silent scope expansion",
+            "description": "If task grows, stop and re-propose",
+        },
+        {
+            "id": "H7",
+            "name": "No undocumented state changes",
+            "description": "Every change must be traceable",
+        },
+        {
+            "id": "H8",
+            "name": "Documentation is implementation",
+            "description": "Architecture changes MUST update docs",
+        },
+        {
+            "id": "H9",
+            "name": "Execution timeout required",
+            "description": "All agent commands must have timeouts",
+        },
+        {
+            "id": "H10",
+            "name": "No hardcoded versions",
+            "description": "Use importlib.metadata at runtime",
+        },
+        {
+            "id": "H11",
+            "name": "No unbounded loops",
+            "description": "Every loop must have a deadline",
+        },
+        {
+            "id": "H12",
+            "name": "Windows automation via .cmd",
+            "description": "Multi-step automation uses .cmd files",
+        },
+        {
+            "id": "H13",
+            "name": "Epistemic boundaries required",
+            "description": "Proposals must state assumptions",
+        },
+        {
+            "id": "H14",
+            "name": "Documentation freshness",
+            "description": "Docs updated in same commit as code",
+        },
+    ]
+
+    # Quick checks for common violations
+    ledger_exists = (root / "docs" / "LEDGER.md").is_file() or (root / "LEDGER.md").is_file()
+    agents_exists = (root / "AGENTS.md").is_file()
+
+    for rule in rules:
+        rule["status"] = "ok"  # default
+
+    if not ledger_exists:
+        rules[0]["status"] = "violation"
+    if not agents_exists:
+        rules[1]["status"] = "warning"
+
+    return rules

{specsmith-0.10.1.dev283 → specsmith-0.10.1.dev287}/src/specsmith/governance_logic.py

@@ -485,6 +485,151 @@ class GovernanceHTTPServer:
 
                 if self.path in ("/health", "/api/health"):
                     self._json_ok({"status": "ok", "version": __version__})
+
+                # ── Session ────────────────────────────────────────────
+                elif self.path == "/api/session":
+                    try:
+                        from specsmith.session_init import init_session
+
+                        ctx = init_session(project_dir)
+                        self._json_ok(ctx.to_dict())
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
+                # ── Compliance ─────────────────────────────────────────
+                elif self.path == "/api/compliance/summary":
+                    try:
+                        from specsmith.compliance import get_compliance_summary
+
+                        s = get_compliance_summary(project_dir)
+                        self._json_ok(s.to_dict())
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+                elif self.path == "/api/compliance/gaps":
+                    try:
+                        from specsmith.compliance import get_compliance_summary
+
+                        s = get_compliance_summary(project_dir)
+                        self._json_ok(
+                            {"uncovered": s.uncovered_requirements, "orphaned": s.orphaned_tests}
+                        )
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+                elif self.path == "/api/compliance/trace":
+                    try:
+                        from specsmith.compliance import get_compliance_summary
+
+                        s = get_compliance_summary(project_dir)
+                        self._json_ok({"trace_matrix": s.trace_matrix})
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
+                # ── Governance ─────────────────────────────────────────
+                elif self.path == "/api/governance/rules":
+                    try:
+                        from specsmith.compliance import get_governance_rules_status
+
+                        self._json_ok({"rules": get_governance_rules_status(project_dir)})
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+                elif self.path == "/api/governance/phase":
+                    try:
+                        from specsmith.phase import PHASE_MAP, phase_progress_pct, read_phase
+
+                        root = Path(project_dir).resolve()
+                        key = read_phase(root)
+                        phase = PHASE_MAP[key]
+                        self._json_ok(
+                            {
+                                "phase": key,
+                                "label": phase.label,
+                                "emoji": phase.emoji,
+                                "readiness_pct": phase_progress_pct(phase, root),
+                            }
+                        )
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+                elif self.path == "/api/governance/audit":
+                    try:
+                        from specsmith.auditor import run_audit
+
+                        report = run_audit(Path(project_dir).resolve())
+                        self._json_ok(
+                            {
+                                "healthy": report.healthy,
+                                "passed": report.passed,
+                                "failed": report.failed,
+                                "results": [
+                                    {"passed": r.passed, "message": r.message}
+                                    for r in report.results
+                                ],
+                            }
+                        )
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
+                # ── Providers ──────────────────────────────────────────
+                elif self.path == "/api/providers":
+                    try:
+                        from specsmith.agent.provider_registry import ProviderRegistry
+
+                        reg = ProviderRegistry.load()
+                        self._json_ok({"providers": [p.to_public_dict() for p in reg.providers]})
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
+                # ── Profiles ───────────────────────────────────────────
+                elif self.path == "/api/profiles":
+                    try:
+                        from specsmith.agent.execution_profiles import ExecutionProfileStore
+
+                        store = ExecutionProfileStore.load()
+                        self._json_ok(
+                            {
+                                "profiles": [p.to_dict() for p in store.profiles],
+                                "default": store.default().id,
+                            }
+                        )
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
+                # ── Model Scores ───────────────────────────────────────
+                elif self.path.startswith("/api/models/scores"):
+                    try:
+                        import urllib.parse as _up
+
+                        from specsmith.agent.model_intelligence import (
+                            BASELINE_SCORES,
+                            rank_models_for_role,
+                        )
+
+                        qs = _up.urlparse(self.path).query
+                        params = _up.parse_qs(qs)
+                        role = params.get("role", ["coder"])[0]
+                        models = list(BASELINE_SCORES.keys())
+                        ranked = rank_models_for_role(role, models)
+                        self._json_ok(
+                            {"role": role, "scores": [{"model": m, "score": s} for m, s in ranked]}
+                        )
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
+                # ── Datasources ────────────────────────────────────────
+                elif self.path == "/api/datasources":
+                    try:
+                        sources = [
+                            {"id": "patentsview", "name": "PatentsView"},
+                            {"id": "ppubs", "name": "Patent Public Search (PPUBS)"},
+                            {"id": "odp", "name": "USPTO Open Data Portal"},
+                            {"id": "pfw", "name": "Patent File Wrapper"},
+                            {"id": "citations", "name": "USPTO Enriched Citations"},
+                            {"id": "fpd", "name": "Final Petition Decisions"},
+                            {"id": "ptab", "name": "USPTO PTAB"},
+                        ]
+                        self._json_ok({"datasources": sources})
+                    except Exception as exc:  # noqa: BLE001
+                        self._json_err(str(exc), code=500)
+
                 else:
                     self.send_error(404)