specsmith 0.17.1.dev661__tar.gz → 0.17.1.dev664__tar.gz

{specsmith-0.17.1.dev661/src/specsmith.egg-info → specsmith-0.17.1.dev664}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.17.1.dev661
+Version: 0.17.1.dev664
 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.dev661 → specsmith-0.17.1.dev664}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.17.1.dev661"
+version = "0.17.1.dev664"
 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.dev661 → specsmith-0.17.1.dev664}/src/specsmith/agent/context_seed.py

@@ -27,14 +27,17 @@ left off (extended to cover full epistemic continuity).
 from __future__ import annotations
 
 import json
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any
 
-# Maximum total characters injected as seed context.  Large enough to
-# carry meaningful history; small enough not to bloat every prompt.
-_SEED_CHAR_BUDGET = 8_000
+# Maximum total characters injected as seed context.  Raised from 8 000 to
+# 12 000 to accommodate the richer per-kind ESDB query output (REQ-399).
+_SEED_CHAR_BUDGET = 12_000
 _MAX_LEDGER_LINES = 30
-_MAX_ESDB_RECORDS = 5
+_MAX_PREFLIGHT_RECORDS = 10  # preflight_decision records (conf≥0.6)
+_MAX_VERIFY_RECORDS = 5  # verify_result records (conf≥0.6)
+_MAX_WI_RECORDS = 5  # work_item records (active status only)
 
 
 def build_context_seed(
@@ -42,7 +45,9 @@ def build_context_seed(
     *,
     char_budget: int = _SEED_CHAR_BUDGET,
     max_ledger: int = _MAX_LEDGER_LINES,
-    max_esdb: int = _MAX_ESDB_RECORDS,
+    max_preflight: int = _MAX_PREFLIGHT_RECORDS,
+    max_verify: int = _MAX_VERIFY_RECORDS,
+    max_wi: int = _MAX_WI_RECORDS,
 ) -> list[dict[str, Any]]:
     """Return a list of history turns to prepend to a new agent session.
 
@@ -50,11 +55,20 @@ def build_context_seed(
     state or missing optional dependency can never prevent the agent from
     starting.
 
+    The ESDB query is now **relevance-based** (REQ-399): records are fetched by
+    kind (preflight_decision, verify_result, work_item) rather than returning
+    the last N records by insertion order.  Only active records with
+    confidence ≥ 0.6 are included.  This ensures epistemically low-quality
+    records (failed approaches, stale decisions, low-confidence hypotheses) are
+    excluded from the context window.
+
     Args:
         project_dir: Project root containing ``.specsmith/``.
         char_budget: Maximum total characters across all seed turns.
         max_ledger: Maximum LEDGER.md lines to include.
-        max_esdb: Maximum ESDB ChronoRecords to include.
+        max_preflight: Max preflight_decision records to include.
+        max_verify: Max verify_result records to include.
+        max_wi: Max active work_item records to include.
 
     Returns:
         List of ``{role: str, content: str}`` dicts, oldest first.
@@ -72,7 +86,7 @@ def build_context_seed(
             turns.append({"role": "system", "content": content})
             used += len(content)
 
-    # ── 2. Prior conversation history ────────────────────────────────
+    # ── 2. Prior conversation history ────────────────────────────
     hist_turns = _load_conversation_history(root, budget=char_budget - used)
     for t in hist_turns:
         c = json.dumps(t, ensure_ascii=False)
@@ -81,7 +95,7 @@ def build_context_seed(
         turns.append(t)
         used += len(c)
 
-    # ── 3. Recent LEDGER entries ─────────────────────────────────────
+    # ── 3. Recent LEDGER entries ─────────────────────────────────
     ledger_block = _load_ledger_snippet(root, max_lines=max_ledger)
     if ledger_block and used + len(ledger_block) <= char_budget:
         turns.append(
@@ -92,13 +106,21 @@ def build_context_seed(
         )
         used += len(ledger_block)
 
-    # ── 4. Recent ESDB records ───────────────────────────────────────
-    esdb_block = _load_esdb_snippet(root, max_records=max_esdb)
+    # ── 4. ESDB records — relevance-based by kind (REQ-399) ──────────────
+    esdb_block = _load_esdb_by_kind(
+        root,
+        max_preflight=max_preflight,
+        max_verify=max_verify,
+        max_wi=max_wi,
+    )
     if esdb_block and used + len(esdb_block) <= char_budget:
         turns.append(
             {
                 "role": "system",
-                "content": f"[Recent ESDB records — last {max_esdb}]\n{esdb_block}",
+                "content": (
+                    "[ESDB governance context — active preflight"
+                    f" decisions, verify results, work items]\n{esdb_block}"
+                ),
             }
         )
 
@@ -185,31 +207,107 @@ def _load_ledger_snippet(root: Path, *, max_lines: int) -> str:
         return ""
 
 
-def _load_esdb_snippet(root: Path, *, max_records: int) -> str:
-    """Return a compact summary of the most recent ESDB ChronoRecords.
-
-    Uses query.what_is_known() (not store.query()) so infrastructure records
-    (edge, rollback_event, token_metric, skill_run) are excluded from the
-    LLM context seed — critical rule §23 / ESDB spec rule 3.
+def _load_esdb_by_kind(
+    root: Path,
+    *,
+    max_preflight: int = 10,
+    max_verify: int = 5,
+    max_wi: int = 5,
+) -> str:
+    """Return a compact, epistemically-filtered ESDB context block (REQ-399).
+
+    Queries three specific kinds rather than "last N records by insertion
+    order" so the context seed is relevant regardless of store size:
+
+    1. ``preflight_decision`` (active, conf≥0.6) — recent accepted preflights;
+       sorted highest-confidence first so the best-evidenced ones appear.
+    2. ``verify_result``       (active, conf≥0.6) — recent verify outcomes.
+    3. ``work_item``           (active, conf≥0.6) — open/in-progress WIs.
+
+    Falls back to ``query.what_is_known()`` for ChronoStore when the SqliteStore
+    does not have records of the requested kinds (e.g. before the first preflight).
+
+    Uses ``store.query(kind=..., rag_filter=True)`` which applies the
+    confidence≥0.6 filter, honouring H18 (RAG retrieval filtering).
+    Infrastructure kinds (edge, rollback_event, token_metric, skill_run) are
+    never returned by this function — ESDB spec rule 3 / critical rule §23.
     """
+    lines: list[str] = []
+    seen_ids: set[str] = set()
+
+    def _fmt(rec: object) -> str:
+        rid = getattr(rec, "id", "?")
+        kind = getattr(rec, "kind", "?")
+        label = getattr(rec, "label", "")
+        data = getattr(rec, "data", {}) or {}
+        conf = getattr(rec, "confidence", 0.0)
+        line = f"[{rid}] {kind} (conf={conf:.2f}): {label[:120]}"
+        detail = (
+            data.get("decision")
+            or data.get("equilibrium")
+            or data.get("status")
+            or data.get("summary")
+        )
+        if detail:
+            line += f" — {str(detail)[:80]}"
+        return line
+
+    def _add_records(records: Sequence[object], max_n: int) -> None:
+        added = 0
+        for rec in sorted(records, key=lambda r: -getattr(r, "confidence", 0)):
+            if added >= max_n:
+                break
+            rid = getattr(rec, "id", None)
+            if rid and rid not in seen_ids:
+                lines.append(_fmt(rec))
+                seen_ids.add(rid)
+                added += 1
+
+    # --- Try SqliteStore (always available, no external dep) -----------------
     try:
-        from chronomemory import ChronoStore
-        from chronomemory import query as _cm_query
-
-        with ChronoStore(root) as store:
-            all_records = _cm_query.what_is_known(store)  # active, conf>=0.6, no infra
-        recent = all_records[-max_records:] if len(all_records) > max_records else all_records
-        if not recent:
-            return ""
-        lines = []
-        for rec in recent:
-            line = f"[{rec.id}] {rec.kind}: {rec.label}"
-            if rec.data.get("summary"):
-                line += f" \u2014 {str(rec.data['summary'])[:120]}"
-            lines.append(line)
-        return "\n".join(lines)
+        from specsmith.esdb import SqliteStore
+
+        sqlite_path = root / ".specsmith" / "esdb.sqlite3"
+        if sqlite_path.exists():
+            with SqliteStore(root) as store:
+                _add_records(
+                    store.query(kind="preflight_decision", rag_filter=True),
+                    max_preflight,
+                )
+                _add_records(
+                    store.query(kind="verify_result", rag_filter=True),
+                    max_verify,
+                )
+                _add_records(
+                    store.query(kind="work_item", status="active", rag_filter=True),
+                    max_wi,
+                )
     except Exception:  # noqa: BLE001
-        return ""
+        pass
+
+    # --- Supplement / fall back via ChronoStore ------------------------------
+    # Only query ChronoStore when we got fewer records than requested so we
+    # don't duplicate records that are in both backends.
+    chrono_needed = max_preflight + max_verify + max_wi - len(seen_ids)
+    if chrono_needed > 0:
+        try:
+            from chronomemory import ChronoStore
+            from chronomemory import query as _cm_query
+
+            with ChronoStore(root) as store:
+                known = _cm_query.what_is_known(store)  # active, conf>=0.6, no infra
+            # Group by kind and add missing records
+            for kind_key, max_n in (
+                ("preflight_decision", max_preflight),
+                ("verify_result", max_verify),
+                ("work_item", max_wi),
+            ):
+                kind_recs = [r for r in known if getattr(r, "kind", "") == kind_key]
+                _add_records(kind_recs, max_n)
+        except Exception:  # noqa: BLE001
+            pass
+
+    return "\n".join(lines)
 
 
 __all__ = ["build_context_seed"]

{specsmith-0.17.1.dev661 → specsmith-0.17.1.dev664}/src/specsmith/context_orchestrator.py

@@ -220,28 +220,69 @@ class ContextOrchestrator:
         min_confidence: float = 0.5,
         source_type_exclude: list[str] | None = None,
     ) -> int:
