crucible-forge 0.1.0__py3-none-any.whl

crucible/__init__.py

@@ -0,0 +1,57 @@
+"""crucible — deterministic validation engine for OpenSpec v1.1 specifications.
+
+Faithful Python port of the SpecForge ``@specforge/validator`` engine.
+
+``validate(spec, context)`` is the single entry point. All four return layers
+(``structural``, ``scoring``, ``crossValidation``, ``guidance``) are complete
+and verified byte-for-byte against the reference engine.
+"""
+
+from __future__ import annotations
+
+from . import models, types
+from .api import validate
+from .api.input_validation import ValidatorInputError
+from .config import (
+    CONFIG_DEFAULTS,
+    PLANNING_CONFIG_DOMAIN,
+    PLANNING_CONFIG_SCHEMA_VERSION,
+    ConfigValidationError,
+    PlanningConfigOverridesSchema,
+    PlanningConfigResolver,
+    ValidatorConfigSchema,
+    ValidatorConfigSnapshotSchema,
+    load_defaults,
+    load_from_file,
+    load_partial_from_file,
+    merge_config,
+)
+from .models import Blueprint, Epic, Specification, Ticket
+from .structural import validate_structural
+
+__all__ = [
+    "CONFIG_DEFAULTS",
+    "PLANNING_CONFIG_DOMAIN",
+    "PLANNING_CONFIG_SCHEMA_VERSION",
+    "Blueprint",
+    "ConfigValidationError",
+    "Epic",
+    "PlanningConfigOverridesSchema",
+    "PlanningConfigResolver",
+    "Specification",
+    "Ticket",
+    "ValidatorConfigSchema",
+    "ValidatorConfigSnapshotSchema",
+    "ValidatorInputError",
+    "__version__",
+    "load_defaults",
+    "load_from_file",
+    "load_partial_from_file",
+    "merge_config",
+    "models",
+    "types",
+    "validate",
+    "validate_structural",
+]
+
+__version__ = "0.1.0"

crucible/_spec.py

@@ -0,0 +1,20 @@
+"""Spec input normalization.
+
+The engine works on a camelCase ``dict`` (mirroring the TS value-resolver and
+the JSON seeds). ``validate()`` and ``validate_structural()`` accept either a
+:class:`crucible.models.Specification` or a plain mapping; both normalize here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+SpecInput = BaseModel | dict[str, Any]
+
+
+def to_spec_dict(spec: SpecInput) -> dict[str, Any]:
+    if isinstance(spec, BaseModel):
+        return spec.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return dict(spec)

crucible/api/__init__.py

@@ -0,0 +1,25 @@
+"""Validator API layer (port of ``@specforge/validator`` ``src/api``)."""
+
+from __future__ import annotations
+
+from .input_validation import ValidatorInputError, validate_input
+from .phase_classification import (
+    is_human_judgment_phase,
+    phase_includes_epics,
+    phase_includes_tickets,
+)
+from .scope_resolver import resolve_epic_scope, resolve_ticket_scope
+from .validate import validate
+from .version import get_validator_version
+
+__all__ = [
+    "ValidatorInputError",
+    "get_validator_version",
+    "is_human_judgment_phase",
+    "phase_includes_epics",
+    "phase_includes_tickets",
+    "resolve_epic_scope",
+    "resolve_ticket_scope",
+    "validate",
+    "validate_input",
+]

crucible/api/dispatcher.py

@@ -0,0 +1,59 @@
+"""Phase dispatch (port of ``api/dispatcher.ts``)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from ..types.config import ValidatorConfig
+from ..types.phase import SinglePhase
+from ..types.result import ValidationResult, ValidationResultAll, ValidationResultAllMeta
+from .phases import (
+    validate_cross_validation,
+    validate_epic_decomposition,
+    validate_epic_expansion,
+    validate_planning_spec,
+    validate_ticket_decomposition,
+    validate_ticket_expansion,
+)
+from .version import get_validator_version
+
+_PHASES = {
+    "planning_spec": validate_planning_spec,
+    "epic_decomposition": validate_epic_decomposition,
+    "epic_expansion": validate_epic_expansion,
+    "ticket_decomposition": validate_ticket_decomposition,
+    "ticket_expansion": validate_ticket_expansion,
+    "cross_validation": validate_cross_validation,
+}
+
+
+def validate_single(
+    spec: dict[str, Any],
+    phase: SinglePhase,
+    active_entity_id: str | list[str] | None,
+    config: ValidatorConfig,
+) -> ValidationResult:
+    fn = _PHASES.get(phase)
+    if fn is None:
+        raise ValueError(f"Unknown phase: {phase}")
+    return fn(spec, active_entity_id, config)
+
+
+def validate_all(
+    spec: dict[str, Any],
+    active_entity_id: str | list[str] | None,
+    config: ValidatorConfig,
+) -> ValidationResultAll:
+    by_phase = {
+        phase: fn(spec, active_entity_id, config) for phase, fn in _PHASES.items()
+    }
+    passed = all(r.passed for r in by_phase.values())
+    return ValidationResultAll(
+        passed=passed,
+        by_phase=by_phase,
+        meta=ValidationResultAllMeta(
+            validator_version=get_validator_version(),
+            generated_at=datetime.now(UTC).isoformat(),
+        ),
+    )

