devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/llm_primitives.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Literal
+
+PrimitiveName = Literal["idea", "story"]
+
+
+@dataclass(frozen=True)
+class LlmInputPrimitive:
+    name: PrimitiveName
+    purpose: str
+    use_when: list[str]
+    do_not_use_when: list[str]
+    required_fields: list[str]
+    optional_fields: list[str]
+    construction: list[str]
+    processing: list[str]
+    output_contract: list[str]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "purpose": self.purpose,
+            "use_when": self.use_when,
+            "do_not_use_when": self.do_not_use_when,
+            "required_fields": self.required_fields,
+            "optional_fields": self.optional_fields,
+            "construction": self.construction,
+            "processing": self.processing,
+            "output_contract": self.output_contract,
+        }
+
+
+IDEA_PRIMITIVE = LlmInputPrimitive(
+    name="idea",
+    purpose=(
+        "Capture product or workflow intent before it becomes executable story work. "
+        "An idea is planning truth, not an implementation ticket."
+    ),
+    use_when=[
+        "The request introduces a new capability, workflow, product surface, or meaningful behavior area.",
+        "The user is still shaping outcomes, users, constraints, scope, or acceptance boundaries.",
+        "Success depends on deciding what should exist before deciding exactly what to change.",
+    ],
+    do_not_use_when=[
+        "The user asks for a bounded fix or small change to an existing surface; use story.",
+        "The user only asks for explanation, diagnosis, status, or repo inspection; answer directly.",
+        "The request is non-software work or has no DevFlow delivery implication.",
+    ],
+    required_fields=[
+        "idea_id: stable identifier for the idea artifact",
+        "problem: what user/business pain should become true or stop happening",
+        "target_users: concrete users/operators affected by the change",
+        "user_outcomes: observable outcomes those users need",
+        "scope: included and excluded behavior boundaries",
+    ],
+    optional_fields=[
+        "constraints: business, compliance, security, timeline, stack, or repo constraints",
+        "assumptions: explicit assumptions used to keep momentum when details are thin",
+        "source_refs: repo paths, source-doc paths, tickets, screenshots, transcripts, or notes",
+        "candidate_planes: delivery planes likely affected, such as api, ui, integrations, ops, auth",
+    ],
+    construction=[
+        "Prefer grounded assumptions over form-style questioning when the missing detail is agent-owned approach.",
+        (
+            "Ask only for user-owned truth: business outcome, UX intent, risk boundary, "
+            "approval rule, or domain constraint."
+        ),
+        "Keep the idea artifact stable enough that source docs and story generation can consume it later.",
+        "Record uncertainty as assumptions instead of hiding it in prose.",
+    ],
+    processing=[
+        "Normalize the user request into the required fields.",
+        "Evaluate whether the artifact is sufficient for downstream story creation.",
+        "If sufficient, persist or update the idea artifact under .devflow/ideas/<idea_id>/idea.json.",
+        "If not sufficient, return the smallest useful question and preserve the partial artifact.",
+        "When approved for delivery, feed the idea into the idea-to-story pipeline.",
+    ],
+    output_contract=[
+        "status: ready_for_story_generation | needs_clarification | not_applicable",
+        "idea: normalized idea payload",
+        "assumptions: explicit assumptions used",
+        "next_action: run_start | ask_user | answer_directly",
+    ],
+)
+
+
+STORY_PRIMITIVE = LlmInputPrimitive(
+    name="story",
+    purpose=(
+        "Describe one bounded executable change against an existing or approved target. "
+        "A story is implementation input with verification expectations."
+    ),
+    use_when=[
+        "The request is a concrete fix, small behavior change, or narrow improvement on an existing surface.",
+        "An approved idea has been decomposed into a delivery-sized unit.",
+        "The work can be verified with a scoped test, repro, acceptance check, or artifact review.",
+    ],
+    do_not_use_when=[
+        "The request still needs broad product/workflow shaping; use idea.",
+        "The user only wants read-only diagnosis or explanation; answer directly.",
+        "The change is too broad to validate as one bounded implementation unit.",
+    ],
+    required_fields=[
+        "story_id: stable identifier for queueing and execution",
+        "title: concise implementation-facing title",
+        "intent: what must change and why",
+        "scope: exact included and excluded work",
+        "acceptance_criteria: observable checks that define done",
+        "verification: tests, repro steps, commands, or review artifacts to prove completion",
+    ],
+    optional_fields=[
+        "source_idea_id: idea this story came from",
+        "plane_oracles: plane-specific verification anchors",
+        "repo_refs: paths, symbols, commands, logs, or screenshots grounding the change",
+        "risk_notes: security, compliance, migration, data, or ops risks",
+    ],
+    construction=[
+        "Keep one story to one delivery-sized change; split unrelated or multi-surface work.",
+        "State success as behavior and evidence, not as vague completion prose.",
+        "Include enough repo/source context for an implementation worker to start without reopening product planning.",
+        "Preserve ownership boundaries: the story defines target behavior; implementation chooses the local code path.",
+    ],
+    processing=[
+        "Validate the story contract and plane coverage.",
+        "Queue or execute the story through the implementation DAG.",
+        "Run the implementation stages through red, green, refactor, security, and commit gates as configured.",
+        "Record verification evidence and mark implemented only when the acceptance checks pass.",
+        "If blocked or too broad, return a blocker or promote back to idea instead of pretending completion.",
+    ],
+    output_contract=[
+        "status: ready_for_implementation | needs_more_story_context | promote_to_idea | not_applicable",
+        "story: normalized story payload",
+        "verification_plan: concrete proof path",
+        "next_action: run_start | ask_user | promote_to_idea | answer_directly",
+    ],
+)
+
+
+PRIMITIVES: dict[PrimitiveName, LlmInputPrimitive] = {
+    "idea": IDEA_PRIMITIVE,
+    "story": STORY_PRIMITIVE,
+}
+
+
+def render_llm_primitive_guidance(
+    primitive: PrimitiveName | Literal["all"] = "all",
+    *,
+    json_out: bool = False,
+) -> str:
+    selected = list(PRIMITIVES.values()) if primitive == "all" else [PRIMITIVES[primitive]]
+    if json_out:
+        payload = {
+            "version": "v0.02",
+            "agent_command_surface": _agent_command_surface(),
+            "input_primitives": [item.as_dict() for item in selected],
+        }
+        return json.dumps(payload, indent=2, sort_keys=True) + "\n"
+
+    blocks = [
+        "DevFlow LLM input primitives v0.02",
+        "",
+        "## Agent command surface",
+        (
+            "Use this small public surface from an agentic harness. Treat lower-level DAG, queue, "
+            "integration, review, eval, and worker debugging commands as internal unless the user "
+            "is explicitly debugging DevFlow itself."
+        ),
+        "",
+        "Project:",
+        "- devflow project add --path <repo> --name <name> --json",
+        "- devflow project remove <project_id> --yes",
+        "- devflow project status --project <project> --json",
+        "",
+        "Inputs:",
+        "- devflow idea submit --project <project> --from <idea.json> --json",
+        "- devflow story submit --project <project> --from <story.json> --json",
+        "",
+        "Run control:",
+        "- devflow run start --project <project> --json",
+        "- devflow run status --project <project> --json",
+        "- devflow run health --project <project> --json",
+        "- devflow doctor --project <project> --json",
+        "",
+        "Failure triage and repair target surface:",
+        "- devflow recovery run --project <project> --json",
+        "- devflow error solve --project <project> --json",
+        "- devflow error solve --project <project> --repro-command '<cmd>' --json",
+        "",
+        "Command doctrine:",
+        "- Submit idea when the work still needs product/workflow shaping.",
+        "- Submit story when the work is already a bounded implementation unit.",
+        "- After a ready submit, use run start and poll run health/status until idle, stuck, or ready.",
+        "- When run health reports a stuck or failed state, run doctor before attempting repair.",
+        "- Recovery owns DevFlow state repair; error solving owns project-code repair.",
+        (
+            "- Do not call internal queue/DAG commands for normal delivery; the run drain owns "
+            "implementation, integration, E2E follow-up, and preview planning."
+        ),
+        "",
+    ]
+    for item in selected:
+        blocks.extend(
+            [
+                f"## {item.name}",
+                item.purpose,
+                "",
+                "Use when:",
+                *[f"- {line}" for line in item.use_when],
+                "",
+                "Do not use when:",
+                *[f"- {line}" for line in item.do_not_use_when],
+                "",
+                "Required fields:",
+                *[f"- {line}" for line in item.required_fields],
+                "",
+                "Optional fields:",
+                *[f"- {line}" for line in item.optional_fields],
+                "",
+                "Construction rules:",
+                *[f"- {line}" for line in item.construction],
+                "",
+                "Processing flow:",
+                *[f"- {line}" for line in item.processing],
+                "",
+                "Output contract:",
+                *[f"- {line}" for line in item.output_contract],
+                "",
+            ]
+        )
+    return "\n".join(blocks).rstrip() + "\n"
+
+
+def _agent_command_surface() -> dict[str, object]:
+    return {
+        "public_commands": [
+            {
+                "command": "devflow project add --path <repo> --name <name> --json",
+                "use_when": "Register a repo/project and run knowledge bootstrap.",
+                "returns": ["status", "project_id", "repo_root", "next_action"],
+            },
+            {
+                "command": "devflow project remove <project_id> --yes",
+                "use_when": "Remove a project registration when the user explicitly asks.",
+                "returns": ["ok or non-zero failure"],
+            },
+            {
+                "command": "devflow project status --project <project> --json",
+                "use_when": "Inspect registration, queue, worker, and health state for a project.",
+                "returns": ["status", "next_action", "queues", "worker"],
+            },
+            {
+                "command": "devflow idea submit --project <project> --from <idea.json> --json",
+                "use_when": "Submit a planning-level idea primitive.",
+                "returns": ["status", "idea_id", "idea_queue_id", "issues", "next_action"],
+            },
+            {
+                "command": "devflow story submit --project <project> --from <story.json> --json",
+                "use_when": "Submit a bounded implementation story primitive.",
+                "returns": ["status", "story_id", "story_queue_id", "next_action"],
+            },
+            {
+                "command": "devflow run start --project <project> --json",
+                "use_when": "Drain the full delivery workflow after a ready submit.",
+                "returns": ["processed_count", "processed", "stopped_reason", "report"],
+            },
+            {
+                "command": "devflow run status --project <project> --json",
+                "use_when": "Inspect run position and queue state.",
+                "returns": ["status", "next_action", "queued_total", "active_failures", "queues", "worker"],
+            },
+            {
+                "command": "devflow run health --project <project> --json",
+                "use_when": "Poll compact health from an agent harness.",
+                "returns": ["status", "next_action", "active_failures", "worker_status"],
+            },
+            {
+                "command": "devflow doctor --project <project> --json",
+                "use_when": "Triage a stuck or failed run before choosing recovery or error solving.",
+                "returns": [
+                    "classification",
+                    "system_findings",
+                    "project_findings",
+                    "recommended_next_command",
+                    "handoff_lane",
+                ],
+            },
+            {
+                "command": "devflow recovery run --project <project> --json",
+                "use_when": "Repair DevFlow queue, worker, run, or artifact state after doctor routes to recovery.",
+                "returns": ["outcome", "artifacts", "next_action"],
+            },
+            {
+                "command": "devflow error solve --project <project> --json",
+                "use_when": "Repair project-code failures after doctor routes to error solving. Add --repro-command when a deterministic repro is known.",
+                "returns": ["outcome", "error_task_id", "artifacts", "next_action"],
+            },
+        ],
+        "internal_by_default": [
+            "worker",
+            "integration",
+            "source-scope",
+            "source-docs",
+            "ui-grounding",
+            "review",
+            "impl",
+            "registry",
+            "play",
+            "preflight",
+            "idea drafts",
+            "idea stories",
+        ],
+    }

