specsmith 0.17.1.dev684__tar.gz → 0.18.0.dev686__tar.gz

{specsmith-0.17.1.dev684/src/specsmith.egg-info → specsmith-0.18.0.dev686}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.17.1.dev684
+Version: 0.18.0.dev686
 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

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.17.1.dev684"
+version = "0.18.0.dev686"
 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.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import version as _pkg_version
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.17.1"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.18.0"  # fallback: keep in sync with pyproject.toml

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/agent/runner.py

@@ -798,10 +798,11 @@ class AgentRunner:
     def _seal_profile_pin(self, profile_id: str) -> None:
         """Append a TraceVault decision seal recording the ``/agent`` pin (G4).
 
-        Wrapped in best-effort try/except so an unwriteable
-        ``.specsmith/trace.jsonl`` (read-only fs, missing project root, etc.)
-        never breaks the chat loop. The seal type is ``decision`` because
-        a profile pin is an explicit governance choice the user made.
+        Wrapped in best-effort try/except so an unwriteable ESDB store
+        (read-only fs, missing project root, etc.) never breaks the chat loop.
+        The seal is persisted as an ESDB ``seal_record`` (REQ-420). The seal
+        type is ``decision`` because a profile pin is an explicit governance
+        choice the user made.
         """
         try:
             from specsmith.trace import SealType, TraceVault

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/auditor.py

@@ -930,7 +930,14 @@ def check_type_mismatch(root: Path) -> list[AuditResult]:
 
 
 def check_trace_chain_integrity(root: Path) -> list[AuditResult]:
-    """Check trace vault chain integrity if it exists."""
+    """Check trace vault chain integrity if it exists.
+
+    DEPRECATED(REQ-421): this verifies the legacy ``epistemic.trace`` flat-file
+    vault (``.specsmith/trace.jsonl``). The current trace vault is ESDB-only
+    (``specsmith.trace``; REQ-420). Retained so legacy projects that still carry
+    a trace.jsonl keep getting an integrity signal; remove at teardown.
+    See docs/DEPRECATIONS.md.
+    """
     trace_path = root / ".specsmith" / "trace.jsonl"
     if not trace_path.exists():
         return []  # No trace vault configured — skip silently

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/cli.py

@@ -771,174 +771,81 @@ def preflight_cmd(
 ) -> None:
     """Classify a natural-language utterance under Specsmith governance (REQ-085).
 
-    Reads REQUIREMENTS.md and ``.repo-index/files.json`` from PROJECT-DIR,
-    classifies intent (read-only ask / change / release / destructive),
-    infers scope, and emits a JSON object describing the preflight decision.
-    Read-only asks accept by default; destructive intents require
-    clarification; changes with no matching scope return needs_clarification.
+    REQ-418: this command delegates to ``governance_logic.run_preflight`` so the
+    CLI decision matches the in-process broker — explicit ``REQ-NNN`` references
+    and ``.specsmith/requirements.json`` are honored, the REQ-098 floor is applied
+    once, and the work item / ESDB ``preflight_decision`` record are persisted
+    (unless ``--predict-only``). The command then layers on presentation-only
+    extras (``predicted_refinement``, ``stress_warnings``, ``narration``) and the
+    REQ-093/099 LEDGER.md events, and exits 0/2/3 per the decision (REQ-092).
     """
     import json as _json
-    import uuid
 
-    from specsmith.agent.broker import (
-        Intent,
-        PreflightDecision,
-        classify_intent,
-        infer_scope,
-        narrate_plan,
-    )
+    from specsmith.governance_logic import run_preflight
 
     root = Path(project_dir).resolve()