crucible/api/input_validation.py

@@ -0,0 +1,54 @@
+"""Context input validation (port of ``api/input-validation.ts``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_VALID_PHASES = {
+    "planning_spec",
+    "epic_decomposition",
+    "epic_expansion",
+    "ticket_decomposition",
+    "ticket_expansion",
+    "cross_validation",
+    "all",
+}
+
+# Only the per-entity SCORE phases require an active entity.
+_PHASES_REQUIRING_ENTITY_ID = {"epic_expansion", "ticket_expansion"}
+
+_VALID_RETURNS = {"structural", "scoring", "crossValidation", "guidance"}
+
+
+class ValidatorInputError(Exception):
+    """Raised when ``validate`` receives an invalid context."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"[Validator] {message}")
+        self.name = "ValidatorInputError"
+
+
+def validate_input(context: dict[str, Any]) -> None:
+    phase = context.get("phase")
+    if phase is not None and phase not in _VALID_PHASES:
+        raise ValidatorInputError(
+            f"Invalid phase '{phase}'. Must be one of: {', '.join(sorted(_VALID_PHASES))}"
+        )
+
+    active = context.get("activeEntityId")
+    has_entity_id = len(active) > 0 if isinstance(active, list) else active is not None
+
+    if phase is not None and phase in _PHASES_REQUIRING_ENTITY_ID and not has_entity_id:
+        raise ValidatorInputError(f"Phase '{phase}' requires activeEntityId")
+
+    returns = context.get("returns")
+    if returns:
+        for r in returns:
+            if r not in _VALID_RETURNS:
+                raise ValidatorInputError(
+                    f"Invalid return layer '{r}'. Must be one of: "
+                    f"{', '.join(sorted(_VALID_RETURNS))}"
+                )
+
+    if not context.get("config"):
+        raise ValidatorInputError("context.config is required")

crucible/api/phase_classification.py

@@ -0,0 +1,14 @@
+"""Phase classification helpers (port of ``api/phase-classification.ts``)."""
+
+from __future__ import annotations
+
+from ..scoring.cascade import phase_includes_epics, phase_includes_tickets
+from ..types.phase import ValidationPhase
+
+_HUMAN_JUDGMENT_PHASES = {"epic_decomposition", "ticket_decomposition"}
+
+__all__ = ["is_human_judgment_phase", "phase_includes_epics", "phase_includes_tickets"]
+
+
+def is_human_judgment_phase(phase: ValidationPhase) -> bool:
+    return phase != "all" and phase in _HUMAN_JUDGMENT_PHASES

crucible/api/phases/__init__.py

@@ -0,0 +1,19 @@
+"""Per-phase assembly functions."""
+
+from __future__ import annotations
+
+from .cross_validation import validate_cross_validation
+from .epic_decomposition import validate_epic_decomposition
+from .epic_expansion import validate_epic_expansion
+from .planning_spec import validate_planning_spec
+from .ticket_decomposition import validate_ticket_decomposition
+from .ticket_expansion import validate_ticket_expansion
+
+__all__ = [
+    "validate_cross_validation",
+    "validate_epic_decomposition",
+    "validate_epic_expansion",
+    "validate_planning_spec",
+    "validate_ticket_decomposition",
+    "validate_ticket_expansion",
+]

crucible/api/phases/_common.py