devflow_engine/orchestration.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from .stores.execution_store import ExecutionStore
+
+TaskHandler = Callable[[ExecutionStore, Path, dict[str, Any]], dict[str, Any]]
+
+
+@dataclass(frozen=True)
+class WorkerTickResult:
+    worker_id: str
+    queue_name: str
+    task: dict[str, Any] | None
+    outcome: dict[str, Any] | None
+
+
+def process_one_task(
+    *,
+    store: ExecutionStore,
+    repo_root: Path,
+    queue_name: str,
+    worker_id: str,
+    handlers: dict[str, TaskHandler],
+    lease_seconds: int = 900,
+) -> WorkerTickResult:
+    task = store.claim_next_task(queue_name=queue_name, worker_id=worker_id, lease_seconds=lease_seconds)
+    if task is None:
+        return WorkerTickResult(worker_id=worker_id, queue_name=queue_name, task=None, outcome=None)
+
+    lease_token = str(task.get("lease_token") or "")
+    task_id = str(task["task_id"])
+    task_kind = str(task["task_kind"])
+    handler = handlers.get(task_kind)
+    if handler is None:
+        outcome = store.complete_task(
+            task_id=task_id,
+            lease_token=lease_token,
+            status="dead_letter",
+            error=f"no handler registered for task_kind={task_kind}",
+            result={"task_kind": task_kind},
+        )
+        return WorkerTickResult(worker_id=worker_id, queue_name=queue_name, task=task, outcome=outcome)
+
+    store.record_task_step(task_id=task_id, step_name="claim", status="leased", payload={"worker_id": worker_id})
+    try:
+        result = handler(store, repo_root, task)
+        store.record_task_step(task_id=task_id, step_name="complete", status="completed", payload=result)
+        outcome = store.complete_task(task_id=task_id, lease_token=lease_token, status="completed", result=result)
+        return WorkerTickResult(worker_id=worker_id, queue_name=queue_name, task=task, outcome=outcome)
+    except Exception as exc:
+        store.record_task_step(task_id=task_id, step_name="complete", status="failed", payload={"error": str(exc)})
+        outcome = store.complete_task(
+            task_id=task_id,
+            lease_token=lease_token,
+            status="failed",
+            error=str(exc),
+            result={"error": str(exc)},
+        )
+        raise

