devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/story/contracts.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .markdown_contracts import (
+    ALLOWED_PLANES,
+    MANDATORY_CONTRACT_FORMATION_MODE_LINE,
+    ParsedStoryBlock,
+    StoryContract,
+    is_uuid4,
+)
+
+
+@dataclass(frozen=True)
+class ContractIssue:
+    code: str
+    message: str
+    path: str
+
+
+def validate_story_contract(contract: StoryContract, *, start_line: int = 1) -> list[ContractIssue]:
+    issues: list[ContractIssue] = []
+
+    if not contract.story_uuid:
+        issues.append(
+            ContractIssue(
+                "missing_story_uuid",
+                "Story contract must include story_uuid",
+                f"{contract.source_path}:{start_line}:story_uuid",
+            )
+        )
+    elif not is_uuid4(contract.story_uuid):
+        issues.append(
+            ContractIssue(
+                "invalid_story_uuid",
+                "story_uuid must be a uuid-v4 string",
+                f"{contract.source_path}:{start_line}:story_uuid",
+            )
+        )
+
+    if not contract.story_id:
+        issues.append(
+            ContractIssue(
+                "missing_story_id",
+                "Story contract must include story_id",
+                f"{contract.source_path}:{start_line}:story_id",
+            )
+        )
+
+    if not contract.title:
+        issues.append(
+            ContractIssue(
+                "missing_title",
+                "Story contract must include title",
+                f"{contract.source_path}:{start_line}:title",
+            )
+        )
+
+    if not contract.required_planes:
+        issues.append(
+            ContractIssue(
+                "missing_required_planes",
+                "Story contract must include required_planes",
+                f"{contract.source_path}:{start_line}:required_planes",
+            )
+        )
+    else:
+        invalid = [p for p in contract.required_planes if p not in ALLOWED_PLANES]
+        if invalid:
+            issues.append(
+                ContractIssue(
+                    "invalid_required_planes",
+                    f"required_planes contains invalid plane(s): {invalid}; allowed={ALLOWED_PLANES}",
+                    f"{contract.source_path}:{start_line}:required_planes",
+                )
+            )
+
+    if not contract.contract_formation_mode_line_present:
+        issues.append(
+            ContractIssue(
+                "missing_contract_formation_mode",
+                f"Story must include mandatory line: {MANDATORY_CONTRACT_FORMATION_MODE_LINE}",
+                f"{contract.source_path}:{start_line}",
+            )
+        )
+
+    if not contract.plane_oracles:
+        issues.append(
+            ContractIssue(
+                "missing_plane_oracles",
+                "Story must include plane_oracles list block",
+                f"{contract.source_path}:{start_line}:plane_oracles",
+            )
+        )
+        return issues
+
+    # Validate one entry per required plane
+    seen: dict[str, int] = {}
+    for idx, po in enumerate(contract.plane_oracles):
+        if not po.plane:
+            issues.append(
+                ContractIssue(
+                    "invalid_plane_oracle_plane",
+                    "plane_oracles item missing plane",
+                    f"{contract.source_path}:{start_line}:plane_oracles[{idx}].plane",
+                )
+            )
+            continue
+        seen[po.plane] = seen.get(po.plane, 0) + 1
+        if not po.oracle:
+            issues.append(
+                ContractIssue(
+                    "invalid_plane_oracle_oracle",
+                    "plane_oracles item missing oracle",
+                    f"{contract.source_path}:{start_line}:plane_oracles[{idx}].oracle",
+                )
+            )
+        if not po.anchor:
+            issues.append(
+                ContractIssue(
+                    "invalid_plane_oracle_anchor",
+                    "plane_oracles item missing anchor",
+                    f"{contract.source_path}:{start_line}:plane_oracles[{idx}].anchor",
+                )
+            )
+
+    missing = [p for p in contract.required_planes if seen.get(p, 0) == 0]
+    dupes = [p for p, n in seen.items() if n > 1]
+    extra = [p for p in seen if p not in contract.required_planes]
+
+    if missing:
+        issues.append(
+            ContractIssue(
+                "missing_plane_oracles_for_required_planes",
+                f"Missing plane_oracles entries for required_planes: {missing}",
+                f"{contract.source_path}:{start_line}:plane_oracles",
+            )
+        )
+    if dupes:
+        issues.append(
+            ContractIssue(
+                "duplicate_plane_oracles",
+                f"Duplicate plane_oracles entries for plane(s): {dupes}",
+                f"{contract.source_path}:{start_line}:plane_oracles",
+            )
+        )
+    if extra:
+        issues.append(
+            ContractIssue(
+                "extra_plane_oracles",
+                f"plane_oracles contains plane(s) not in required_planes: {extra}",
+                f"{contract.source_path}:{start_line}:plane_oracles",
+            )
+        )
+
+    return issues
+
+
+def validate_parsed_story_block(block: ParsedStoryBlock) -> list[ContractIssue]:
+    return validate_story_contract(block.contract, start_line=block.start_line)