@@ -0,0 +1,103 @@
+"""Shared helpers for phase assembly."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from ...guidance.composer import compose_findings
+from ...guidance.engine import execute_rubric
+from ...guidance.format import format_guidance
+from ...scoring.global_ import GlobalScoreBreakdown as _InternalBreakdown
+from ...scoring.per_field import PerFieldResult
+from ...types.cascade import CascadeFailure, CascadeFloors
+from ...types.context import PhaseContext
+from ...types.guidance import GuidanceResult
+from ...types.result import (
+    GlobalScoreBreakdown,
+    PerFieldScore,
+    ScoringResultActive,
+    ValidationResultMeta,
+)
+from ..version import get_validator_version
+
+
+def build_guidance(spec: dict[str, Any], context: PhaseContext) -> GuidanceResult:
+    findings = execute_rubric(spec, context)
+    composites = compose_findings(findings, context, spec)
+    composed_ids = {f.rubric_entry_id for c in composites for f in c.grouped_findings}
+    individuals = [
+        f
+        for f in findings
+        if f.rubric_entry_id not in composed_ids and f.status != "fulfilled"
+    ]
+    return format_guidance(composites, individuals, context, spec)
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def build_meta(
+    *,
+    active_entity_id: str | list[str] | None = None,
+    resolution: str | None = None,
+    warnings: list[str] | None = None,
+) -> ValidationResultMeta:
+    kwargs: dict[str, object] = {
+        "validator_version": get_validator_version(),
+        "generated_at": now_iso(),
+    }
+    if active_entity_id is not None:
+        kwargs["active_entity_id"] = active_entity_id
+    if resolution is not None:
+        kwargs["resolution"] = resolution
+    if warnings:
+        kwargs["warnings"] = warnings
+    return ValidationResultMeta(**kwargs)
+
+
+def per_field_to_scores(per_field: dict[str, PerFieldResult]) -> dict[str, PerFieldScore]:
+    return {
+        k: PerFieldScore(earned=v.earned, possible=v.possible, tier=v.tier)
+        for k, v in per_field.items()
+    }
+
+
+def breakdown_model(b: _InternalBreakdown) -> GlobalScoreBreakdown:
+    return GlobalScoreBreakdown(
+        spec_block=b.spec_block,
+        epic_block=b.epic_block,
+        ticket_block=b.ticket_block,
+        epic_avg=b.epic_avg,
+        ticket_avg=b.ticket_avg,
+        weights=b.weights,
+    )
+
+
+def build_active_scoring(
+    *,
+    local_score: float,
+    per_field: dict[str, PerFieldScore],
+    breakdown: _InternalBreakdown,
+    cascade_floors: CascadeFloors,
+    cascade_failures: list[CascadeFailure],
+    gate_result: str,
+    threshold: float,
+    per_entity_score: dict[str, float] | None = None,
+) -> ScoringResultActive:
+    kwargs: dict[str, object] = {
+        "skipped": False,
+        "local_score": local_score,
+        "global_score": breakdown.global_score,
+        "per_field": per_field,
+        "topology_penalties": breakdown.topology_penalty,
+        "gate_result": gate_result,
+        "threshold": threshold,
+        "global_score_breakdown": breakdown_model(breakdown),
+        "cascade_floors": cascade_floors,
+        "cascade_failures": cascade_failures,
+    }
+    if per_entity_score is not None:
+        kwargs["per_entity_score"] = per_entity_score
+    return ScoringResultActive(**kwargs)

crucible/api/phases/cross_validation.py

@@ -0,0 +1,70 @@
+"""cross_validation phase (port of ``api/phases/cross-validation.ts``)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ...cross_validation import run_cross_validation
+from ...cross_validation.emission import CVEmission
+from ...structural import validate_structural
+from ...types.config import ValidatorConfig
+from ...types.guidance import GuidanceCrossValidationEntry, GuidanceEntry, GuidanceResult
+from ...types.result import ValidationResult
+from ._common import build_meta
+
+
+def _adapt_emission(emission: CVEmission) -> GuidanceCrossValidationEntry:
+    f = emission.finding
+    kwargs: dict[str, Any] = {
+        "pattern_id": "cross-validation",
+        "category": f.category,
+        "severity": f.severity,
+        "field_path": f.field,
+        "primary_entity_id": f.primary_entity_id,
+        "entity_ids": f.entity_ids,
+        "message": emission.guidance,
+        "operations": f.operations,
+        "points_lost": 0,
+        "global_impact_on_fix": 0,
+    }
+    if f.context is not None:
+        kwargs["context"] = f.context
+    return GuidanceCrossValidationEntry(**kwargs)
+
+
+def validate_cross_validation(
+    spec: dict[str, Any], active_entity_id: str | list[str] | None, config: ValidatorConfig
+) -> ValidationResult:
+    warnings: list[str] = []
+    if active_entity_id is not None:
+        warnings.append(
+            f"cross_validation phase ignores activeEntityId; received: "
+            f"{json.dumps(active_entity_id)}"
+        )
+
+    structural = validate_structural(spec, config, "cross_validation")
+    run = run_cross_validation(spec, config, "cross_validation")
+    cross_validation = run.result
+
+    per_entity: dict[str, list[GuidanceEntry]] = {}
+    for emission in run.emissions:
+        adapted = _adapt_emission(emission)
+        for entity_id in emission.finding.entity_ids:
+            per_entity.setdefault(entity_id, []).append(adapted)
+    guidance = GuidanceResult(per_entity=per_entity)
+
+    passed = (
+        not structural.invalid_fields
+        and not any(f.severity == "error" for f in structural.findings)
+        and not cross_validation.findings
+    )
+
+    return ValidationResult(
+        phase="cross_validation",
+        passed=passed,
+        structural=structural,
+        cross_validation=cross_validation,
+        guidance=guidance,
+        meta=build_meta(active_entity_id=active_entity_id, warnings=warnings or None),
+    )