devflow_engine/planning/analyze_repo.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..story.markdown_contracts import ALLOWED_PLANES
+
+
+@dataclass(frozen=True)
+class RepoSignal:
+    path: str
+    kind: str
+
+
+def collect_repo_signals(repo_root: Path, *, max_files: int = 500) -> list[RepoSignal]:
+    signals: list[RepoSignal] = []
+    count = 0
+    for p in sorted(repo_root.rglob("*")):
+        if count >= max_files:
+            break
+        if "/.git/" in p.as_posix() or p.name.startswith(".venv"):
+            continue
+        if p.is_dir():
+            continue
+        rel = p.relative_to(repo_root).as_posix()
+        kind = "file"
+        if rel.endswith("pyproject.toml"):
+            kind = "pyproject"
+        elif rel.endswith(".py"):
+            kind = "python"
+        elif rel.endswith(".md"):
+            kind = "docs"
+        elif rel.endswith(".sql"):
+            kind = "sql"
+        signals.append(RepoSignal(path=rel, kind=kind))
+        count += 1
+    return signals
+
+
+def draft_user_stories(repo_root: Path) -> list[dict]:
+    """Produce *draft* story skeletons.
+
+    Drafts are not canonical contracts; they are generated from repo signals and should be
+    reviewed/edited into canonical markdown contracts under ai_docs/context/v2/....
+
+    This returns a dict payload that the CLI can serialize to markdown.
+    """
+
+    signals = collect_repo_signals(repo_root)
+    top_kinds = {s.kind for s in signals}
+
+    # Minimal heuristic: propose one baseline story with evidence anchors taken from repo.
+    evidence = sorted({s.path for s in signals if s.kind in {"pyproject", "python", "docs"}})[:10]
+
+    stories: list[dict] = []
+
+    def mk(story_id: str, title: str) -> dict:
+        required_planes = [p for p in ALLOWED_PLANES if p in {"api", "ops", "integrations", "auth", "ui"}]
+        # default: api+ops for code repos
+        if "python" in top_kinds or "pyproject" in top_kinds:
+            required_planes = ["api", "ops"]
+        if "docs" in top_kinds:
+            required_planes = sorted(set(required_planes + ["ui"]))
+
+        plane_oracles = [
+            {
+                "plane": "ops",
+                "oracle": "Green gate passes (tests + typecheck + lint)",
+                "anchor": "command:devflow impl gate",
+            },
+            {
+                "plane": "api",
+                "oracle": "Primary app entrypoint runs and exposes expected endpoints",
+                "anchor": f"evidence:{evidence[0] if evidence else 'repo'}",
+            },
+        ]
+        plane_oracles = [po for po in plane_oracles if po["plane"] in required_planes]
+
+        return {
+            "story_id": story_id,
+            "title": title,
+            "required_planes": required_planes,
+            "evidence_anchors": evidence,
+            "plane_oracles": plane_oracles,
+        }
+
+    stories.append(mk("STORY:devflow:planner:baseline", "Establish baseline DevFlow v2 story contracts"))
+
+    if "python" in top_kinds:
+        stories.append(mk("STORY:devflow:planner:python", "Python repo: validate tests/typecheck/lint pipeline"))
+
+    return stories