-        """Mark low-confidence records as 'evicted-from-context' in memory only.
+        """Tombstone low-confidence records in the ESDB store (REQ-400).
 
-        NOTE: This does NOT delete from the WAL — it only removes from the
-        in-context representation returned by the current query.
+        Writes back to the store (tombstone via store.delete()) so the eviction
+        persists across sessions.  Data is never physically removed — tombstone
+        only.  Infrastructure records (edge, rollback_event, token_metric,
+        skill_run) and governance records (requirement, testcase) are exempt.
 
-        Returns the count of records that would be evicted.
+        Returns the count of records actually tombstoned.
         """
+        _EXEMPT_KINDS = frozenset(
+            {
+                "requirement",
+                "testcase",
+                "edge",
+                "rollback_event",
+                "token_metric",
+                "skill_run",
+            }
+        )
 
+        # --- Try 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:
+                    records = store.query()
+                    count = 0
+                    for rec in records:
+                        if getattr(rec, "kind", "") in _EXEMPT_KINDS:
+                            continue
+                        evict = rec.confidence < min_confidence
+                        if (
+                            source_type_exclude
+                            and getattr(rec, "source_type", "") in source_type_exclude
+                        ):
+                            evict = True
+                        if evict:
+                            store.delete(rec.id)  # tombstone — never physically removed
+                            count += 1
+                    return count
+            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:
-                records = store.query()
+            sqlite_path = self.root / ".specsmith" / "esdb.sqlite3"
+            if not sqlite_path.exists():
+                return 0
+            with SqliteStore(self.root) as store:
+                records = store.query(status="active")
                 count = 0
                 for rec in records:
+                    if rec.kind in _EXEMPT_KINDS:
+                        continue
                     evict = rec.confidence < min_confidence
-                    if source_type_exclude and rec.source_type in source_type_exclude:
+                    if source_type_exclude and rec.kind in source_type_exclude:
                         evict = True
                     if evict:
+                        store.delete(rec.id)  # tombstone
                         count += 1
                 return count
         except Exception:  # noqa: BLE001

specsmith-0.17.1.dev664/src/specsmith/esdb_writer.py

@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""specsmith.esdb_writer — centralised best-effort ESDB write paths (REQ-395..402).
+
+This module provides the write paths that were previously missing from ESDB:
+  - Preflight decisions  (kind="preflight_decision")
+  - Verify results       (kind="verify_result")
+  - Work item records    (kind="work_item")
+
+All three functions are **best-effort** — they are wrapped in try/except so
+they never block their callers when ESDB is unavailable or the store fails.
+
+Backend-agnostic: uses ``open_default_store()`` which dispatches to either
+the free SQLite backend or the commercial ChronoStore backend depending on
+what is installed and licensed.
+
+Record confidence mapping:
+  preflight_decision  → payload["confidence_target"]   (0.7–0.9 typical)
+  verify_result       → 0.85 on equilibrium, 0.4 otherwise
+  work_item           → wi.confidence_target; tombstone on terminal states
+
+REQ-395: ESDBWriter utility module
+REQ-396: Preflight decision ESDB write path
+REQ-397: Verify result ESDB write path
+REQ-398: Work item ESDB synchronisation
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass  # avoid circular imports at runtime
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _short_hash(text: str, length: int = 8) -> str:
+    """Return first *length* hex chars of SHA-256 of *text*."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:length].upper()
+
+
+# ---------------------------------------------------------------------------
+# Public write functions — all best-effort (wrapped in try/except by callers)
+# ---------------------------------------------------------------------------
+
+
+def write_preflight_record(
+    project_root: str | Path,
+    payload: dict[str, Any],
+) -> bool:
+    """Upsert a ``preflight_decision`` ESDB record from a preflight payload.
+
+    Called by ``run_preflight()`` after the work item is minted.
+
+    Record shape:
+      id          = payload["work_item_id"]  (e.g. "WI-3A9F1C02")
+      kind        = "preflight_decision"
+      label       = utterance extracted from payload
+      confidence  = payload["confidence_target"]
+      source_ids  = payload["requirement_ids"]
+      status      = "active"
+      data        = {decision, intent, work_item_id, test_case_ids, ...}
+
+    Returns True on success, False on any error (error is swallowed).
+    """
+    try:
+        work_item_id = payload.get("work_item_id", "")
+        if not work_item_id:
+            return False  # only persist accepted preflights that minted a WI
+
+        from specsmith.esdb import SqliteRecord, open_default_store
+
+        root = Path(project_root)
+        pf_id = f"PF-{work_item_id}"
+        record = SqliteRecord(
+            id=pf_id,
+            kind="preflight_decision",
+            status="active",
+            label=str(payload.get("instruction", payload.get("intent", "")))[:200],
+            confidence=float(payload.get("confidence_target", 0.7)),
+            data={
+                "decision": payload.get("decision", ""),
+                "intent": payload.get("intent", ""),
+                "work_item_id": work_item_id,
+                "test_case_ids": payload.get("test_case_ids", []),
+                "instruction": payload.get("instruction", ""),
+                "ai_disclosure": payload.get("ai_disclosure", {}),
+            },
+            source_ids=list(payload.get("requirement_ids", [])),
+        )
+        with open_default_store(root, warn=False) as store:
+            store.upsert(record)
+        return True
+    except Exception:  # noqa: BLE001 — best-effort; never blocks preflight
+        return False
+
+
+def write_verify_record(
+    project_root: str | Path,
+    result: dict[str, Any],
+) -> bool:
+    """Upsert a ``verify_result`` ESDB record from a verify payload.
+
+    Called by ``run_verify()`` after the work item is marked implemented.
+
+    Record shape:
+      id          = "VERIFY-{work_item_id}"
+      kind        = "verify_result"
+      label       = brief summary string
+      confidence  = 0.85 on equilibrium else 0.4
+      source_ids  = [work_item_id] (links to preflight_decision record)
+      status      = "active"
+      data        = {equilibrium, retry_strategy, files_changed_count, ...}
+
+    When equilibrium is reached the corresponding ``preflight_decision``
+    record is tombstoned (status → "tombstone") to signal completion.
+
+    Returns True on success, False on any error.
+    """
+    try:
+        work_item_id = result.get("work_item_id", "")
+        equilibrium = bool(result.get("equilibrium", False))
+        confidence = 0.85 if equilibrium else 0.4
+
+        from specsmith.esdb import SqliteRecord, open_default_store
+
+        root = Path(project_root)
+        verify_id = (
+            f"VERIFY-{work_item_id}" if work_item_id else f"VERIFY-{_short_hash(str(result))}"
+        )
+
+        record = SqliteRecord(
+            id=verify_id,
+            kind="verify_result",
+            status="active",
+            label=str(result.get("summary", ""))[:200],
+            confidence=confidence,
+            data={
+                "equilibrium": equilibrium,
+                "confidence": result.get("confidence", confidence),
+                "retry_strategy": result.get("retry_strategy", ""),
+                "files_changed_count": len(result.get("files_changed", [])),
+                "work_item_id": work_item_id,
+            },
+            source_ids=[work_item_id] if work_item_id else [],
+        )
+        with open_default_store(root, warn=False) as store:
+            store.upsert(record)
+            # When equilibrium reached, tombstone the preflight_decision record
+            # so context seed knows this WI is complete.
+            if equilibrium and work_item_id:
+                pf_id = f"PF-{work_item_id}"
+                existing = store.get(pf_id)
+                if existing is not None and existing.kind == "preflight_decision":
+                    store.delete(pf_id)
+        return True
+    except Exception:  # noqa: BLE001 — best-effort
+        return False
+
+
+def write_work_item_record(
+    project_root: str | Path,
+    wi: Any,  # WorkItem — avoid circular import; duck-typed
+) -> bool:
+    """Upsert a ``work_item`` ESDB record mirroring a WorkItem.
+
+    Called by WorkItemStore after create/set_status/mark_implemented/promote.
+
+    Record shape:
+      id          = wi.id  (e.g. "WI-3A9F1C02")
+      kind        = "work_item"
+      label       = wi.intent[:200]
+      confidence  = wi.confidence_target
+      source_ids  = wi.requirement_ids + wi.test_case_ids
+      status      = "active"  for open/implemented
+                    "tombstone" for promoted/closed/archived/rejected
+      data        = {status, kind, verified, promoted_to_req, blast_radius, ...}
+
+    Returns True on success, False on any error.
+    """
+    try:
+        from specsmith.esdb import SqliteRecord, open_default_store
+
+        _TERMINAL = frozenset({"promoted", "closed", "archived", "rejected"})
+        esdb_status = "tombstone" if wi.status in _TERMINAL else "active"
+
+        source_ids = list(getattr(wi, "requirement_ids", []))
+        source_ids += list(getattr(wi, "test_case_ids", []))
+
+        record = SqliteRecord(
+            id=wi.id,
+            kind="work_item",
+            status=esdb_status,
+            label=str(wi.intent or wi.id)[:200],
+            confidence=float(getattr(wi, "confidence_target", 0.7)),
+            data={
+                "status": wi.status,
+                "kind": getattr(wi, "kind", "feature"),
+                "verified": getattr(wi, "verified", False),
+                "promoted_to_req": getattr(wi, "promoted_to_req", ""),
+                "blast_radius_estimate": getattr(wi, "blast_radius_estimate", ""),
+                "created_at": getattr(wi, "created_at", ""),
+                "updated_at": getattr(wi, "updated_at", ""),
+                "closed_reason": getattr(wi, "closed_reason", ""),
+            },
+            source_ids=source_ids,
+        )
+        root = Path(project_root)
+        with open_default_store(root, warn=False) as store:
+            store.upsert(record)
+        return True
+    except Exception:  # noqa: BLE001 — best-effort
+        return False
+
+
+__all__ = [
+    "write_preflight_record",
+    "write_verify_record",
+    "write_work_item_record",
+]

