specsmith 0.15.3.dev573__tar.gz → 0.15.3.dev585__tar.gz

{specsmith-0.15.3.dev573/src/specsmith.egg-info → specsmith-0.15.3.dev585}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.15.3.dev573
+Version: 0.15.3.dev585
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT
@@ -85,13 +85,30 @@ Dynamic: license-file
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/layer1labs/specsmith/blob/main/LICENSE)
 
-**Applied Epistemic Engineering toolkit for AI-assisted development.**
+SpecSmith is the governance layer for AI-assisted development: it sits between agents and your repo, enforces preflight decisions, and records requirement/test traceability with auditable evidence. It is **not** an IDE, autonomous coding agent, CI runner, or legal-compliance certifier. Use SpecSmith when changes need repeatable controls, work-item lineage, and review-ready artifacts; do not use it for throwaway prototyping where governance overhead is unnecessary. Compared with GitHub Spec Kit, OpenSpec, and BMAD, SpecSmith adds execution-time policy gates and trace chains. Compared with Aider, Claude Code, and Cursor, SpecSmith governs those clients instead of replacing them. Compared with LangGraph and AutoGen, SpecSmith prioritizes software-governance outcomes and evidence quality over general-purpose multi-agent orchestration.
 
-> Intelligence proposes. Constraints decide. The ledger remembers.
+## Architecture at a glance
 
-specsmith treats belief systems like code: codable, testable, and deployable. It scaffolds
-epistemically-governed projects, stress-tests requirements as BeliefArtifacts, runs
-cryptographically-sealed trace vaults, and orchestrates AI agents under formal AEE governance.
+```mermaid
+flowchart LR
+    A[AI Agents / IDE Clients] --> B[SpecSmith Governance Layer]
+    B --> C[Repository Files]
+    B --> D[Requirements and Tests]
+    B --> E[ESDB / Audit Ledger]
+    E --> F[CI and MCP Integrations]
+    D --> F
+```
+
+## When to use / when not to use
+
+- Use when you need governed AI development, auditable decision trails, and requirement-to-test linkage.
+- Avoid when rapid local prototyping is the only goal and formal governance is unnecessary.
+
+## Comparison summary
+
+- **GitHub Spec Kit / OpenSpec / BMAD:** strong specification practices; SpecSmith adds execution-time governance, work-item lifecycle control, and trace-chain evidence.
+- **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients.
+- **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability.
 
 **v0.15.2 — PyPI-safe README links, RTD nav coverage, updated security policy, and expanded embedded skill catalog (Zephyr 4.4→3.x, FreeRTOS, bare-metal C).**
 specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689)
@@ -180,6 +197,18 @@ specsmith phase list     # list all phases
 The current phase is persisted in `scaffold.yml` as `aee_phase`. Each phase has a checklist
 of file/command criteria, recommended commands, and a readiness percentage.
 
