devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/drafts.py

@@ -0,0 +1,446 @@
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..planning.render_drafts import render_draft_story_markdown
+from .paths import get_idea_paths
+from .sufficiency import extract_sufficient_idea
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class DraftSet:
+    draft_set_id: str
+    root: Path
+
+
+def _read_analysis(repo_root: Path, *, idea_id: str, analysis_id: str) -> dict:
+    paths = get_idea_paths(repo_root, idea_id=idea_id)
+    p = paths.analysis_root / analysis_id / "analysis.json"
+    if not p.exists():
+        return {
+            "analysis_id": analysis_id,
+            "idea_id": idea_id,
+            "repo_root": str(repo_root),
+            "created_at": _iso_now(),
+            "evidence": [],
+        }
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def _read_idea_payload(repo_root: Path, *, idea_id: str) -> dict:
+    idea_json = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+    if not idea_json.exists():
+        return {"idea_id": idea_id}
+    return json.loads(idea_json.read_text(encoding="utf-8"))
+
+
+def _read_raw_idea_text(repo_root: Path, *, idea_id: str) -> str:
+    candidate = repo_root / ".devflow" / f"{idea_id}.txt"
+    if not candidate.exists():
+        return ""
+    return candidate.read_text(encoding="utf-8").strip()
+
+
+def _safe_plane_list(planes: str | None) -> list[str]:
+    if not planes:
+        return ["api"]
+    items = [p.strip() for p in planes.split(",") if p.strip()]
+    return sorted(set(items)) or ["api"]
+
+
+def _dedupe(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for item in items:
+        text = item.strip()
+        if not text or text in seen:
+            continue
+        seen.add(text)
+        ordered.append(text)
+    return ordered
+
+
+def _split_bullet_prefix(text: str) -> str:
+    return re.sub(r"^\s*(?:[-*]|\d+\.)\s*", "", text).strip()
+
+
+def _parse_idea_sections(raw_text: str) -> dict[str, list[str]]:
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+
+    def normalize_heading(text: str) -> str:
+        lowered = re.sub(r"[^a-z0-9+]+", " ", text.lower()).strip()
+        if "primary users" in lowered:
+            return "target_users"
+        if lowered == "problem":
+            return "problem"
+        if lowered == "goal":
+            return "goal"
+        if lowered.startswith("scope"):
+            return "scope"
+        if "out of scope" in lowered:
+            return "out_of_scope"
+        if "constraint" in lowered or "non goals" in lowered:
+            return "constraints"
+        if "acceptance criteria" in lowered:
+            return "acceptance_criteria"
+        if "definition of done" in lowered or "good enough" in lowered:
+            return "definition_of_done"
+        return lowered.replace(" ", "_")
+
+    for raw_line in raw_text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.endswith(":") and not line.startswith(("-", "*")):
+            current = normalize_heading(line[:-1])
+            sections.setdefault(current, [])
+            continue
+        if current is None:
+            continue
+        sections.setdefault(current, []).append(_split_bullet_prefix(line))
+
+    return sections
+
+
+def _coerce_list(value: object) -> list[str]:
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return []
+
+
+def _idea_context(repo_root: Path, *, idea_id: str) -> dict[str, object]:
+    payload = _read_idea_payload(repo_root, idea_id=idea_id)
+    raw_text = _read_raw_idea_text(repo_root, idea_id=idea_id)
+    sections = _parse_idea_sections(raw_text)
+    extracted = extract_sufficient_idea(raw_text) if raw_text else {}
+    sufficient = payload.get("sufficient_idea") if isinstance(payload.get("sufficient_idea"), dict) else {}
+    combined = {**extracted, **sufficient}
+
+    target_users = _dedupe(_coerce_list(combined.get("target_users")) + sections.get("target_users", []))
+    scope = _dedupe(_coerce_list(combined.get("scope")) + sections.get("scope", []))
+    constraints = _dedupe(_coerce_list(combined.get("constraints")) + sections.get("constraints", []))
+    acceptance = _dedupe(_coerce_list(combined.get("acceptance_criteria")) + sections.get("acceptance_criteria", []))
+    out_of_scope = _dedupe(sections.get("out_of_scope", []))
+    done = _dedupe(sections.get("definition_of_done", []))
+    problem_parts = _coerce_list(combined.get("problem")) + sections.get("problem", [])
+    goal_parts = _coerce_list(combined.get("user_outcomes")) + sections.get("goal", [])
+
+    return {
+        "title": str(payload.get("title") or idea_id).strip(),
+        "raw_text": raw_text,
+        "target_users": target_users,
+        "problem": " ".join(problem_parts).strip(),
+        "goal": " ".join(goal_parts).strip(),
+        "scope": scope,
+        "constraints": constraints,
+        "acceptance_criteria": acceptance,
+        "out_of_scope": out_of_scope,
+        "definition_of_done": done,
+    }
+
+
+def _keyword_terms(context: dict[str, object]) -> list[str]:
+    source = " ".join(
+        [
+            str(context.get("title") or ""),
+            str(context.get("problem") or ""),
+            str(context.get("goal") or ""),
+            " ".join(_coerce_list(context.get("scope"))),
+            " ".join(_coerce_list(context.get("acceptance_criteria"))),
+        ]
+    ).lower()
+    if any(term in source for term in ("age verification", "18+", "adult", "age gate")):
+        return [
+            "age",
+            "verified",
+            "verification",
+            "adult",
+            "attestation",
+            "agegatepage",
+            "ageverifiedroute",
+            "age_gate",
+            "age-gate",
+            "ai gateway",
+            "content",
+            "profile",
+        ]
+    words = re.findall(r"[a-z0-9_]{4,}", source)
+    return _dedupe(words[:12])
+
+
+def _find_repo_signal_anchors(repo_root: Path, *, keywords: list[str], limit: int = 12) -> list[str]:
+    candidate_roots = [
+        repo_root / "src",
+        repo_root / "supabase",
+        repo_root / "ai_docs" / "context" / "project_docs",
+        repo_root / "README.md",
+    ]
+    allowed_suffixes = {".md", ".tsx", ".ts", ".js", ".jsx", ".py", ".sql", ".json", ".toml", ".yml", ".yaml"}
+    scored: list[tuple[int, str]] = []
+    repo_name = repo_root.name
+
+    for root in candidate_roots:
+        if not root.exists():
+            continue
+        paths = [root] if root.is_file() else sorted(root.rglob("*"))
+        for path in paths:
+            if not path.is_file() or path.suffix.lower() not in allowed_suffixes:
+                continue
+            rel = path.relative_to(repo_root).as_posix()
+            lower_rel = rel.lower()
+            score = sum(4 for keyword in keywords if keyword in lower_rel)
+            if score == 0:
+                try:
+                    sample = path.read_text(encoding="utf-8", errors="ignore")[:20000].lower()
+                except OSError:
+                    continue
+                score += sum(1 for keyword in keywords if keyword in sample)
+            if score <= 0:
+                continue
+            scored.append((score, f"fs:{repo_name}/{rel}"))
+
+    scored.sort(key=lambda item: (-item[0], item[1]))
+    return _dedupe([anchor for _, anchor in scored])[:limit]
+
+
+def _plane_anchor(plane: str, repo_anchors: list[str], analysis_anchors: list[str]) -> str:
+    plane_keywords = {
+        "auth": ["ageverifiedroute", "router", "route", "auth", "verified"],
+        "api": ["ai-gateway", "unlock-content", "select-content", "gateway", "supabase", "function", "sql"],
+        "ui": ["agegatepage", "age-gate", "page", "user_stories", "story"],
+        "integrations": ["outbox", "queue", "provider", "webhook"],
+        "ops": ["health", "doctor", "migration", "workflow"],
+    }.get(plane, [])
+    if plane_keywords:
+        scored = sorted(
+            repo_anchors,
+            key=lambda anchor: (
+                -sum(3 if keyword in anchor.lower() else 0 for keyword in plane_keywords),
+                anchor,
+            ),
+        )
+        if scored and any(keyword in scored[0].lower() for keyword in plane_keywords):
+            return scored[0]
+    if repo_anchors:
+        return repo_anchors[0]
+    return analysis_anchors[0] if analysis_anchors else ""
+
+
+def _plane_oracle(plane: str, title: str) -> str:
+    if "age verification" in title.lower():
+        if plane == "auth":
+            return "Authenticated but unverified users are redirected to /age-gate until the profile records completed age verification."
+        if plane == "api":
+            return "Restricted AI/content requests are denied until the profile stores age_verified, age_verified_at, and age_verification_method for the signed-in user."
+        if plane == "ui":
+            return "The signed-in user can complete a single 18+ self-attestation flow and then reach the previously blocked adult feature."
+    return f"{title}: the user-observable contract remains satisfied for the {plane} plane."
+
+
+def _build_draft_content(*, plane: str, context: dict[str, object]) -> dict[str, object]:
+    title = str(context.get("title") or "")
+    target_users = _coerce_list(context.get("target_users"))
+    role = target_users[1] if len(target_users) > 1 else (target_users[0] if target_users else "authenticated user")
+    problem = str(context.get("problem") or "the restricted experience is unsafe or incoherent without clear gating").strip()
+    goal = str(context.get("goal") or "complete the required flow and unlock the intended experience").strip()
+    acceptance = _coerce_list(context.get("acceptance_criteria"))
+    scope = _coerce_list(context.get("scope"))
+    out_of_scope = _coerce_list(context.get("out_of_scope"))
+    constraints = _coerce_list(context.get("constraints"))
+    done = _coerce_list(context.get("definition_of_done"))
+
+    if "age verification" in title.lower():
+        story_statement = (
+            f"As an {role}, I want to complete one 18+ self-attestation flow before entering restricted adult features, "
+            "so that adult AI and content access is unlocked only after verification is recorded."
+        )
+        outcome_oracle = [
+            "An authenticated but unverified user is blocked from a restricted adult feature and sent to /age-gate.",
+            "After the user confirms they are 18+, the profile stores age_verified, age_verified_at, and age_verification_method=self_attestation.",
+            "A verified user can retry the restricted feature without being forced through the gate again.",
+        ]
+        preconditions = [
+            "The user is signed in.",
+            "The user's profile is not yet age verified.",
+            "The requested route or request targets an adult-only Joyride surface.",
+        ]
+        steps = [
+            "Attempt to open a restricted adult feature while signed in but still unverified.",
+            "Complete the 18+ self-attestation on /age-gate.",
+            "Return to the blocked feature or retry the protected request.",
+        ]
+        pass_conditions = [
+            "The user is redirected to /age-gate before reaching the restricted surface.",
+            "Verification is persisted once with age_verified, age_verified_at, and age_verification_method.",
+            "Server-side AI/content gateway checks allow the request only after verification is present.",
+        ]
+        fail_conditions = [
+            "An unverified user can reach an adult feature without the age gate.",
+            "The self-attestation flow completes but verification fields are missing from the profile.",
+            "Restricted AI or content requests succeed while the user is still unverified.",
+        ]
+        acceptance_criteria = acceptance or [
+            "MUST redirect an authenticated but unverified user who requests a restricted adult feature to /age-gate.",
+            "MUST persist age_verified, age_verified_at, and age_verification_method when the user completes self-attestation.",
+            "MUST allow a verified user to access the previously blocked adult feature without repeating the flow unnecessarily.",
+            "MUST deny restricted AI gateway and content gateway requests for unverified users.",
+            "MUST record enough verification metadata for auditability without collecting unnecessary sensitive data.",
+        ]
+        non_goals = out_of_scope or [
+            "Third-party age verification provider integration.",
+            "Document upload, KYC, or biometric verification.",
+            "Collecting more sensitive personal data than the MVP requires.",
+        ]
+        contract_test_spec = [
+            "Given an authenticated user with profile.age_verified=false and a restricted adult feature target.",
+            "When the user attempts the feature before verification.",
+            "Then the product redirects the user to /age-gate and denies the protected server-side request.",
+            "Given the same user completes the 18+ self-attestation flow once.",
+            "When the profile stores age_verified=true, age_verified_at, and age_verification_method=self_attestation.",
+            "Then the user can access the adult feature and the server-side gateways stop rejecting the verified request.",
+        ]
+        return {
+            "story_statement": story_statement,
+            "outcome_oracle": outcome_oracle,
+            "preconditions": preconditions,
+            "steps": steps,
+            "pass_conditions": pass_conditions,
+            "fail_conditions": fail_conditions,
+            "acceptance_criteria": acceptance_criteria,
+            "non_goals": non_goals,
+            "contract_test_spec": contract_test_spec,
+        }
+
+    story_statement = f"As a {role}, I want {goal.rstrip('.')}, so that {problem.rstrip('.')} is resolved through an observable user outcome."
+    acceptance_criteria = acceptance or [f"MUST deliver {scope[0]}." if scope else "MUST deliver the stated user outcome."]
+    non_goals = out_of_scope or constraints or ["Implementation details that are not user-observable."]
+    return {
+        "story_statement": story_statement,
+        "outcome_oracle": done or [goal],
+        "preconditions": [f"The actor is {role}."] + ([scope[0]] if scope else []),
+        "steps": ["Start from the user entry point.", "Complete the minimal happy path.", "Verify the promised outcome."],
+        "pass_conditions": done or acceptance_criteria[:2],
+        "fail_conditions": [f"The user still experiences {problem}."] if problem else ["The promised outcome is not observable."],
+        "acceptance_criteria": acceptance_criteria,
+        "non_goals": non_goals,
+        "contract_test_spec": [
+            f"Given {role} needs to achieve the promised outcome.",
+            "When the user completes the minimum supported flow.",
+            f"Then {goal or 'the expected outcome'} is observable without relying on internal implementation details.",
+        ],
+    }
+
+
+def generate_draft_set(
+    *,
+    repo_root: Path,
+    idea_id: str,
+    analysis_id: str,
+    planes: list[str],
+) -> DraftSet:
+    paths = get_idea_paths(repo_root, idea_id=idea_id)
+    paths.drafts_root.mkdir(parents=True, exist_ok=True)
+
+    draft_set_id = uuid.uuid4().hex[:12]
+    ds_root = paths.drafts_root / draft_set_id
+    ds_root.mkdir(parents=True, exist_ok=True)
+
+    analysis = _read_analysis(repo_root, idea_id=idea_id, analysis_id=analysis_id)
+    evidence = analysis.get("evidence") or []
+    analysis_anchors = [e.get("anchor") for e in evidence if isinstance(e, dict) and isinstance(e.get("anchor"), str)]
+    context = _idea_context(repo_root, idea_id=idea_id)
+    repo_anchors = _find_repo_signal_anchors(repo_root, keywords=_keyword_terms(context))
+    anchors = repo_anchors or analysis_anchors
+
+    draft_paths: list[str] = []
+    for plane in planes:
+        plane_dir = ds_root / plane
+        plane_dir.mkdir(parents=True, exist_ok=True)
+        plane_anchor = _plane_anchor(plane, repo_anchors, analysis_anchors)
+        draft_content = _build_draft_content(plane=plane, context=context)
+
+        draft_payload = {
+            "story_id": f"STORY:idea:{idea_id}:{plane}",
+            "title": f"{context['title']}: {plane} draft",
+            "required_planes": [plane],
+            "plane_oracles": [
+                {"plane": plane, "oracle": _plane_oracle(plane, str(context["title"])), "anchor": plane_anchor}
+            ],
+            "evidence_anchors": anchors[:10],
+            "draft_story_id": f"draft_{plane}_{draft_set_id}",
+            "source_analysis_id": analysis_id,
+            "plane": plane,
+            **draft_content,
+        }
+
+        md = render_draft_story_markdown(draft_payload)
+        out_path = plane_dir / f"draft_{plane}_001.md"
+        out_path.write_text(md, encoding="utf-8")
+        draft_paths.append(str(out_path.relative_to(repo_root)))
+
+    manifest = {
+        "draft_set_id": draft_set_id,
+        "idea_id": idea_id,
+        "source_analysis_id": analysis_id,
+        "created_at": _iso_now(),
+        "generator": "devflow-engine",
+        "planes": planes,
+        "draft_paths": draft_paths,
+    }
+    (ds_root / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
+
+    return DraftSet(draft_set_id=draft_set_id, root=ds_root)
+
+
+_LOCKED_START = "DEVFLOW:LOCKED_START"
+_LOCKED_END = "DEVFLOW:LOCKED_END"
+
+
+def parse_locked_header(text: str) -> dict[str, str]:
+    lines = [ln.rstrip("\n") for ln in text.splitlines()]
+    try:
+        i0 = lines.index(_LOCKED_START)
+        i1 = lines.index(_LOCKED_END)
+    except ValueError:
+        return {}
+    if i1 <= i0:
+        return {}
+    header = {}
+    for ln in lines[i0 + 1 : i1]:
+        if ":" not in ln:
+            continue
+        k, v = ln.split(":", 1)
+        header[k.strip()] = v.strip()
+    return header
+
+
+_DRAFT_NAME_RE = re.compile(r"^DRAFT-([A-Za-z]+)-(\d+)\.md$")
+
+
+def dest_filename_for_draft(draft_path: Path, *, header: dict[str, str]) -> str:
+    if (sid := header.get("story_id")):
+        # Safe canonical filename heuristic.
+        safe = sid.replace("/", "-").replace(":", "-")
+        return f"{safe}.md"
+
+    m = _DRAFT_NAME_RE.match(draft_path.name)
+    if m:
+        plane = m.group(1).upper()
+        num = m.group(2)
+        return f"DF2-IDEA-{plane}-{num}.md"
+
+    # Fallback: stable mapping based on filename.
+    return f"{draft_path.stem}.md"