devflow_engine/planning/render_drafts.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from ..story.markdown_contracts import MANDATORY_CONTRACT_FORMATION_MODE_LINE
+
+
+def _as_list(value: Any) -> list[str]:
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if isinstance(value, list):
+        items: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                text = item.strip()
+                if text:
+                    items.append(text)
+        return items
+    return []
+
+
+def render_draft_story_markdown(draft: dict[str, Any]) -> str:
+    """Render a *draft* story skeleton as markdown.
+
+    Drafts are intended to be copied/edited into canonical story contracts.
+    """
+
+    story_uuid = str(draft.get("story_uuid") or uuid.uuid4())
+    story_id = str(draft.get("story_id") or "STORY:todo:todo:todo")
+    title = str(draft.get("title") or "TODO")
+    required_planes = draft.get("required_planes") or []
+    rp = ", ".join(required_planes)
+
+    plane_oracles = draft.get("plane_oracles") or []
+    evidence = draft.get("evidence_anchors") or []
+    story_statement = str(draft.get("story_statement") or "As a ... I want ... so that ...")
+    outcome_oracle = _as_list(draft.get("outcome_oracle")) or ["TODO"]
+    preconditions = _as_list(draft.get("preconditions")) or ["TODO"]
+    steps = _as_list(draft.get("steps")) or ["TODO"]
+    pass_conditions = _as_list(draft.get("pass_conditions")) or ["TODO"]
+    fail_conditions = _as_list(draft.get("fail_conditions")) or ["TODO"]
+    acceptance_criteria = _as_list(draft.get("acceptance_criteria")) or ["MUST ...", "MUST NOT ..."]
+    non_goals = _as_list(draft.get("non_goals")) or ["..."]
+    contract_test_spec = _as_list(draft.get("contract_test_spec")) or ["Given ...", "When ...", "Then ..."]
+
+    draft_story_id = str(draft.get("draft_story_id") or f"draft_{story_uuid}")
+    plane = str(draft.get("plane") or "")
+    source_analysis_id = str(draft.get("source_analysis_id") or "")
+
+    lines: list[str] = []
+
+    # Locked header block for tooling (must be preserved by editors/agents).
+    lines.append("DEVFLOW:LOCKED_START")
+    lines.append(f"draft_story_id: {draft_story_id}")
+    if plane:
+        lines.append(f"plane: {plane}")
+    if source_analysis_id:
+        lines.append(f"source_analysis_id: {source_analysis_id}")
+    # Include at least one evidence anchor line when available.
+    for a in evidence[:5]:
+        lines.append(f"anchor: {a}")
+    lines.append("DEVFLOW:LOCKED_END")
+    lines.append("")
+
+    lines.append(f"# {title}")
+    lines.append("")
+    lines.append(f"story_uuid: {story_uuid}")
+    lines.append(f"story_id: {story_id}")
+    lines.append(f"title: {title}")
+    lines.append(f"required_planes: [{rp}]")
+    lines.append("")
+    lines.append(MANDATORY_CONTRACT_FORMATION_MODE_LINE)
+    lines.append("")
+
+    lines.append("plane_oracles:")
+    for po in plane_oracles:
+        lines.append(f"- plane: {po.get('plane','')}")
+        lines.append(f"  oracle: \"{po.get('oracle','')}\"")
+        lines.append(f"  anchor: \"{po.get('anchor','')}\"")
+        lines.append("")
+
+    if evidence:
+        lines.append("## Evidence anchors (repo signals)")
+        for e in evidence:
+            lines.append(f"- {e}")
+        lines.append("")
+
+    lines.append("## Story statement")
+    lines.append(story_statement)
+    lines.append("")
+
+    lines.append("## Outcome oracle (user-observable)")
+    for item in outcome_oracle:
+        lines.append(f"- {item}")
+    lines.append("")
+
+    lines.append("## Preconditions")
+    for item in preconditions:
+        lines.append(f"- {item}")
+    lines.append("")
+
+    lines.append("## Steps")
+    for index, item in enumerate(steps, start=1):
+        lines.append(f"{index}. {item}")
+    lines.append("")
+
+    lines.append("## Pass/fail conditions")
+    lines.append("Pass:")
+    for item in pass_conditions:
+        lines.append(f"- {item}")
+    lines.append("Fail:")
+    for item in fail_conditions:
+        lines.append(f"- {item}")
+    lines.append("")
+
+    lines.append("## Acceptance criteria")
+    for index, item in enumerate(acceptance_criteria, start=1):
+        lines.append(f"{index}. {item}")
+    lines.append("")
+
+    lines.append("## Non-goals")
+    for item in non_goals:
+        lines.append(f"- {item}")
+    lines.append("")
+
+    lines.append("## Contract test spec (Given/When/Then)")
+    for item in contract_test_spec:
+        lines.append(f"- {item}")
+    lines.append("")
+
+    return "\n".join(lines)

devflow_engine/playground/hooks.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class PreflightResult:
+    ok: bool
+    message: str
+
+
+def preflight(repo_root: Path) -> PreflightResult:
+    # Minimal: verify .devflow exists.
+    df = repo_root / ".devflow"
+    if not df.exists():
+        return PreflightResult(
+            ok=False,
+            message=".devflow not initialized. Run `devflow project init`.",
+        )
+    return PreflightResult(ok=True, message="ok")
+
+
+def run_scenario(_name: str) -> None:
+    # Placeholder hook for future integration.
+    return

devflow_engine/playwright_workflow/__init__.py

@@ -0,0 +1,5 @@
+"""Post-integration Playwright workflow artifacts."""
+
+from .dag import PostIntegrationPlaywrightDagResult, run_post_integration_playwright_dag
+
+__all__ = ["PostIntegrationPlaywrightDagResult", "run_post_integration_playwright_dag"]