+## 1.0 release criteria status
+
+| Criterion | Status | Source |
+|---|---|---|
+| Stable CLI core contract documented | In progress | `docs/stability.md` |
+| Stable generated file schemas documented | In progress | `docs/stability.md` |
+| Stable MCP tool schemas documented | In progress | `docs/stability.md` |
+| Migration tests linked (#218) | In progress | `docs/roadmap/1.0-criteria.md` |
+| Security threat model documented | In progress | `docs/security-threat-model.md` |
+| Docs/tutorial/glossary baseline complete | In progress | `docs/roadmap/1.0-criteria.md` |
+| Upgrade path and changelog criteria defined | In progress | `docs/roadmap/1.0-criteria.md` |
+
 ---
 
 ## Install
@@ -224,6 +253,8 @@ in your own application without managing a pipx environment.
 | **Default** | `specsmith` (built-in) | MIT, free | SQLite backend — requirements, test cases, confidence filtering |
 | **Commercial** | `chronomemory` via `specsmith[esdb]` | Proprietary — license required | ChronoStore: tamper-evident SHA-256 WAL, OEA anti-hallucination fields, Rust acceleration, epistemic rollback |
 
+See `docs/editions.md` for the full OSS vs commercial feature matrix.
+
 `pip install specsmith` always installs the **free SQLite backend** automatically.
 No additional packages, no license key, no configuration — it works out of the box.
 
@@ -1187,8 +1218,14 @@ command reference, project types, tool registry, governance model, ESDB, skills
 
 - [PyPI](https://pypi.org/project/specsmith/)
 - [Documentation](https://specsmith.readthedocs.io)
+- [Stability Contract](https://github.com/layer1labs/specsmith/blob/main/docs/stability.md)
+- [1.0 Release Criteria](https://github.com/layer1labs/specsmith/blob/main/docs/roadmap/1.0-criteria.md)
+- [Editions Matrix](https://github.com/layer1labs/specsmith/blob/main/docs/editions.md)
 - [Changelog](https://github.com/layer1labs/specsmith/blob/main/CHANGELOG.md)
 - [Contributing](https://github.com/layer1labs/specsmith/blob/main/CONTRIBUTING.md)
+- [Roadmap](https://github.com/layer1labs/specsmith/blob/main/ROADMAP.md)
+- [Compatibility Matrix](https://github.com/layer1labs/specsmith/blob/main/docs/site/compatibility.md)
+- [Product Principles](https://github.com/layer1labs/specsmith/blob/main/docs/product-principles.md)
 - [Security](https://github.com/layer1labs/specsmith/blob/main/SECURITY.md)
 
 ## License

{specsmith-0.15.3.dev573 → specsmith-0.15.3.dev585}/README.md

@@ -7,13 +7,30 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/layer1labs/specsmith/blob/main/LICENSE)
 
-**Applied Epistemic Engineering toolkit for AI-assisted development.**
+SpecSmith is the governance layer for AI-assisted development: it sits between agents and your repo, enforces preflight decisions, and records requirement/test traceability with auditable evidence. It is **not** an IDE, autonomous coding agent, CI runner, or legal-compliance certifier. Use SpecSmith when changes need repeatable controls, work-item lineage, and review-ready artifacts; do not use it for throwaway prototyping where governance overhead is unnecessary. Compared with GitHub Spec Kit, OpenSpec, and BMAD, SpecSmith adds execution-time policy gates and trace chains. Compared with Aider, Claude Code, and Cursor, SpecSmith governs those clients instead of replacing them. Compared with LangGraph and AutoGen, SpecSmith prioritizes software-governance outcomes and evidence quality over general-purpose multi-agent orchestration.
+
+## Architecture at a glance
+
+```mermaid
+flowchart LR
+    A[AI Agents / IDE Clients] --> B[SpecSmith Governance Layer]
+    B --> C[Repository Files]
+    B --> D[Requirements and Tests]
+    B --> E[ESDB / Audit Ledger]
+    E --> F[CI and MCP Integrations]
+    D --> F
+```
+
+## When to use / when not to use
 
-> Intelligence proposes. Constraints decide. The ledger remembers.
+- Use when you need governed AI development, auditable decision trails, and requirement-to-test linkage.
+- Avoid when rapid local prototyping is the only goal and formal governance is unnecessary.
 
-specsmith treats belief systems like code: codable, testable, and deployable. It scaffolds
-epistemically-governed projects, stress-tests requirements as BeliefArtifacts, runs
-cryptographically-sealed trace vaults, and orchestrates AI agents under formal AEE governance.
+## Comparison summary
+
+- **GitHub Spec Kit / OpenSpec / BMAD:** strong specification practices; SpecSmith adds execution-time governance, work-item lifecycle control, and trace-chain evidence.
+- **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients.
+- **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability.
 
 **v0.15.2 — PyPI-safe README links, RTD nav coverage, updated security policy, and expanded embedded skill catalog (Zephyr 4.4→3.x, FreeRTOS, bare-metal C).**
 specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689)
@@ -102,6 +119,18 @@ specsmith phase list     # list all phases
 The current phase is persisted in `scaffold.yml` as `aee_phase`. Each phase has a checklist
 of file/command criteria, recommended commands, and a readiness percentage.
 
+## 1.0 release criteria status
+
+| Criterion | Status | Source |
+|---|---|---|
+| Stable CLI core contract documented | In progress | `docs/stability.md` |
+| Stable generated file schemas documented | In progress | `docs/stability.md` |
+| Stable MCP tool schemas documented | In progress | `docs/stability.md` |
+| Migration tests linked (#218) | In progress | `docs/roadmap/1.0-criteria.md` |
+| Security threat model documented | In progress | `docs/security-threat-model.md` |
+| Docs/tutorial/glossary baseline complete | In progress | `docs/roadmap/1.0-criteria.md` |
+| Upgrade path and changelog criteria defined | In progress | `docs/roadmap/1.0-criteria.md` |
+
 ---
 
 ## Install
@@ -146,6 +175,8 @@ in your own application without managing a pipx environment.
 | **Default** | `specsmith` (built-in) | MIT, free | SQLite backend — requirements, test cases, confidence filtering |
 | **Commercial** | `chronomemory` via `specsmith[esdb]` | Proprietary — license required | ChronoStore: tamper-evident SHA-256 WAL, OEA anti-hallucination fields, Rust acceleration, epistemic rollback |
 
+See `docs/editions.md` for the full OSS vs commercial feature matrix.
+
 `pip install specsmith` always installs the **free SQLite backend** automatically.
 No additional packages, no license key, no configuration — it works out of the box.
 
@@ -1109,8 +1140,14 @@ command reference, project types, tool registry, governance model, ESDB, skills
 
 - [PyPI](https://pypi.org/project/specsmith/)
 - [Documentation](https://specsmith.readthedocs.io)
+- [Stability Contract](https://github.com/layer1labs/specsmith/blob/main/docs/stability.md)
+- [1.0 Release Criteria](https://github.com/layer1labs/specsmith/blob/main/docs/roadmap/1.0-criteria.md)
+- [Editions Matrix](https://github.com/layer1labs/specsmith/blob/main/docs/editions.md)
 - [Changelog](https://github.com/layer1labs/specsmith/blob/main/CHANGELOG.md)
 - [Contributing](https://github.com/layer1labs/specsmith/blob/main/CONTRIBUTING.md)
+- [Roadmap](https://github.com/layer1labs/specsmith/blob/main/ROADMAP.md)
+- [Compatibility Matrix](https://github.com/layer1labs/specsmith/blob/main/docs/site/compatibility.md)
+- [Product Principles](https://github.com/layer1labs/specsmith/blob/main/docs/product-principles.md)
 - [Security](https://github.com/layer1labs/specsmith/blob/main/SECURITY.md)
 
 ## License

{specsmith-0.15.3.dev573 → specsmith-0.15.3.dev585}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.15.3.dev573"
+version = "0.15.3.dev585"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"

specsmith-0.15.3.dev585/src/specsmith/approvals.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+APPROVAL_TYPES = ("requirement", "plan", "implementation", "verification", "release")
+
+
+@dataclass
+class ApprovalRecord:
+    approval_type: str
+    work_item_id: str
+    approver: str
+    timestamp: str
+    scope: str
+    rationale: str
+    requirement_ids: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _approvals_path(root: Path) -> Path:
+    return root / ".specsmith" / "approvals.json"
+
+
+def load_approvals(root: Path) -> list[ApprovalRecord]:
+    path = _approvals_path(root)
+    if not path.is_file():
+        return []
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+    if not isinstance(raw, list):
+        return []
+    out: list[ApprovalRecord] = []
+    for row in raw:
+        if isinstance(row, dict):
+            out.append(
+                ApprovalRecord(
+                    approval_type=str(row.get("approval_type", "")),
+                    work_item_id=str(row.get("work_item_id", "")),
+                    approver=str(row.get("approver", "")),
+                    timestamp=str(row.get("timestamp", "")),
+                    scope=str(row.get("scope", "")),
+                    rationale=str(row.get("rationale", "")),
+                    requirement_ids=list(row.get("requirement_ids", []) or []),
+                )
+            )
+    return out
+
+
+def save_approvals(root: Path, approvals: list[ApprovalRecord]) -> None:
+    path = _approvals_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps([a.to_dict() for a in approvals], indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+
+def detect_approver(root: Path) -> str:
+    def _git_config(key: str) -> str:
+        try:
+            proc = subprocess.run(
+                ["git", "-C", str(root), "config", "--get", key],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+        except Exception:  # noqa: BLE001
+            return ""
+        return (proc.stdout or "").strip()
+
+    name = _git_config("user.name")
+    email = _git_config("user.email")
+    if name and email:
+        return f"{name} <{email}>"
+    if name:
+        return name
+    if email:
+        return email
+    return "unknown-approver"
+
+
+def record_approval(
+    root: Path,
+    approval_type: str,
+    work_item_id: str,
+    rationale: str,
+    *,
+    scope: str = "",
+    requirement_ids: list[str] | None = None,
+) -> ApprovalRecord:
+    if approval_type not in APPROVAL_TYPES:
+        msg = f"approval_type must be one of {APPROVAL_TYPES}"
+        raise ValueError(msg)
+    approvals = load_approvals(root)
+    record = ApprovalRecord(
+        approval_type=approval_type,
+        work_item_id=work_item_id,
+        approver=detect_approver(root),
+        timestamp=_now_iso(),
+        scope=scope or work_item_id,
+        rationale=rationale.strip(),
+        requirement_ids=list(requirement_ids or []),
+    )
+    approvals.append(record)
+    save_approvals(root, approvals)
+    return record
+
+
+def approvals_by_work_item(root: Path, work_item_id: str) -> list[ApprovalRecord]:
+    return [a for a in load_approvals(root) if a.work_item_id == work_item_id]

{specsmith-0.15.3.dev573 → specsmith-0.15.3.dev585}/src/specsmith/auditor.py

@@ -1281,6 +1281,79 @@ def check_cross_repo_dependencies(root: Path) -> list[AuditResult]:
     return results
 
 
+def check_policy_validation(root: Path) -> list[AuditResult]:
+    results: list[AuditResult] = []
+    from specsmith.policy import load_policy
+
+    policy, errors = load_policy(root)
+    if errors:
+        for err in errors:
+            results.append(
+                AuditResult(
+                    name="policy-validation",
+                    passed=False,
+                    message=f"policy.yml invalid: {err}",
+                )
+            )
+        return results
+    if (root / ".specsmith" / "policy.yml").is_file():
+        results.append(
+            AuditResult(
+                name="policy-validation",
+                passed=True,
+                message=f"policy.yml valid (risk_threshold={policy.risk_threshold})",
+            )
+        )
+    return results
+
+
+def check_work_item_risk_gates(root: Path) -> list[AuditResult]:
+    results: list[AuditResult] = []
+    from specsmith.approvals import approvals_by_work_item
+    from specsmith.risk import assess_all_work_items
+    from specsmith.wi_store import WorkItemStore
+
+    store = WorkItemStore(root)
+    items = {item.id: item for item in store.load()}
+    if not items:
+        return results
+    for wi_id, risk in assess_all_work_items(root):
+        item = items.get(wi_id)
+        if item is None:
+            continue
+        approvals = {a.approval_type for a in approvals_by_work_item(root, wi_id)}
+        missing_gates: list[str] = []
+        if (
+            "human_approval:implementation" in risk.required_gates
+            and "implementation" not in approvals
+        ):
+            missing_gates.append("implementation approval")
+        if "human_approval:verification" in risk.required_gates and "verification" not in approvals:
+            missing_gates.append("verification approval")
+        if "tests_required" in risk.required_gates and not item.test_case_ids:
+            missing_gates.append("linked tests")
+        if missing_gates:
+            results.append(
+                AuditResult(
+                    name=f"risk-gates:{wi_id}",
+                    passed=False,
+                    message=(
+                        f"{wi_id} risk={risk.level} missing gates: {', '.join(missing_gates)}"
+                        + (f" (override: {risk.override_reason})" if risk.overridden else "")
+                    ),
+                )
+            )
+        else:
+            results.append(
+                AuditResult(
+                    name=f"risk-gates:{wi_id}",
+                    passed=True,
+                    message=f"{wi_id} risk={risk.level} gates satisfied",
+                )
+            )
+    return results
+
+
 def run_audit(root: Path) -> AuditReport:
     """Run all audit checks and return a report."""
     report = AuditReport()
@@ -1298,6 +1371,8 @@ def run_audit(root: Path) -> AuditReport:
     report.results.extend(check_industrial_artifacts(root))
     report.results.extend(check_derived_artifacts(root))
     report.results.extend(check_cross_repo_dependencies(root))
+    report.results.extend(check_policy_validation(root))
+    report.results.extend(check_work_item_risk_gates(root))
 
     # Apply accepted_warnings / audit_suppressions from scaffold.yml (REQ-357)
     raw = _read_scaffold_raw(root)