{specsmith-0.17.1.dev661 → specsmith-0.17.1.dev664}/src/specsmith/governance_logic.py

@@ -271,6 +271,16 @@ def run_preflight(
         except Exception:  # noqa: BLE001
             pass
 
+    # ESDB write — persist preflight decision for session resume and RAG (REQ-396).
+    # Best-effort: esdb_writer swallows all errors so ESDB is never on the
+    # critical path for preflight.
+    try:
+        from specsmith.esdb_writer import write_preflight_record
+
+        write_preflight_record(_root_str, payload)
+    except Exception:  # noqa: BLE001
+        pass
+
     return payload
 
 
@@ -370,6 +380,15 @@ def run_verify(
         except Exception:  # noqa: BLE001
             pass
 
+    # ESDB write — persist verify result for session resume and audit (REQ-397).
+    # Also tombstones the preflight_decision record on equilibrium.
+    try:
+        from specsmith.esdb_writer import write_verify_record
+
+        write_verify_record(root, out)
+    except Exception:  # noqa: BLE001
+        pass
+
     return out
 
 

{specsmith-0.17.1.dev661 → specsmith-0.17.1.dev664}/src/specsmith/migrations/__init__.py

@@ -115,6 +115,7 @@ class _MigrationRegistry:
             m005_agent_run_tool,
             m006_session_governance,
             m007_yaml_first,
+            m008_esdb_full_coverage,
         )
 
         instances: list[Migration] = [
@@ -125,6 +126,7 @@ class _MigrationRegistry:
             m005_agent_run_tool.AgentRunToolMigration(),
             m006_session_governance.SessionGovernanceMigration(),
             m007_yaml_first.YamlFirstMigration(),
+            m008_esdb_full_coverage.EsdbFullCoverageMigration(),
         ]
         instances.sort(key=lambda m: m.version)
         self._migrations = instances