devflow_engine/story/discovery.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+LEGACY_CANONICAL_STORY_PATH = Path("ai_docs/context/v2/project_docs/user_stories.md")
+CANONICAL_STORY_SOURCES_DIR_PATH = Path("ai_docs/context/v2/project_docs/user_stories")
+GENERATED_STORY_SOURCES_DIR_PATH = CANONICAL_STORY_SOURCES_DIR_PATH / "generated"
+RECONCILED_STORY_DOC_PATH = GENERATED_STORY_SOURCES_DIR_PATH / "_reconciled_story_queue.md"
+
+def _iter_story_markdown_paths(stories_dir: Path) -> list[Path]:
+    return sorted(
+        [p for p in stories_dir.rglob("*.md") if "/.git/" not in p.as_posix()],
+        key=lambda p: p.as_posix(),
+    )
+
+
+def canonical_story_reconciliation_doc_path(repo_root: Path) -> Path:
+    repo_root = Path(repo_root)
+    legacy = repo_root / LEGACY_CANONICAL_STORY_PATH
+    if legacy.exists():
+        return legacy
+    return repo_root / RECONCILED_STORY_DOC_PATH
+
+
+def canonical_story_generated_dir(repo_root: Path) -> Path:
+    return Path(repo_root) / GENERATED_STORY_SOURCES_DIR_PATH
+
+
+def get_story_source_paths(repo_root: Path) -> list[Path]:
+    """Return deterministic story source paths from the current canonical tree.
+
+    Current truth is the markdown set under ``ai_docs/context/v2/project_docs/user_stories/``.
+    ``user_stories.md`` is retained as a legacy compatibility source when it exists.
+    """
+
+    repo_root = Path(repo_root)
+    legacy = repo_root / LEGACY_CANONICAL_STORY_PATH
+    stories_dir = repo_root / CANONICAL_STORY_SOURCES_DIR_PATH
+    paths = _iter_story_markdown_paths(stories_dir) if stories_dir.exists() else []
+
+    if legacy.exists():
+        return [legacy, *paths]
+    if paths:
+        return paths
+
+    raise FileNotFoundError(f"{stories_dir} (or legacy {legacy})")