crucible/api/phases/epic_decomposition.py

@@ -0,0 +1,40 @@
+"""epic_decomposition phase (port of ``api/phases/epic-decomposition.ts``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...engines.ratios import check_blueprint_epic_ratio
+from ...guidance.fixed_prompts import build_epic_decomposition_guidance
+from ...structural import validate_structural
+from ...types.config import ValidatorConfig
+from ...types.result import CrossValidationResult, ScoringResultSkipped, ValidationResult
+from ._common import build_meta
+
+
+def validate_epic_decomposition(
+    spec: dict[str, Any], _active_entity_id: str | list[str] | None, config: ValidatorConfig
+) -> ValidationResult:
+    structural = validate_structural(spec, config, "epic_decomposition")
+    ratio_findings = check_blueprint_epic_ratio(spec, config)
+
+    passed = (
+        not ratio_findings
+        and not structural.invalid_fields
+        and not any(f.severity == "error" for f in structural.findings)
+    )
+
+    return ValidationResult(
+        phase="epic_decomposition",
+        passed=passed,
+        structural=structural,
+        scoring=ScoringResultSkipped(),
+        cross_validation=CrossValidationResult(
+            skipped=False,
+            findings=ratio_findings,
+            ran_checks=["blueprint-epic-ratio"],
+            skipped_checks=[],
+        ),
+        guidance=build_epic_decomposition_guidance(spec),
+        meta=build_meta(),
+    )

crucible/api/phases/epic_expansion.py

@@ -0,0 +1,99 @@
+"""epic_expansion phase (port of ``api/phases/epic-expansion.ts``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...checks.coverage import validate_nfr_coverage, validate_requirement_coverage
+from ...checks.na_validation import validate_na_epic
+from ...guidance.rubric import get_rubric_for_phase
+from ...scoring import (
+    CascadeGateInput,
+    compute_cascade_floors,
+    compute_entity_score,
+    compute_global_score,
+    evaluate_cascade_gate,
+)
+from ...structural import validate_structural
+from ...types.config import ValidatorConfig
+from ...types.context import PhaseContext
+from ...types.result import CrossValidationResult, ValidationResult
+from ..scope_resolver import resolve_epic_scope
+from ._common import build_active_scoring, build_guidance, build_meta
+
+
+def validate_epic_expansion(
+    spec: dict[str, Any], active_entity_id: str | list[str] | None, config: ValidatorConfig
+) -> ValidationResult:
+    scoped_epics = resolve_epic_scope(spec, active_entity_id)
+    structural = validate_structural(spec, config, "epic_expansion")
+
+    epic_entries = [
+        e for e in get_rubric_for_phase("epic_expansion") if e.field_path.startswith("epic.")
+    ]
+    per_entity_score: dict[str, float] = {}
+    scores: list[float] = []
+    for epic in scoped_epics:
+        result = compute_entity_score(epic, epic_entries, config)
+        per_entity_score[epic["id"]] = result.local_score
+        scores.append(result.local_score)
+    avg_local = 100.0 if not scores else sum(scores) / len(scores)
+
+    breakdown = compute_global_score(spec, config["scoring"]["weights"], config)
+    cascade_floors = compute_cascade_floors(config)
+    cascade = evaluate_cascade_gate(
+        CascadeGateInput(
+            global_score=breakdown.global_score,
+            spec_block=breakdown.spec_block,
+            epic_block=breakdown.epic_block,
+            phase="epic_expansion",
+            floors=cascade_floors,
+        )
+    )
+
+    threshold = config["thresholds"]["epic"]
+    gate_result = "pass" if avg_local >= threshold and cascade.gate_result == "pass" else "fail"
+
+    scoring = build_active_scoring(
+        local_score=avg_local,
+        per_field={},
+        breakdown=breakdown,
+        cascade_floors=cascade_floors,
+        cascade_failures=cascade.cascade_failures,
+        gate_result=gate_result,
+        threshold=threshold,
+        per_entity_score=per_entity_score,
+    )
+
+    na_findings = [f for e in scoped_epics for f in validate_na_epic(e, config)]
+    coverage_findings = [
+        *validate_requirement_coverage(spec, scoped_epics, config),
+        *validate_nfr_coverage(spec, scoped_epics, config),
+    ]
+    all_local = [*na_findings, *coverage_findings]
+
+    passed = (
+        gate_result == "pass"
+        and not structural.invalid_fields
+        and not any(f.severity == "error" for f in structural.findings)
+        and not all_local
+    )
+
+    guidance = build_guidance(
+        spec, PhaseContext(phase="epic_expansion", config=config, active_entity_id=active_entity_id)
+    )
+
+    return ValidationResult(
+        phase="epic_expansion",
+        passed=passed,
+        structural=structural,
+        scoring=scoring,
+        cross_validation=CrossValidationResult(
+            skipped=False,
+            findings=all_local,
+            ran_checks=["na-validation", "requirement-coverage", "nfr-coverage"],
+            skipped_checks=[],
+        ),
+        guidance=guidance,
+        meta=build_meta(active_entity_id=active_entity_id),
+    )

crucible/api/phases/planning_spec.py

@@ -0,0 +1,82 @@
+"""planning_spec phase (port of ``api/phases/planning-spec.ts``).
+
+Guidance layer deferred (C7) — ``guidance`` is left unset.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...checks.na_validation import validate_na_spec
+from ...guidance.rubric import get_rubric_for_phase
+from ...scoring import (
+    CascadeGateInput,
+    compute_cascade_floors,
+    compute_entity_score,
+    compute_global_score,
+    evaluate_cascade_gate,
+)
+from ...structural import validate_structural
+from ...types.config import ValidatorConfig
+from ...types.context import PhaseContext
+from ...types.result import ValidationResult
+from ._common import build_active_scoring, build_guidance, build_meta, per_field_to_scores
+
+
+def validate_planning_spec(
+    spec: dict[str, Any], active_entity_id: str | list[str] | None, config: ValidatorConfig
+) -> ValidationResult:
+    structural = validate_structural(spec, config, "planning_spec")
+
+    spec_entries = [
+        e for e in get_rubric_for_phase("planning_spec") if e.field_path.startswith("specification.")
+    ]
+    entity_score = compute_entity_score(spec, spec_entries, config)
+
+    breakdown = compute_global_score(spec, config["scoring"]["weights"], config)
+    cascade_floors = compute_cascade_floors(config)
+    cascade = evaluate_cascade_gate(
+        CascadeGateInput(
+            global_score=breakdown.global_score,
+            spec_block=breakdown.spec_block,
+            epic_block=breakdown.epic_block,
+            phase="planning_spec",
+            floors=cascade_floors,
+        )
+    )
+
+    threshold = config["thresholds"]["specification"]
+    gate_result = (
+        "pass" if entity_score.local_score >= threshold and cascade.gate_result == "pass" else "fail"
+    )
+
+    scoring = build_active_scoring(
+        local_score=entity_score.local_score,
+        per_field=per_field_to_scores(entity_score.per_field),
+        breakdown=breakdown,
+        cascade_floors=cascade_floors,
+        cascade_failures=cascade.cascade_failures,
+        gate_result=gate_result,
+        threshold=threshold,
+    )
+
+    na_findings = validate_na_spec(spec, config)
+    passed = (
+        gate_result == "pass"
+        and not structural.invalid_fields
+        and not any(f.severity == "error" for f in structural.findings)
+        and not na_findings
+    )
+
+    guidance = build_guidance(
+        spec, PhaseContext(phase="planning_spec", config=config, active_entity_id=active_entity_id)
+    )
+
+    return ValidationResult(
+        phase="planning_spec",
+        passed=passed,
+        structural=structural,
+        scoring=scoring,
+        guidance=guidance,
+        meta=build_meta(active_entity_id=active_entity_id),
+    )