specsmither 0.1.0__py3-none-any.whl

specsmither/__init__.py

@@ -0,0 +1,17 @@
+"""specsmither — local-first, NO-LLM reimplementation of the SpecForge engine.
+
+Drives a software scope through ``Specification → Epic → Ticket → DAG`` over a
+single SQLite file. Imports the two pure gates side-by-side: ``crucible`` (the
+planning gate) and ``assay`` (the work gate, 0.2.0). The engine is fully
+deterministic and synchronous; only the MCP server and the TUI are async
+presentation adapters over it.
+
+M0 (this layer): ``domain/``, ``db/``, ``dag/``, ``rollups/``, ``operations/``,
+``adapters/`` — the deterministic substrate. No lifecycle, MCP, or CLI yet.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

specsmither/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters: the WritePlan executor (apply ``WritePlanItem[]`` in one
+``Session.begin()`` then run the recompute worklist) and the in-memory
+operations projector (project a post-mutation ``SpecFull`` without persisting,
+so the gate can score as-if-applied).
+"""

specsmither/adapters/config.py

@@ -0,0 +1,134 @@
+"""Config resolution — the pure merge layer over the :class:`ConfigStore` seam.
+
+Faithful port of ``lifecycle/config.ts`` (work item #6, A1 §6). Two config domains
+feed the lifecycle; both resolve the same way — baseline defaults, then the project
+override, then (if a spec is in play) the frozen spec snapshot — but they merge with
+different machinery:
+
+* **``planning``** — the crucible ``ValidatorConfig`` (thresholds, tiers, topology,
+  cross-validation). Owned by crucible; merged by :func:`crucible.merge_config`
+  (which deep-merges *and re-validates* the result). :func:`resolve_validator_config`
+  layers ``crucible.load_defaults()`` ← project overrides ← spec snapshot.
+
+* **``planning-lifecycle``** — the lifecycle guidance knobs. After the ME.10.5 trim
+  (and dropping ``observatoryBaseUrl`` — observatory links are cosmetic prose — and
+  ``gateResultCacheTtlMs`` — the CPS stale-cache TTL is baked locally), this is just
+  :data:`PLANNING_LIFECYCLE_DEFAULTS`: ``guidance.{maxNextEntitiesToShow,
+  fieldRenderDetail}``. :func:`resolve_lifecycle_config` layers it via the pure
+  :func:`deep_merge` (no schema, no validation — the shape is tiny and fixed).
+
+Both resolvers read from a :class:`specsmither.lifecycle.ports.ConfigStore`. The async
+``PlanningLifecycleConfigResolver`` / ``PlanningConfigResolver`` classes collapse to
+these two sync functions — SpecSmither has no async I/O and assembles the effective
+config straight from the store (A1 §5, ports.py ``LifecyclePorts.config_store``).
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import TYPE_CHECKING, Any
+
+import crucible
+
+if TYPE_CHECKING:
+    from specsmither.lifecycle.ports import ConfigStore
+
+__all__ = [
+    "PLANNING_DOMAIN",
+    "PLANNING_LIFECYCLE_CONFIG_SCHEMA_VERSION",
+    "PLANNING_LIFECYCLE_DEFAULTS",
+    "PLANNING_LIFECYCLE_DOMAIN",
+    "deep_merge",
+    "resolve_lifecycle_config",
+    "resolve_validator_config",
+]
+
+#: The crucible ``ValidatorConfig`` namespace (mirrors ``crucible.PLANNING_CONFIG_DOMAIN``).
+PLANNING_DOMAIN = "planning"
+#: The lifecycle-guidance namespace (TS ``PLANNING_LIFECYCLE_CONFIG_DOMAIN``).
+PLANNING_LIFECYCLE_DOMAIN = "planning-lifecycle"
+#: The schema version stamped on a ``planning-lifecycle`` write (TS bumped 1→2 at the
+#: ME.10.5 clean-break trim). Surfaced for the spec-create snapshot freeze (L4).
+PLANNING_LIFECYCLE_CONFIG_SCHEMA_VERSION = 2
+
+#: Baseline ``planning-lifecycle`` config — merged under project/spec overrides.
+#: Trimmed to the two surviving guidance knobs (see module docstring).
+PLANNING_LIFECYCLE_DEFAULTS: dict[str, Any] = {
+    "guidance": {
+        # Max entities shown in the expansion-phase "next to fill" block. Caps size.
+        "maxNextEntitiesToShow": 3,
+        # Phase-entry field-block fidelity: 'rich' (full per-field render) | 'concise'.
+        "fieldRenderDetail": "rich",
+    },
+}
+
+
+def deep_merge(base: dict[str, Any], override: Any) -> dict[str, Any]:
+    """Recursively merge *override* onto *base* (the PURE resolver merge, config.ts:32-53).
+
+    Rules (identical for both config domains):
+
+    * a non-mapping *override* (``None``, a list, a primitive) leaves *base* unchanged;
+    * a ``None`` value at any key is skipped (an override never *unsets* a default);
+    * a list or primitive value **replaces** the corresponding key wholesale;
+    * two mappings at the same key **merge recursively**.
+
+    Never mutates either argument — *base* is shallow-copied per level (the resolvers
+    feed a deep copy of the defaults, so nested defaults are never aliased into a
+    returned result that a caller might mutate).
+    """
+    if not isinstance(override, dict):
+        return dict(base)
+    result: dict[str, Any] = dict(base)
+    for key, value in override.items():
+        if value is None:
+            continue
+        existing = result.get(key)
+        if isinstance(value, dict) and isinstance(existing, dict):
+            # Two mappings → merge recursively (lists/primitives fall through, replacing).
+            result[key] = deep_merge(existing, value)
+        else:
+            result[key] = value
+    return result
+
+
+def resolve_validator_config(
+    config_store: ConfigStore, project_id: str, spec_id: str | None = None
+) -> dict[str, Any]:
+    """Resolve the effective crucible ``ValidatorConfig`` (domain ``planning``).
+
+    Layers ``crucible.load_defaults()`` ← the project's overrides ← (if *spec_id* is
+    given) the spec's frozen snapshot, via :func:`crucible.merge_config` (deep-merge +
+    re-validate). With no stored overrides this returns the crucible defaults verbatim.
+    """
+    overrides: list[dict[str, Any]] = []
+    project_overrides = config_store.get_project_overrides(project_id, PLANNING_DOMAIN)
+    if project_overrides is not None:
+        overrides.append(project_overrides)
+    if spec_id is not None:
+        snapshot = config_store.get_spec_snapshot(spec_id, PLANNING_DOMAIN)
+        if snapshot is not None:
+            overrides.append(snapshot)
+    return crucible.merge_config(crucible.load_defaults(), *overrides)
+
+
+def resolve_lifecycle_config(
+    config_store: ConfigStore, project_id: str, spec_id: str | None = None
+) -> dict[str, Any]:
+    """Resolve the effective ``PlanningLifecycleConfig`` (domain ``planning-lifecycle``).
+
+    Layers :data:`PLANNING_LIFECYCLE_DEFAULTS` ← the project's overrides ← (if
+    *spec_id* is given) the spec's frozen snapshot, via the pure :func:`deep_merge`.
+    With no stored overrides this returns the defaults. The defaults are deep-copied
+    up front so the module-level constant is never aliased into the result.
+    """
+    result = deep_merge(
+        copy.deepcopy(PLANNING_LIFECYCLE_DEFAULTS),
+        config_store.get_project_overrides(project_id, PLANNING_LIFECYCLE_DOMAIN),
+    )
+    if spec_id is not None:
+        result = deep_merge(
+            result,
+            config_store.get_spec_snapshot(spec_id, PLANNING_LIFECYCLE_DOMAIN),
+        )
+    return result

specsmither/adapters/crucible_validator.py

@@ -0,0 +1,279 @@
+"""Crucible-backed :class:`~specsmither.lifecycle.ports.Validator` (work item #5).
+
+Faithful port of ``lifecycle/adapters/validator-adapter.ts`` (A1 §3.2). This is
+the one *coupled* seam between the pure planning lifecycle and crucible — the
+deterministic OpenSpec validation engine. The lifecycle only ever reads the flat
+:class:`~specsmither.lifecycle.ports.ValidatorOutput` contract; this adapter maps
+crucible's richer four-layer result down to it.
+
+The mapping in one paragraph
+----------------------------
+
+:meth:`CrucibleValidatorAdapter.validate` short-circuits the terminal ``planned``
+sentinel (and any non-validator phase) to a trivial pass *before* touching
+crucible. For the six real phases it dumps the nested
+:class:`~crucible.models.Specification` to crucible's camelCase wire dict, scopes
+``activeEntityId`` (the two ``*_expansion`` phases score per entity, so they pass
+the full id list; everything else — including ``ticket_decomposition``, which is
+spec-wide — passes ``None``), and calls :func:`crucible.validate` for the
+``structural`` / ``scoring`` / ``guidance`` layers. ``gate_result`` / ``local_score``
+come from the active ``scoring`` layer (a *skipped* or *absent* scoring layer maps
+to ``'fail'`` / ``0.0``, mirroring the TS ``scoring && !scoring.skipped`` guard);
+the per-entity scores route to ``per_epic_score`` on ``epic_expansion`` and
+``per_ticket_score`` on ``ticket_expansion`` (``{}`` on every other phase); and
+``findings`` flattens crucible's structural findings + per-entity guidance entries
+into the lifecycle's :class:`~specsmither.lifecycle.ports.ValidatorFinding` list.
+
+Faithful-port notes
+--------------------
+
+* crucible's ``validate`` is **synchronous** (the engine has no async I/O) — the
+  TS ``Promise`` wrapper drops, exactly as the rest of the SpecSmither seam went
+  sync.
+* :data:`_VALIDATOR_OP_TO_PATH` keys are crucible's ``OperationName`` vocabulary
+  (``add_dependencies`` / ``remove_dependency`` / ``link_blueprint`` …), *not* the
+  lifecycle's 15-op planning names — cross-validation guidance entries carry the
+  validator-side op names, so the table is ported verbatim from the TS adapter.
+* Every emitted finding carries ``severity='finding'`` (advisory); crucible's own
+  ``error``/``warning`` severities are not surfaced — the TS adapter hardcodes
+  ``'finding'`` because the gate, not the finding, is the hard signal.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from crucible import validate as crucible_validate
+from crucible.types import (
+    GuidanceCrossValidationEntry,
+    GuidanceMessage,
+    ScoringResultActive,
+    StructuralFinding,
+    ValidationResult,
+)
+
+from specsmither.domain.enums import FindingCategory, PlanningPhase
+from specsmither.lifecycle.ports import SpecFull, ValidatorFinding, ValidatorOutput
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["CrucibleValidatorAdapter"]
+
+
+# --------------------------------------------------------------------------- #
+# Phase set + op→path table (ported verbatim from validator-adapter.ts)        #
+# --------------------------------------------------------------------------- #
+
+#: Phases crucible recognises — the six real phases, excluding the ``planned``
+#: terminal sentinel the validator does not know about.
+_VALIDATOR_PHASES: frozenset[str] = frozenset(
+    {
+        PlanningPhase.PLANNING_SPEC,
+        PlanningPhase.EPIC_DECOMPOSITION,
+        PlanningPhase.EPIC_EXPANSION,
+        PlanningPhase.TICKET_DECOMPOSITION,
+        PlanningPhase.TICKET_EXPANSION,
+        PlanningPhase.CROSS_VALIDATION,
+    }
+)
+
+#: crucible validator op name → lifecycle cross-validation path prefix. Keys are
+#: crucible's ``OperationName`` vocabulary, surfaced on cross-validation guidance
+#: entries' ``operations``.
+_VALIDATOR_OP_TO_PATH: dict[str, str] = {
+    "set_metadata": "/cross-validation/by-op/set_metadata",
+    "create_epic": "/cross-validation/by-op/create_epic",
+    "update_epic": "/cross-validation/by-op/update_epic",
+    "delete_epic": "/cross-validation/by-op/delete_epic",
+    "create_ticket": "/cross-validation/by-op/create_ticket",
+    "update_ticket": "/cross-validation/by-op/update_ticket",
+    "delete_ticket": "/cross-validation/by-op/delete_ticket",
+    "add_dependencies": "/cross-validation/by-op/add_dependencies",
+    "remove_dependency": "/cross-validation/by-op/remove_dependency",
+    "create_blueprint": "/cross-validation/by-op/create_blueprint",
+    "update_blueprint": "/cross-validation/by-op/update_blueprint",
+    "delete_blueprint": "/cross-validation/by-op/delete_blueprint",
+    "link_blueprint": "/cross-validation/by-op/link_blueprint",
+    "unlink_blueprint": "/cross-validation/by-op/unlink_blueprint",
+}
+
+
+# --------------------------------------------------------------------------- #
+# Pure mapping helpers                                                         #
+# --------------------------------------------------------------------------- #
+
+
+def _entity_path(entity_type: str, entity_id: str) -> str:
+    """``entityType``/``entityId`` → the lifecycle locator path (``entityPath``)."""
+    if entity_type == "specification":
+        return "/spec"
+    if entity_type == "epic":
+        return f"/epics/{entity_id}"
+    return f"/tickets/{entity_id}"  # ticket
+
+
+def _structural_finding_to_finding(finding: StructuralFinding) -> ValidatorFinding:
+    """Map a crucible structural finding → a ``schema`` / ``count`` finding."""
+    category = finding.category
+    is_count = "count" in category or category == "entity-count"
+    return ValidatorFinding(
+        category=FindingCategory.COUNT if is_count else FindingCategory.SCHEMA,
+        message=finding.message,
+        severity="finding",
+        entity_id=None,
+        entity_type=None,
+        path=f"/structural/{finding.field}",
+        points_lost=0.0,
+        global_impact_on_fix=0.0,
+    )
+
+
+def _guidance_message_to_finding(entry: GuidanceMessage) -> ValidatorFinding:
+    """Map a crucible per-entity guidance message → a ``rubric`` finding."""
+    return ValidatorFinding(
+        category=FindingCategory.RUBRIC,
+        message=entry.message,
+        severity="finding",
+        entity_id=entry.entity_id,
+        entity_type=entry.entity_type,
+        path=_entity_path(entry.entity_type, entry.entity_id),
+        points_lost=entry.points_lost,
+        global_impact_on_fix=entry.global_impact_on_fix,
+    )
+
+
+def _cross_validation_entry_to_finding(
+    entry: GuidanceCrossValidationEntry,
+) -> ValidatorFinding:
+    """Map a crucible cross-validation entry → a ``cross-validation`` finding."""
+    first_op = entry.operations[0] if entry.operations else None
+    if first_op is not None:
+        path = _VALIDATOR_OP_TO_PATH.get(first_op, f"/cross-validation/{first_op}")
+    else:
+        path = "/cross-validation/unknown"
+    return ValidatorFinding(
+        category=FindingCategory.CROSS_VALIDATION,
+        message=entry.message,
+        severity="finding",
+        entity_id=entry.primary_entity_id,
+        entity_type=None,
+        path=path,
+        points_lost=0.0,
+        global_impact_on_fix=0.0,
+    )
+
+
+def _collect_findings(result: ValidationResult) -> list[ValidatorFinding]:
+    """Flatten structural findings + per-entity guidance into the flat list."""
+    findings: list[ValidatorFinding] = []
+
+    # Structural findings (schema / count checks).
+    if result.structural is not None:
+        for structural in result.structural.findings:
+            findings.append(_structural_finding_to_finding(structural))
+
+    # Guidance findings (rubric / cross-validation), keyed per entity.
+    if result.guidance is not None:
+        for entries in result.guidance.per_entity.values():
+            for entry in entries:
+                if isinstance(entry, GuidanceCrossValidationEntry):
+                    findings.append(_cross_validation_entry_to_finding(entry))
+                else:
+                    findings.append(_guidance_message_to_finding(entry))
+
+    return findings
+
+
+def _get_active_entity_id(
+    spec_full: SpecFull, phase: PlanningPhase
+) -> str | list[str] | None:
+    """Scope crucible's ``activeEntityId`` (``getActiveEntityId``).
+
+    Only the per-entity SCORE phases carry an active entity: ``epic_expansion``
+    scopes to the epic ids being scored, ``ticket_expansion`` to the ticket ids
+    (flattened across epics). ``ticket_decomposition`` is spec-wide (its ratio +
+    structural checks span ALL tickets of ALL epics), so — like every other phase
+    — it returns ``None``, which crucible resolves to the whole spec.
+    """
+    if phase == PlanningPhase.EPIC_EXPANSION:
+        return [epic.id for epic in spec_full.epics]
+    if phase == PlanningPhase.TICKET_EXPANSION:
+        return [ticket.id for epic in spec_full.epics for ticket in epic.tickets]
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# The adapter                                                                  #
+# --------------------------------------------------------------------------- #
+
+
+class CrucibleValidatorAdapter:
+    """Implements :class:`~specsmither.lifecycle.ports.Validator` over crucible.
+
+    Stateless — a single instance is safe to share across the lifecycle. The
+    ``config`` argument is the already-merged effective ``ValidatorConfig`` dict
+    (defaults + project overrides + frozen spec snapshot); this adapter passes it
+    straight through to :func:`crucible.validate`.
+    """
+
+    def validate(
+        self, spec_full: SpecFull, phase: PlanningPhase, config: Mapping[str, Any]
+    ) -> ValidatorOutput:
+        """Score ``spec_full`` for ``phase`` → a flat :class:`ValidatorOutput`."""
+        # 'planned' (and any non-validator phase) → trivial pass; never call
+        # crucible, which does not recognise the terminal sentinel.
+        if phase not in _VALIDATOR_PHASES:
+            return ValidatorOutput(
+                gate_result="pass",
+                local_score=1.0,
+                per_epic_score={},
+                per_ticket_score={},
+                findings=[],
+                validated_phase=phase,
+            )
+
+        active_entity_id = _get_active_entity_id(spec_full, phase)
+        spec_dict = spec_full.spec.model_dump(by_alias=True, exclude_none=True)
+
+        context: dict[str, Any] = {
+            "phase": phase,
+            "config": config,
+            "activeEntityId": active_entity_id,
+            "returns": ["structural", "scoring", "guidance"],
+        }
+        result = cast(ValidationResult, crucible_validate(spec_dict, context))
+
+        # gate_result is the AUTHORITATIVE per-phase verdict crucible composes
+        # across all layers (structural counts for the decomposition phases,
+        # the cross-validation layer for cross_validation, scoring-threshold for
+        # the rubric phases) — exposed as the top-level ``result.passed``. Reading
+        # only ``scoring.gate_result`` (as the TS adapter did) wrongly fails every
+        # non-scoring phase, making the loop unable to reach ``ready``.
+        # local_score / per-entity scores still come from the active scoring layer
+        # (a skipped/absent layer has no rubric score → 0.0).
+        scoring = result.scoring
+        gate_result: Literal["pass", "fail"] = "pass" if result.passed else "fail"
+        if isinstance(scoring, ScoringResultActive):
+            local_score = scoring.local_score
+            per_entity_score = scoring.per_entity_score or {}
+        else:
+            local_score = 0.0
+            per_entity_score = {}
+
+        # epic_expansion populates epic ids; ticket_expansion populates ticket
+        # ids; every other phase leaves both empty (the validator only scores
+        # per-entity on the two expansion phases).
+        per_epic_score = per_entity_score if phase == PlanningPhase.EPIC_EXPANSION else {}
+        per_ticket_score = (
+            per_entity_score if phase == PlanningPhase.TICKET_EXPANSION else {}
+        )
+
+        return ValidatorOutput(
+            gate_result=gate_result,
+            local_score=local_score,
+            per_epic_score=per_epic_score,
+            per_ticket_score=per_ticket_score,
+            findings=_collect_findings(result),
+            validated_phase=phase,
+        )