-    intent = classify_intent(utterance)
-    scope = infer_scope(
+    # REQ-418: delegate the decision to the authoritative broker so explicit
+    # REQ-NNN ids and .specsmith/requirements.json drive the result.  run_preflight
+    # also applies the REQ-098 floor, allocates/persists the work item (unless
+    # predict_only), writes the ESDB preflight_decision record, and attaches the
+    # ai_disclosure + REG-004 escalation fields.  Do NOT re-apply the floor here.
+    payload = run_preflight(
         utterance,
-        root / "REQUIREMENTS.md",
-        repo_index_path=root / ".repo-index" / "files.json",
+        str(root),
+        predict_only=predict_only,
+        escalate_threshold=escalate_threshold,
     )
+    decision_str = str(payload.get("decision", ""))
+    work_item_id = str(payload.get("work_item_id", ""))
+    requirement_ids = list(payload.get("requirement_ids", []))
+    confidence_target = float(payload.get("confidence_target", 0.0))
 
-    requirement_ids = [r.req_id for r in scope.matched_requirements]
-
-    # REQ-088: resolve test_case_ids from machine state by joining
-    # `requirement_ids` against `.specsmith/testcases.json` (or `TESTS.md`
-    # when the JSON is unavailable). Never invent ids.
-    test_case_ids: list[str] = []
-    if requirement_ids:
-        testcases_json = root / ".specsmith" / "testcases.json"
-        if testcases_json.is_file():
-            try:
-                records = _json.loads(testcases_json.read_text(encoding="utf-8"))
-            except (OSError, ValueError):
-                records = []
-            req_set = set(requirement_ids)
-            for record in records:
-                if (
-                    isinstance(record, dict)
-                    and record.get("requirement_id") in req_set
-                    and isinstance(record.get("id"), str)
-                ):
-                    test_case_ids.append(record["id"])
-        else:
-            tests_md = root / "TESTS.md"
-            if tests_md.is_file():
-                import re as _re
-
-                text = tests_md.read_text(encoding="utf-8")
-                # Match each test block: a `TEST-NNN` id paired with a
-                # `REQ-NNN` requirement-id reference within the same block.
-                req_set = set(requirement_ids)
-                for block in _re.split(r"\n## ", text):
-                    test_match = _re.search(r"\*\*ID:\*\*\s+(TEST-\d+)", block)
-                    req_match = _re.search(r"\*\*Requirement ID:\*\*\s+(REQ-\d+)", block)
-                    if test_match and req_match and req_match.group(1) in req_set:
-                        test_case_ids.append(test_match.group(1))
-
-    # Heuristic decision policy. Specsmith governance owns the contract; the
-    # CLI implementation is intentionally simple and deterministic so the
-    # broker (and tests) can rely on it without an LLM.
-    decision_str = "accepted"
-    instruction = ""
-    confidence_target = 0.7
-
-    if intent == Intent.READ_ONLY_ASK:
-        decision_str = "accepted"
-        instruction = "Read-only ask; no governance changes required."
-    elif intent == Intent.DESTRUCTIVE:
-        decision_str = "needs_clarification"
-        instruction = (
-            "Destructive operation detected. "
-            "Confirm explicitly which paths or resources should be removed."
-        )
-        confidence_target = 0.9
-    elif intent == Intent.RELEASE:
-        decision_str = "needs_clarification"
-        instruction = (
-            "Release operations require explicit confirmation. "
-            "Specify the target version and channel."
-        )
-        confidence_target = 0.9
-    else:  # CHANGE
-        if scope.is_known:
-            decision_str = "accepted"
-            instruction = (
-                "Change request matched existing governance scope. Proceed under "
-                "Specsmith verification."
-            )
-            confidence_target = max(0.7, scope.confidence)
-        else:
-            decision_str = "needs_clarification"
-            instruction = (
-                "This change does not match an existing requirement. "
-                "Could you say in one sentence which behavior you expect?"
-            )
-            confidence_target = 0.7
-
-    # REQ-098: respect epistemic.confidence_threshold from .specsmith/config.yml
-    # as a floor for confidence_target (heuristic default still applies when
-    # the configured value is lower or the file is missing).
-    config_threshold = _read_confidence_threshold_floor(root)
-    if config_threshold is not None and config_threshold > confidence_target:
-        confidence_target = config_threshold
-
-    work_item_id = f"WI-{uuid.uuid4().hex[:8].upper()}" if decision_str == "accepted" else ""
-
-    # REQ-117: predict-only mode does not allocate a work_item_id and does
-    # not write a ledger event; instead it adds a `predicted_refinement`
-    # field for IDE autocomplete.
+    # REQ-117: predict-only adds a `predicted_refinement` hint for IDE autocomplete.
+    # run_preflight already withholds the work item and the ESDB/ledger writes here.
     if predict_only:
-        work_item_id = ""
-
-    payload = {
-        "decision": decision_str,
-        "work_item_id": work_item_id,
-        "requirement_ids": requirement_ids,
-        "test_case_ids": test_case_ids,
-        "confidence_target": round(confidence_target, 3),
-        "instruction": instruction,
-        "intent": intent.value,
-    }
-    if predict_only:
-        if not scope.is_known and intent == Intent.CHANGE:
+        if decision_str == "needs_clarification":
             payload["predicted_refinement"] = (
-                f"{utterance} (please name the component or file you want to change)"
+                f"{utterance} (please name the component, file, or REQ id to change)"
             )
-        elif intent == Intent.DESTRUCTIVE:
-            payload["predicted_refinement"] = f"{utterance} (specify the exact paths or resources)"
         else:
             payload["predicted_refinement"] = utterance
 
-    # REQ-100: optional stress-test bridge over matched requirements. The flag
-    # defaults off so unrelated tests stay green.
-    if stress and scope.matched_requirements:
-        warnings = _stress_test_warnings(root, scope.matched_requirements)
-        if warnings:
-            payload["stress_warnings"] = warnings
-
-    if verbose:
-        decision_obj = PreflightDecision.from_json(payload)
-        payload["narration"] = narrate_plan(intent, scope, decision_obj, verbose=True)
-        if payload.get("stress_warnings"):
-            payload["narration"] += "\nNote: stress-test surfaced one or more critical failures."
-
-    # REG-009: AI disclosure metadata (FTC Operation AI Comply, Utah SB149 2024).
-    # Every governed output must disclose the AI system producing it.
-    import os as _os
-
-    payload["ai_disclosure"] = {
-        "governed_by": "specsmith",
-        "governance_gated": True,
-        "provider": _os.environ.get("SPECSMITH_PROVIDER", "local/heuristic"),
-        "model": _os.environ.get("SPECSMITH_MODEL", "deterministic-broker"),
-        "spec_version": __version__,
-    }
+    # REQ-100 (--stress) and --verbose (narration) need the broker's scope/intent
+    # view.  Re-derive it best-effort; failures never affect the decision payload.
+    if stress or verbose:
+        try:
+            from specsmith.agent.broker import (
+                PreflightDecision,
+                classify_intent,
+                infer_scope,
+                narrate_plan,
+            )
 
-    # REG-004: human escalation — if a threshold is set and confidence < threshold,
-    # surface an explicit escalation notice in the payload.
-    if escalate_threshold is not None and confidence_target < escalate_threshold:
-        payload["escalation_required"] = True
-        payload["escalation_reason"] = (
-            f"Confidence {confidence_target:.3f} is below escalation threshold "
-            f"{escalate_threshold:.3f}. Human review required before execution."
-        )
+            intent = classify_intent(utterance)
+            # Mirror run_preflight's requirements-path resolution (REQ-418 parity):
+            # prefer docs/REQUIREMENTS.md, fall back to the project-root file so the
+            # stress/verbose scope view matches the authoritative decision's scope.
+            req_md = root / "docs" / "REQUIREMENTS.md"
+            if not req_md.is_file():
+                req_md = root / "REQUIREMENTS.md"
+            scope = infer_scope(
+                utterance,
+                req_md,
+                repo_index_path=root / ".repo-index" / "files.json",
+            )
+            if stress and scope.matched_requirements:
+                warnings = _stress_test_warnings(root, scope.matched_requirements)
+                if warnings:
+                    payload["stress_warnings"] = warnings
+            if verbose:
+                decision_obj = PreflightDecision.from_json(payload)
+                payload["narration"] = narrate_plan(intent, scope, decision_obj, verbose=True)
+                if payload.get("stress_warnings"):
+                    payload["narration"] += (
+                        "\nNote: stress-test surfaced one or more critical failures."
+                    )
+        except Exception:  # noqa: BLE001 - presentation extras are best-effort
+            pass
 
     # Bypass rich's renderer to keep the JSON intact (same pattern as clean).
     click.echo(_json.dumps(payload, indent=2))
@@ -11592,39 +11499,99 @@ def esdb_status_cmd(project_dir: str, as_json: bool) -> None:
             raise SystemExit(1)
         return
 
-    icon = "[green]\u25cf[/green]"
-    console.print(f"{icon} ESDB \u2014 {backend_label}")
-    console.print(f"  Records: {record_count}")
-    for kind, count in counts.items():
-        console.print(f"    {kind}: {count}")
+    # REQ-417: report the actual chain-verification result, not a hardcoded label.
+    integrity_label = "Integrity OK" if chain_ok else "Integrity FAILED"
     chain_icon = "[green]\u2714[/green]" if chain_ok else "[red]\u2717[/red]"
-    console.print(f"  {chain_icon} Integrity OK")
+
+    # Issue #263 / REQ-419: build both a colored (Rich markup) and a plain ASCII
+    # rendering.  The Rich render is attempted first for healthy consoles; on the
+    # Windows legacy console it can raise a spurious KeyboardInterrupt (which Click
+    # turns into Abort/exit 1), so ANY failure falls back to a resilient plain-text
+    # stdout writer that mirrors the --json branch and never aborts.
+    markup_lines: list[str] = [
+        f"[green]\u25cf[/green] ESDB \u2014 {backend_label}",
+        f"  Records: {record_count}",
+    ]
+    plain_lines: list[str] = [
+        f"ESDB - {backend_label}",
+        f"  Records: {record_count}",
+    ]
+    for kind, count in counts.items():
+        markup_lines.append(f"    {kind}: {count}")
+        plain_lines.append(f"    {kind}: {count}")
+    markup_lines.append(f"  {chain_icon} {integrity_label}")
+    plain_lines.append(f"  {integrity_label}")
     if store_error:
-        console.print(f"  [red]\u2717[/red] Store error: {store_error}")
+        markup_lines.append(f"  [red]\u2717[/red] Store error: {store_error}")
+        plain_lines.append(f"  Store error: {store_error}")
     # License line
     if not sys.modules["specsmith.esdb"].CHRONO_AVAILABLE:
-        console.print(
+        markup_lines.append(
             "  [dim]chronomemory not installed \u2014 run "
             "'pip install specsmith[esdb]' for ChronoStore[/dim]"
         )
+        plain_lines.append(
+            "  chronomemory not installed - run 'pip install specsmith[esdb]' for ChronoStore"
+        )
     elif lic_status and lic_status.valid:
-        console.print(
+        markup_lines.append(
             f"  [green]\u2714[/green] License: {lic_status.customer} "
             f"(expires {lic_status.expires_at})"
         )
+        plain_lines.append(f"  License: {lic_status.customer} (expires {lic_status.expires_at})")
     else:
         reason = lic_status.reason if lic_status else "no license file"
-        console.print(f"  [yellow]\u26a0[/yellow]  ESDB license: {reason}")
-        console.print(
+        markup_lines.append(f"  [yellow]\u26a0[/yellow]  ESDB license: {reason}")
+        markup_lines.append(
             "  [dim]Use 'specsmith esdb enable --key-file <path>' to activate ChronoStore.[/dim]"
         )
+        plain_lines.append(f"  ESDB license: {reason}")
+        plain_lines.append(
+            "  Use 'specsmith esdb enable --key-file <path>' to activate ChronoStore."
+        )
     if auto_counts:
-        console.print(
+        markup_lines.append(
             "  [cyan]\u27f3[/cyan] Auto-migrated from legacy JSON: "
             f"{auto_counts.get('requirements', 0)} requirements + "
             f"{auto_counts.get('testcases', 0)} testcases "
             f"({auto_counts.get('skipped', 0)} skipped)"
         )
+        plain_lines.append(
+            "  Auto-migrated from legacy JSON: "
+            f"{auto_counts.get('requirements', 0)} requirements + "
+            f"{auto_counts.get('testcases', 0)} testcases "
+            f"({auto_counts.get('skipped', 0)} skipped)"
+        )
+
+    def _emit_plain() -> None:
+        """Resiliently write the plain-text status block (mirrors the --json branch)."""
+        plain_text = "\n".join(plain_lines)
+        try:
+            sys.stdout.write(plain_text + "\n")
+            sys.stdout.flush()
+        except Exception as out_exc:  # noqa: BLE001
+            try:
+                sys.stderr.write(
+                    _json.dumps(
+                        {
+                            "ok": False,
+                            "error": "esdb status: stdout write failed",
+                            "reason": str(out_exc),
+                            "backend": active_backend,
+                            "record_count": record_count,
+                        }
+                    )
+                    + "\n"
+                )
+                sys.stderr.flush()
+            except Exception:  # noqa: BLE001
+                pass
+            raise SystemExit(1) from out_exc
+
+    try:
+        console.print("\n".join(markup_lines))
+    except (KeyboardInterrupt, Exception):  # noqa: BLE001
+        _emit_plain()
 
 
 @esdb_group.command(name="verify-chain")
@@ -11888,12 +11855,13 @@ def esdb_migrate_cmd(project_dir: str, as_json: bool) -> None:
 @click.option("--project-dir", type=click.Path(exists=True), default=".")
 @click.option("--json", "as_json", is_flag=True, default=False)
 def esdb_replay_cmd(project_dir: str, as_json: bool) -> None:
-    """Replay the trace vault WAL and verify SHA-256 hash chain integrity.
+    """Replay the trace vault and verify SHA-256 hash chain integrity.
 
-    Reads .specsmith/trace.jsonl and walks every seal entry, recomputing
-    each entry_hash from its stored content_hash + prev_hash and comparing
-    to the stored value. Any mismatch indicates tampering or corruption.
-    Also reports ledger.jsonl entry count as a secondary consistency signal.
+    Reads seal records from the ESDB (``seal_record`` kind; REQ-420) and walks
+    every seal entry, recomputing each entry_hash from its stored content_hash +
+    prev_hash and comparing to the stored value. Any mismatch indicates tampering
+    or corruption. Also reports ledger.jsonl entry count as a secondary
+    consistency signal.
     """
     import json as _json
 
@@ -14002,9 +13970,12 @@ def resume_cmd(
     with contextlib.suppress(Exception):
         bridge = EsdbBridge(str(root))
         status = bridge.status()
+        # REQ-417: the leading ESDB indicator must reflect the real chain state,
+        # not a hardcoded green check.
         chain_icon = "\u2713" if status.chain_valid else "\u2717"
+        chain_color = "green" if status.chain_valid else "red"
         console.print(
-            f"  [green]\u2713[/green] ESDB: {status.backend} "
+            f"  [{chain_color}]{chain_icon}[/{chain_color}] ESDB: {status.backend} "
             f"({status.record_count} records, chain {chain_icon})"
         )
 

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/compliance/evidence.py

@@ -163,17 +163,21 @@ class EvidenceCollector:
             )
         )
 
-        # Trace vault
-        trace = self.root / ".specsmith" / "trace.jsonl"
+        # Trace vault (REQ-420: seals are ESDB ``seal_record`` entries, no
+        # longer a .specsmith/trace.jsonl flat file).
+        from specsmith.trace import count_seal_records
+
+        seal_count = count_seal_records(self.root)
         items.append(
             EvidenceItem(
                 control_id="Art.12",
                 regulation_id="*",
-                description="SHA-256 chained trace vault (decision seals)",
-                source=".specsmith/trace.jsonl",
-                source_type="file",
-                confidence=0.9 if trace.exists() else 0.1,
-                present=trace.exists(),
+                description="SHA-256 chained trace vault (decision seals, ESDB seal_record)",
+                source="ESDB seal_record (.specsmith/esdb.sqlite3 | .chronomemory/)",
+                source_type="esdb",
+                confidence=0.9 if seal_count > 0 else 0.1,
+                present=seal_count > 0,
+                detail=f"{seal_count} seal(s) in ESDB",
             )
         )
 

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/compliance/regulations.py

@@ -127,7 +127,8 @@ _EU_AI_ACT = Regulation(
             category="logging",
             specsmith_controls=[
                 "specsmith trace (SHA-256 chain)",
-                ".specsmith/trace.jsonl",
+                # DEPRECATED(REQ-421): legacy trace.jsonl replaced by ESDB seal_record.
+                "ESDB seal_record (.specsmith/esdb.sqlite3 | .chronomemory/)",
                 "ChronoStore WAL (.chronomemory/events.wal)",
                 ".specsmith/ledger.jsonl",
                 "specsmith trace verify",

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/config.py

@@ -141,7 +141,7 @@ class ProjectConfig(BaseModel):
         ),
     )
     language: str = Field(default="python", description="Primary language/runtime")
-    spec_version: str = Field(default="0.17.1", description="Spec version to scaffold from")
+    spec_version: str = Field(default="0.18.0", description="Spec version to scaffold from")
     description: str = Field(default="", description="Short project description")
 
     # Options
@@ -451,7 +451,7 @@ class ProjectConfig(BaseModel):
     )
     enable_trace_vault: bool = Field(
         default=False,
-        description="Enable cryptographic trace vault (.specsmith/trace.jsonl)",
+        description="Enable cryptographic trace vault (ESDB seal_record; REQ-420)",
     )
 
     @property

{specsmith-0.17.1.dev684 → specsmith-0.18.0.dev686}/src/specsmith/context_orchestrator.py

@@ -360,18 +360,37 @@ class ContextOrchestrator:
             return 0
 
     def _count_critical_records(self) -> int:
-        """Count records that qualify as critical (must be protected)."""
+        """Count records that qualify as critical (must be protected).
+
+        REQ-422: parity across backends — prefer the ChronoStore WAL when present,
+        otherwise count active high-confidence records from the free SQLite ESDB
+        backend so the protection path behaves identically without ChronoStore.
+        """
+        # --- ChronoStore first (commercial backend) -------------------------
         wal = self.root / ".chronomemory" / "events.wal"
-        if not wal.exists():
-            return 0
+        if wal.exists():
+            try:
+                from chronomemory import ChronoStore
+
+                with ChronoStore(self.root) as store:
+                    return sum(
+                        1
+                        for r in store.query()
+                        if r.confidence >= CRITICAL_CONFIDENCE and r.status == "active"
+                    )
+            except Exception:  # noqa: BLE001
+                pass  # fall through to SqliteStore
+
+        # --- Fall back to SqliteStore (free default backend) ----------------
         try:
-            from chronomemory import ChronoStore
+            from specsmith.esdb import SqliteStore
 
-            with ChronoStore(self.root) as store:
+            sqlite_path = self.root / ".specsmith" / "esdb.sqlite3"
+            if not sqlite_path.exists():
+                return 0
+            with SqliteStore(self.root) as store:
                 return sum(
-                    1
-                    for r in store.query()
-                    if r.confidence >= CRITICAL_CONFIDENCE and r.status == "active"
+                    1 for r in store.query(status="active") if r.confidence >= CRITICAL_CONFIDENCE
                 )
         except Exception:  # noqa: BLE001
             return 0