devflow_engine/story/evidence.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from ..llm.execution_context import get_execution_context
+
+
+def safe_story_id(story_id: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]+", "_", str(story_id or "").strip()) or "unknown_story"
+
+
+def story_dir(*, repo_root: Path, story_id: str) -> Path:
+    return _story_state_root(repo_root=repo_root) / safe_story_id(story_id)
+
+
+def _story_state_root(*, repo_root: Path) -> Path:
+    ctx = get_execution_context() or {}
+    override = str(ctx.get("devflow_story_state_root") or "").strip()
+    if override:
+        return Path(override)
+    return repo_root / ".devflow" / "stories"
+
+
+def story_verification_path(*, repo_root: Path, story_id: str) -> Path:
+    return story_dir(repo_root=repo_root, story_id=story_id) / "verification.json"
+
+
+def _load_json_if_exists(path: Path) -> dict[str, Any] | None:
+    if not path.exists() or not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def load_story_verification(*, repo_root: Path, story_id: str) -> dict[str, Any] | None:
+    return _load_json_if_exists(story_verification_path(repo_root=repo_root, story_id=story_id))
+
+
+def persist_story_verification(*, repo_root: Path, story_id: str, payload: dict[str, Any]) -> Path:
+    path = story_verification_path(repo_root=repo_root, story_id=story_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def record_story_verification(
+    *,
+    repo_root: Path,
+    story_id: str,
+    story_uuid: str | None = None,
+    source: str,
+    test_paths: list[str] | None = None,
+    validator: dict[str, Any] | None = None,
+    tests: dict[str, Any] | None = None,
+) -> tuple[dict[str, Any], Path]:
+    current = load_story_verification(repo_root=repo_root, story_id=story_id) or {}
+    canonical_test_paths = [
+        str(path).strip() for path in (test_paths or current.get("canonical_test_paths") or []) if str(path).strip()
+    ]
+    latest_result = {
+        "source": str(source or "").strip() or "unknown",
+        "story_id": story_id,
+        "story_uuid": str(story_uuid or current.get("story_uuid") or "").strip() or None,
+        "canonical_test_paths": canonical_test_paths,
+        "validator": dict(validator or {}),
+        "tests": dict(tests or {}),
+    }
+    passed = bool(latest_result["validator"].get("ok")) and bool(latest_result["tests"].get("ok"))
+    latest_result["passed"] = passed
+
+    payload: dict[str, Any] = {
+        "schema_version": 1,
+        "story_id": story_id,
+        "story_uuid": latest_result["story_uuid"],
+        "canonical_test_paths": canonical_test_paths,
+        "latest_result": latest_result,
+        "latest_passing_verification": current.get("latest_passing_verification"),
+    }
+    if passed:
+        payload["latest_passing_verification"] = latest_result
+    path = persist_story_verification(repo_root=repo_root, story_id=story_id, payload=payload)
+    return payload, path
+
+
+def resolve_story_verification_state(*, repo_root: Path, story_id: str) -> dict[str, Any]:
+    from ..implementation.test_runtime import load_story_test_runtime_contract, story_test_runtime_contract_path
+
+    runtime_contract = load_story_test_runtime_contract(repo_root=repo_root, story_id=story_id) or {}
+    verification = load_story_verification(repo_root=repo_root, story_id=story_id) or {}
+    canonical_test_paths = [
+        str(path).strip()
+        for path in (
+            runtime_contract.get("test_paths")
+            or verification.get("canonical_test_paths")
+            or ((verification.get("latest_result") or {}).get("canonical_test_paths"))
+            or []
+        )
+        if str(path).strip()
+    ]
+    latest_passing_verification = verification.get("latest_passing_verification")
+    return {
+        "story_id": story_id,
+        "runtime_contract_path": str(story_test_runtime_contract_path(repo_root=repo_root, story_id=story_id)),
+        "verification_path": str(story_verification_path(repo_root=repo_root, story_id=story_id)),
+        "has_runtime_contract": bool(runtime_contract),
+        "has_canonical_test_paths": bool(canonical_test_paths),
+        "canonical_test_paths": canonical_test_paths,
+        "has_verification_evidence": bool(verification),
+        "latest_result": dict(verification.get("latest_result") or {}) if isinstance(verification.get("latest_result"), dict) else None,
+        "has_latest_passing_verification": isinstance(latest_passing_verification, dict) and bool(latest_passing_verification),
+        "latest_passing_verification": dict(latest_passing_verification or {}) if isinstance(latest_passing_verification, dict) else None,
+    }

devflow_engine/story/hashing.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import hashlib
+
+
+def normalize_for_contract_hash(text: str) -> str:
+    """Normalize story markdown for stable contract hashing.
+
+    Policy (tests/spec):
+    - Remove UTF-8 BOM if present
+    - Normalize newlines to '\n'
+    - Trim trailing whitespace per line
+    - Ensure exactly one trailing newline
+    """
+
+    if text.startswith("\ufeff"):
+        text = text.lstrip("\ufeff")
+
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+
+    lines = [ln.rstrip() for ln in text.split("\n")]
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def compute_contract_hash(text: str) -> str:
+    normalized = normalize_for_contract_hash(text)
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()

devflow_engine/story/implemented_queue_purge.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from ..devflow_state import fetch_story_statuses_from_supabase
+from ..stores.execution_store import ExecutionStore
+
+ACTIVE_STORY_QUEUE_STATUSES = ("queued", "claimed", "in_progress", "blocked")
+PURGE_NOTE = "story queue completed locally because Supabase already marks the story implemented"
+
+
+def _load_active_story_queue_rows(store: ExecutionStore, *, project_id: str | None) -> list[dict[str, Any]]:
+    query = (
+        "SELECT story_queue_id, project_id, enqueue_run_id, story_artifact_id, story_id, title, status, "
+        "claimed_by_worker_id, claimed_at, started_run_id, finished_run_id, failure_message, failure_context_json, "
+        "created_at, updated_at "
+        "FROM story_queue WHERE status IN ('queued','claimed','in_progress','blocked')"
+    )
+    params: tuple[Any, ...] = ()
+    if project_id is not None:
+        query += " AND project_id=?"
+        params = (project_id,)
+    query += " ORDER BY created_at ASC, story_queue_id ASC"
+
+    with store._connect() as conn:
+        rows = conn.execute(query, params).fetchall()
+
+    payloads: list[dict[str, Any]] = []
+    for row in rows:
+        payload = dict(row)
+        try:
+            payload["failure_context"] = (
+                json.loads(str(payload.get("failure_context_json") or ""))
+                if payload.get("failure_context_json")
+                else None
+            )
+        except Exception:
+            payload["failure_context"] = None
+        payloads.append(payload)
+    return payloads
+
+
+def purge_implemented_story_queue(
+    *,
+    repo_root: Path,
+    project_id: str | None = None,
+    apply: bool = False,
+) -> dict[str, Any]:
+    repo_root = repo_root.expanduser().resolve()
+    store = ExecutionStore(repo_root / ".devflow" / "execution.sqlite")
+    queue_rows = _load_active_story_queue_rows(store, project_id=project_id)
+    story_ids = sorted(
+        {
+            str(row.get("story_id") or "").strip()
+            for row in queue_rows
+            if str(row.get("story_id") or "").strip()
+        }
+    )
+    supabase_status_by_story_id = fetch_story_statuses_from_supabase(story_ids=story_ids)
+
+    candidates: list[dict[str, Any]] = []
+    implemented_story_ids: set[str] = set()
+    for row in queue_rows:
+        story_id = str(row.get("story_id") or "").strip()
+        supabase_status = str(supabase_status_by_story_id.get(story_id) or "").strip().lower()
+        if supabase_status != "implemented":
+            continue
+        implemented_story_ids.add(story_id)
+        candidates.append(
+            {
+                "story_queue_id": str(row.get("story_queue_id") or ""),
+                "project_id": str(row.get("project_id") or ""),
+                "story_id": story_id,
+                "title": str(row.get("title") or ""),
+                "local_status_before": str(row.get("status") or ""),
+                "local_status_after": "completed",
+                "supabase_status": supabase_status,
+                "claimed_by_worker_id": row.get("claimed_by_worker_id"),
+                "claimed_at": row.get("claimed_at"),
+                "started_run_id": row.get("started_run_id"),
+                "finished_run_id": row.get("finished_run_id"),
+            }
+        )
+
+    applied_changes: list[dict[str, Any]] = []
+    if apply and candidates:
+        now = int(time.time())
+        touched_story_ids: set[str] = set()
+        with store._connect() as conn:
+            for row in queue_rows:
+                story_id = str(row.get("story_id") or "").strip()
+                if story_id not in implemented_story_ids:
+                    continue
+                story_queue_id = str(row.get("story_queue_id") or "")
+                failure_context = row.get("failure_context") if isinstance(row.get("failure_context"), dict) else {}
+                failure_context.update(
+                    {
+                        "suppressed_because_supabase_status": "implemented",
+                        "suppressed_from_active_execution_queue": True,
+                        "suppressed_at": now,
+                    }
+                )
+                cursor = conn.execute(
+                    (
+                        "UPDATE story_queue SET status='completed', claimed_by_worker_id=NULL, claimed_at=NULL, "
+                        "started_run_id=NULL, finished_run_id=NULL, "
+                        "failure_message=?, failure_context_json=?, updated_at=? "
+                        "WHERE story_queue_id=? AND status IN ('queued','claimed','in_progress','blocked')"
+                    ),
+                    (PURGE_NOTE, json.dumps(failure_context, sort_keys=True), now, story_queue_id),
+                )
+                if int(getattr(cursor, "rowcount", 0) or 0) <= 0:
+                    continue
+                touched_story_ids.add(story_id)
+                applied_changes.append(
+                    {
+                        "story_queue_id": story_queue_id,
+                        "story_id": story_id,
+                        "project_id": str(row.get("project_id") or ""),
+                        "title": str(row.get("title") or ""),
+                    }
+                )
+        for story_id in sorted(touched_story_ids):
+            store.update_story_status(story_id=story_id, status="implemented")
+
+    summary = {
+        "active_queue_rows_examined": len(queue_rows),
+        "active_story_ids_examined": len(story_ids),
+        "supabase_status_rows_found": len(supabase_status_by_story_id),
+        "implemented_story_ids_matched": len(implemented_story_ids),
+        "queue_rows_to_complete": len(candidates),
+        "queue_rows_completed": len(applied_changes),
+    }
+
+    return {
+        "repo_root": str(repo_root),
+        "db_path": str((repo_root / ".devflow" / "execution.sqlite").resolve()),
+        "project_id": project_id,
+        "apply": apply,
+        "summary": summary,
+        "candidates": candidates,
+        "applied_changes": applied_changes,
+        "supabase_status_by_story_id": supabase_status_by_story_id,
+        "note": PURGE_NOTE,
+    }

devflow_engine/story/indexer.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .discovery import get_story_source_paths
+from .hashing import compute_contract_hash
+from .markdown_contracts import ParsedStoryBlock, parse_story_contracts_from_markdown
+
+
+@dataclass(frozen=True)
+class StoryIndexEntry:
+    story_uuid: str
+    story_id: str
+    title: str
+    source_path: str
+    contract_hash: str
+
+
+@dataclass(frozen=True)
+class StoryIndex:
+    entries: list[StoryIndexEntry]
+
+    def to_json_bytes(self) -> bytes:
+        payload = {"entries": [asdict(e) for e in self.entries]}
+        # Deterministic serialization: sort keys + stable separators.
+        return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+            "utf-8"
+        )
+
+
+def _iter_story_blocks(repo_root: Path) -> list[ParsedStoryBlock]:
+    blocks: list[ParsedStoryBlock] = []
+    for p in get_story_source_paths(repo_root):
+        text = p.read_text(encoding="utf-8")
+        blocks.extend(parse_story_contracts_from_markdown(text, source_path=str(p)))
+    return blocks
+
+
+def build_story_index(repo_root: Path) -> StoryIndex:
+    """Build a deterministic story index from canonical + artifact sources.
+
+    Raises:
+        ValueError: on duplicate story_uuid across sources.
+    """
+
+    repo_root = Path(repo_root)
+    blocks = _iter_story_blocks(repo_root)
+
+    seen_uuid_to_path: dict[str, str] = {}
+    entries: list[StoryIndexEntry] = []
+
+    for b in blocks:
+        c = b.contract
+        if c.story_uuid in seen_uuid_to_path:
+            first = seen_uuid_to_path[c.story_uuid]
+            raise ValueError(
+                f"duplicate story_uuid {c.story_uuid} across sources: {first} and {c.source_path}"
+            )
+        if c.story_uuid:
+            seen_uuid_to_path[c.story_uuid] = c.source_path
+
+        entries.append(
+            StoryIndexEntry(
+                story_uuid=c.story_uuid,
+                story_id=c.story_id,
+                title=c.title,
+                source_path=c.source_path,
+                contract_hash=compute_contract_hash(c.raw_text),
+            )
+        )
+
+    # Deterministic ordering for downstream tools: sort by story_id then uuid.
+    entries_sorted = sorted(entries, key=lambda e: (e.story_id, e.story_uuid, e.source_path))
+    return StoryIndex(entries=entries_sorted)
+
+
+def persist_story_index(db_path: Path, index: StoryIndex) -> None:
+    db_path = Path(db_path)
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with sqlite3.connect(db_path) as conn:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS story_index (
+              story_uuid TEXT PRIMARY KEY,
+              story_id TEXT NOT NULL,
+              title TEXT NOT NULL,
+              source_path TEXT NOT NULL,
+              contract_hash TEXT NOT NULL
+            )
+            """
+        )
+        conn.execute("DELETE FROM story_index")
+
+        conn.executemany(
+            "INSERT INTO story_index (story_uuid, story_id, title, source_path, contract_hash) VALUES (?, ?, ?, ?, ?)",
+            [
+                (e.story_uuid, e.story_id, e.title, e.source_path, e.contract_hash)
+                for e in index.entries
+            ],
+        )
+        conn.commit()

devflow_engine/story/io.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"YAML at {path} must be a mapping")
+    return data
+
+
+def dump_yaml(path: Path, obj: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(obj, sort_keys=False, allow_unicode=True), encoding="utf-8")