devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/traditional_stories.py

@@ -0,0 +1,1257 @@
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib  # py3.11+
+except Exception:  # pragma: no cover
+    tomllib = None  # type: ignore
+
+from ..llm.cli_one_shot import run_one_shot
+from .actors import canonicalize_story_actor, load_actor_registry, normalize_actor_label, resolve_actor_entry, validate_canonical_actor_label
+from .paths import get_idea_paths
+
+
+MAX_COVERAGE_ATTEMPTS = 3
+MAX_DECOMPOSITION_ITERATIONS = 2
+MAX_JSON_REPAIR_ATTEMPTS = 1
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class TraditionalStorySet:
+    story_set_id: str
+    root: Path
+    story_paths: list[Path]
+    sufficiency_report: dict[str, Any]
+
+
+class TraditionalStoryInsufficiencyError(RuntimeError):
+    def __init__(self, *, root: Path, story_set_id: str, report_path: Path, report: dict[str, Any]) -> None:
+        self.root = root
+        self.story_set_id = story_set_id
+        self.report_path = report_path
+        self.report = report
+        findings = report.get("final_findings") or report.get("history", [{}])[-1].get("findings") or []
+        summary = "; ".join(str(item) for item in findings[:4]) or "traditional story set remained insufficient"
+        super().__init__(summary)
+
+
+class TraditionalStoryGenerationError(RuntimeError):
+    def __init__(self, *, root: Path, story_set_id: str, resume_cursor: dict[str, Any] | None, cause: Exception) -> None:
+        self.root = root
+        self.story_set_id = story_set_id
+        self.resume_cursor = resume_cursor
+        self.failure_context = {
+            'story_set_id': story_set_id,
+            'stories_dir': str(root),
+            'resume_cursor': resume_cursor,
+        }
+        super().__init__(str(cause))
+
+
+def _traditional_root(repo_root: Path, *, idea_id: str) -> Path:
+    return get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "traditional_user_stories"
+
+
+def _read_idea_payload(repo_root: Path, *, idea_id: str) -> dict[str, Any]:
+    idea_json = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+    return json.loads(idea_json.read_text(encoding="utf-8"))
+
+
+def _extract_sufficient_idea(payload: dict[str, Any]) -> dict[str, Any]:
+    candidates = [
+        payload.get("sufficient_idea"),
+        payload.get("ideation_output"),
+        payload.get("ideation_artifact"),
+    ]
+    for candidate in candidates:
+        if isinstance(candidate, dict):
+            if isinstance(candidate.get("sufficient_idea"), dict):
+                return dict(candidate["sufficient_idea"])
+            return dict(candidate)
+    return payload
+
+
+def _resolved_actor_entries(actor_registry: dict[str, Any]) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    for item in (actor_registry.get("resolved_actors") or actor_registry.get("actors") or []):
+        if not isinstance(item, dict):
+            continue
+        label = str(item.get("label") or "").strip()
+        actor_id = str(item.get("id") or "").strip()
+        if not label or not actor_id:
+            continue
+        entries.append({
+            "id": actor_id,
+            "label": label,
+            "kind": str(item.get("kind") or "human").strip() or "human",
+            "inherits_from": str(item.get("inherits_from") or "").strip() or None,
+            "description": str(item.get("description") or "").strip(),
+            "aliases": [str(alias).strip() for alias in (item.get("aliases") or []) if str(alias).strip()],
+        })
+    return entries
+
+
+def _resolved_actor_ids(actor_registry: dict[str, Any]) -> list[str]:
+    return [str(item.get("id") or "").strip() for item in _resolved_actor_entries(actor_registry)]
+
+
+def _primary_actor_contract(*, actor_registry: dict[str, Any], actor_id: str | None = None, actor_label: str | None = None, field_name: str = "primary actor") -> dict[str, Any]:
+    resolved = None
+    if actor_id:
+        for item in _resolved_actor_entries(actor_registry):
+            if str(item.get("id") or "").strip() == str(actor_id).strip():
+                resolved = item
+                break
+    if resolved is None and actor_label:
+        resolved = resolve_actor_entry(actor=str(actor_label), actor_registry=actor_registry)
+    if resolved is None:
+        allowed = ", ".join(f"{item['id']}:{item['label']}" for item in _resolved_actor_entries(actor_registry)) or "<none>"
+        raise RuntimeError(f"{field_name.title()} must resolve from the canonical actor registry. Allowed actors: {allowed}")
+    if actor_id and str(resolved.get("id") or "").strip() != str(actor_id).strip():
+        raise RuntimeError(f"{field_name.title()} id {actor_id!r} does not match canonical actor {resolved.get('id')!r}.")
+    if actor_label and str(resolved.get("label") or "").strip() != str(actor_label).strip():
+        raise RuntimeError(f"{field_name.title()} label {actor_label!r} does not match canonical actor label {resolved.get('label')!r}.")
+    return {
+        "id": str(resolved.get("id") or "").strip(),
+        "label": str(resolved.get("label") or "").strip(),
+        "kind": str(resolved.get("kind") or "human").strip() or "human",
+        "inherits_from": str(resolved.get("inherits_from") or "").strip() or None,
+    }
+
+
+def _normalize_list(value: object) -> 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:
+            text = str(item).strip()
+            if text:
+                items.append(text)
+        return items
+    return []
+
+
+def _required_fields(sufficient_idea: dict[str, Any]) -> list[str]:
+    missing: list[str] = []
+    if not _normalize_list(sufficient_idea.get("target_users")):
+        missing.append("target_users")
+    if not str(sufficient_idea.get("problem") or "").strip():
+        missing.append("problem")
+    if not _normalize_list(sufficient_idea.get("user_outcomes")):
+        missing.append("user_outcomes")
+    return missing
+
+
+def validate_sufficient_idea(sufficient_idea: dict[str, Any]) -> list[str]:
+    return _required_fields(sufficient_idea)
+
+
+def _stable_story_set_id(*, idea_id: str, sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any] | None = None) -> str:
+    payload = {
+        "idea_id": idea_id,
+        "sufficient_idea": sufficient_idea,
+        "coverage_requirements": coverage_requirements or {},
+        "story_generation_version": 2,
+    }
+    digest = hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
+    return f"trad_{digest[:12]}"
+
+
+def load_sufficient_idea(repo_root: Path, *, idea_id: str) -> tuple[dict[str, Any], dict[str, Any]]:
+    payload = _read_idea_payload(repo_root, idea_id=idea_id)
+    sufficient_idea = _extract_sufficient_idea(payload)
+    missing = validate_sufficient_idea(sufficient_idea)
+    if missing:
+        raise ValueError("Sufficient idea missing required fields: " + ", ".join(missing))
+    return payload, sufficient_idea
+
+
+def _global_devflow_dir() -> Path:
+    home = os.environ.get("DEVFLOW_HOME")
+    if home:
+        return Path(home) / ".devflow"
+    return Path.home() / ".devflow"
+
+
+def _read_toml(path: Path) -> dict[str, object]:
+    if tomllib is None or not path.exists():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except Exception:
+        # Fall back: if tomllib fails (e.g. Python dict-string format in tiers key),
+        # read the raw file, extract all scalar key=value pairs as-is, and separately
+        # parse the tiers key as a Python literal so tier config works.
+        data = {}
+        try:
+            import re
+            raw = path.read_text(encoding="utf-8")
+            # Extract tiers separately as a Python literal.
+            m = re.search(r"^tiers\s*=\s*(.+)$", raw, re.MULTILINE | re.DOTALL)
+            if m:
+                tiers_src = m.group(1).strip()
+                parsed = ast.literal_eval(tiers_src)
+                if isinstance(parsed, dict):
+                    data["tiers"] = parsed
+            # Extract all other scalar top-level key=value pairs directly.
+            for line in raw.splitlines():
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" not in line:
+                    continue
+                key, _, raw_val = line.partition("=")
+                key = key.strip()
+                if key in data or key == "tiers":
+                    continue
+                val = raw_val.strip()
+                # Parse scalar TOML values: "string", number, boolean, null.
+                if val in ("true", "false"):
+                    data[key] = val == "true"
+                elif val == "null":
+                    data[key] = None
+                elif val.startswith('"') and val.endswith('"'):
+                    data[key] = val[1:-1]
+                elif val.startswith("'") and val.endswith("'"):
+                    data[key] = val[1:-1]
+                else:
+                    try:
+                        data[key] = int(val)
+                    except ValueError:
+                        try:
+                            data[key] = float(val)
+                        except ValueError:
+                            pass
+        except Exception:
+            pass
+    return data if isinstance(data, dict) else {}
+
+
+
+
+def _agent_timeout_seconds() -> int:
+    raw = os.environ.get("DEVFLOW_IDEA_STORY_AGENT_TIMEOUT")
+    if not raw:
+        return 3600
+    try:
+        value = int(raw)
+    except ValueError:
+        return 3600
+    return value if value > 0 else 3600
+
+def _load_llm_cli_config() -> tuple[str, str]:
+    cfg = _read_toml(_global_devflow_dir() / "config.toml")
+    llm_mode = str(cfg.get("llm_mode") or "").strip().lower()
+    if llm_mode != "cli":
+        raise RuntimeError("LLM not configured for CLI mode. Run: devflow config llm-set-provider --mode cli --provider <...>")
+    base_cmd = str(cfg.get("llm_cli_base") or "").strip()
+    if not base_cmd:
+        raise RuntimeError("LLM CLI base command not set. Run: devflow config llm-set-provider ...")
+    delivery = str(cfg.get("llm_cli_delivery") or "argument").strip().lower()
+    return base_cmd, delivery
+
+
+def _extract_json(text: str) -> str | None:
+    if "```" in text:
+        parts = text.split("```")
+        for i in range(len(parts) - 1):
+            body = parts[i + 1]
+            body_lines = body.splitlines()
+            if body_lines and body_lines[0].strip().lower() in {"json", "javascript"}:
+                body = "\n".join(body_lines[1:])
+            body = body.strip()
+            if body.startswith("{") and body.endswith("}"):
+                return body
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        return text[start : end + 1]
+    return None
+
+
+def _json_attempt_artifact_path(*, root: Path | None, task: str, attempt: int) -> Path | None:
+    if root is None:
+        return None
+    safe_task = ''.join(ch if ch.isalnum() or ch in {'_', '-'} else '_' for ch in task).strip('_') or 'task'
+    agent_root = root / 'agent_runs'
+    agent_root.mkdir(parents=True, exist_ok=True)
+    return agent_root / f"{safe_task}_{attempt:03d}.json"
+
+
+def _write_agent_attempt_artifact(*, path: Path | None, prompt: dict[str, Any], base_cmd: str, delivery: str, stdout: str, stderr: str, ok: bool, parsed: dict[str, Any] | None = None, parse_error: str | None = None, repaired_from_attempt: int | None = None) -> None:
+    if path is None:
+        return
+    payload: dict[str, Any] = {'task': str(prompt.get('task') or ''), 'ok': ok, 'base_cmd': base_cmd, 'delivery': delivery, 'prompt': prompt, 'raw_stdout': stdout, 'raw_stderr': stderr}
+    if parsed is not None:
+        payload['parsed'] = parsed
+    if parse_error:
+        payload['parse_error'] = parse_error
+    if repaired_from_attempt is not None:
+        payload['repaired_from_attempt'] = repaired_from_attempt
+    _write_json(path, payload)
+
+
+def _repair_json_prompt(*, original_prompt: dict[str, Any], raw_stdout: str) -> dict[str, Any]:
+    return {
+        'task': f"repair_{str(original_prompt.get('task') or 'json_output')}",
+        'instructions': [
+            'Return JSON only. No markdown. No prose outside JSON.',
+            'Repair or extract the prior model output into one valid JSON object matching the original requested schema.',
+            'Do not add new semantics. Preserve the original meaning as closely as possible.',
+        ],
+        'original_prompt': original_prompt,
+        'raw_output_to_repair': raw_stdout,
+        'output_schema': original_prompt.get('output_schema') or {},
+    }
+
+
+def _parse_json_agent_output(*, stdout: str, task: str) -> dict[str, Any]:
+    raw_json = _extract_json(stdout)
+    if raw_json is None:
+        raise RuntimeError(f"Failed to locate JSON in agent output for task={task!r}.")
+    try:
+        parsed = json.loads(raw_json)
+    except Exception as exc:
+        raise RuntimeError(f"Failed to parse JSON from agent output for task={task!r}.") from exc
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"Agent output for task={task!r} must be a JSON object.")
+    return parsed
+
+
+def _call_json_agent(*, repo_root: Path, prompt: dict[str, Any], error_message: str, artifact_root: Path | None = None) -> dict[str, Any]:
+    base_cmd, delivery = _load_llm_cli_config()
+    task = str(prompt.get('task') or 'json_task')
+    result = run_one_shot(base_cmd=base_cmd, delivery=delivery, prompt=json.dumps(prompt, indent=2, sort_keys=True), cwd=repo_root, timeout_seconds=_agent_timeout_seconds())
+    attempt_path = _json_attempt_artifact_path(root=artifact_root, task=task, attempt=1)
+    if not result.ok:
+        _write_agent_attempt_artifact(path=attempt_path, prompt=prompt, base_cmd=base_cmd, delivery=delivery, stdout=result.stdout, stderr=result.stderr, ok=False, parse_error=result.stderr or result.stdout or error_message)
+        raise RuntimeError(result.stderr or result.stdout or error_message)
+    try:
+        parsed = _parse_json_agent_output(stdout=result.stdout, task=task)
+        _write_agent_attempt_artifact(path=attempt_path, prompt=prompt, base_cmd=base_cmd, delivery=delivery, stdout=result.stdout, stderr=result.stderr, ok=True, parsed=parsed)
+        return parsed
+    except RuntimeError as exc:
+        _write_agent_attempt_artifact(path=attempt_path, prompt=prompt, base_cmd=base_cmd, delivery=delivery, stdout=result.stdout, stderr=result.stderr, ok=False, parse_error=str(exc))
+        repair_error: RuntimeError = exc
+        for repair_attempt in range(1, MAX_JSON_REPAIR_ATTEMPTS + 1):
+            repair_prompt = _repair_json_prompt(original_prompt=prompt, raw_stdout=result.stdout)
+            repair_result = run_one_shot(base_cmd=base_cmd, delivery=delivery, prompt=json.dumps(repair_prompt, indent=2, sort_keys=True), cwd=repo_root, timeout_seconds=_agent_timeout_seconds())
+            repair_path = _json_attempt_artifact_path(root=artifact_root, task=task, attempt=repair_attempt + 1)
+            if not repair_result.ok:
+                _write_agent_attempt_artifact(path=repair_path, prompt=repair_prompt, base_cmd=base_cmd, delivery=delivery, stdout=repair_result.stdout, stderr=repair_result.stderr, ok=False, parse_error=repair_result.stderr or repair_result.stdout or error_message, repaired_from_attempt=1)
+                repair_error = RuntimeError(repair_result.stderr or repair_result.stdout or error_message)
+                continue
+            try:
+                repaired = _parse_json_agent_output(stdout=repair_result.stdout, task=task)
+                _write_agent_attempt_artifact(path=repair_path, prompt=repair_prompt, base_cmd=base_cmd, delivery=delivery, stdout=repair_result.stdout, stderr=repair_result.stderr, ok=True, parsed=repaired, repaired_from_attempt=1)
+                return repaired
+            except RuntimeError as inner_exc:
+                _write_agent_attempt_artifact(path=repair_path, prompt=repair_prompt, base_cmd=base_cmd, delivery=delivery, stdout=repair_result.stdout, stderr=repair_result.stderr, ok=False, parse_error=str(inner_exc), repaired_from_attempt=1)
+                repair_error = inner_exc
+        raise repair_error
+
+
+def _normalize_requirement(requirement: dict[str, Any], *, index: int, actor_registry: dict[str, Any] | None = None) -> dict[str, Any]:
+    category = str(requirement.get("category") or "coverage").strip() or "coverage"
+    requirement_id = str(requirement.get("requirement_id") or f"req_{index:03d}").strip() or f"req_{index:03d}"
+    actor_requirement_id = str(requirement.get("actor_requirement_id") or "").strip() or None
+    subject = str(requirement.get("subject") or "").strip()
+    actor_id = str(requirement.get("actor_id") or "").strip() or None
+    actor_label = str(requirement.get("actor_label") or "").strip() or None
+    if category == "actor" and actor_registry is not None and _resolved_actor_entries(actor_registry):
+        primary_actor = _primary_actor_contract(
+            actor_registry=actor_registry,
+            actor_id=actor_id,
+            actor_label=actor_label or subject,
+            field_name="coverage requirement actor",
+        )
+        actor_id = primary_actor["id"]
+        actor_label = primary_actor["label"]
+        subject = actor_label
+    return {
+        "requirement_id": requirement_id,
+        "category": category,
+        "actor_requirement_id": actor_requirement_id,
+        "actor_id": actor_id,
+        "actor_label": actor_label,
+        "subject": subject,
+        "requirement": str(requirement.get("requirement") or "").strip(),
+        "rationale": str(requirement.get("rationale") or "").strip(),
+    }
+
+
+def _coverage_requirements_prompt(*, idea_id: str, payload: dict[str, Any], sufficient_idea: dict[str, Any], actor_registry: dict[str, Any]) -> dict[str, Any]:
+    resolved_actor_catalog = [
+        {
+            "id": str(item.get("id") or "").strip(),
+            "label": str(item.get("label") or "").strip(),
+            "kind": str(item.get("kind") or "human").strip() or "human",
+            "inherits_from": str(item.get("inherits_from") or "").strip() or None,
+        }
+        for item in _resolved_actor_entries(actor_registry)
+    ]
+    return {
+        "task": "generate_traditional_story_coverage_requirements",
+        "idea_id": idea_id,
+        "idea_title": str(payload.get("title") or sufficient_idea.get("summary") or idea_id),
+        "sufficient_idea": sufficient_idea,
+        "actor_registry": actor_registry,
+        "resolved_actor_catalog": resolved_actor_catalog,
+        "instructions": [
+            "Return JSON only. No markdown. No prose outside JSON.",
+            "Generate the atomic coverage requirements that must be represented by the traditional user story set.",
+            "Every requirement must be specific, testable at the story-planning level, and traceable to the sufficient idea.",
+            "Decompose capability-first / process-first by default: prefer one requirement per distinct user-visible capability or workflow.",
+            "Do not clone the same requirement across multiple user types or actors when the capability, workflow, and acceptance remain materially the same.",
+            "Create actor-scoped requirements only when auth, permissions, approvals, data scope, or the workflow materially differs for that actor.",
+            "Use only actors from actor_registry.canonical_actors / actor_registry.actors when generating actor-scoped requirements." if _resolved_actor_entries(actor_registry) else "If no actor registry is defined yet, use singular canonical actor labels and avoid merged actor classes.",
+            f"Use only these resolved actor ids when actor_id is present: {_resolved_actor_ids(actor_registry)}" if _resolved_actor_entries(actor_registry) else "If actor_id is omitted, use a singular actor label only.",
+            "Canonical actor labels must name exactly one actor class. Never use slash-separated aliases, merged synonym labels, or hybrid names like employee/respondent or admin/operator.",
+            "When a requirement concerns a specific actor's distinct outcome, gate, or materially different flow, include actor_requirement_id pointing at that actor requirement.",
+            "Do not use heuristics or fallback behavior. Derive requirements directly from the sufficient idea and canonical actor registry.",
+        ],
+        "output_schema": {
+            "requirements": [
+                {
+                    "requirement_id": "string",
+                    "category": "actor|actor_outcome|actor_flow|actor_gate|cross_cutting",
+                    "actor_requirement_id": "string|null",
+                    "actor_id": "string|null",
+                    "actor_label": "string|null",
+                    "subject": "string",
+                    "requirement": "string",
+                    "rationale": "string",
+                }
+            ]
+        },
+    }
+
+
+def generate_story_coverage_requirements(*, repo_root: Path, idea_id: str, payload: dict[str, Any], sufficient_idea: dict[str, Any], actor_registry: dict[str, Any] | None = None) -> dict[str, Any]:
+    actor_registry = actor_registry or load_actor_registry(repo_root)
+    prompt = _coverage_requirements_prompt(
+        idea_id=idea_id,
+        payload=payload,
+        sufficient_idea=sufficient_idea,
+        actor_registry=actor_registry,
+    )
+    raw = _call_json_agent(repo_root=repo_root, prompt=prompt, error_message="story coverage requirements LLM command failed", artifact_root=get_idea_paths(repo_root, idea_id=idea_id).idea_dir)
+    requirements_raw = raw.get("requirements") if isinstance(raw.get("requirements"), list) else []
+    requirements = [_normalize_requirement(item, index=index, actor_registry=actor_registry) for index, item in enumerate(requirements_raw, start=1) if isinstance(item, dict)]
+    if not requirements:
+        raise RuntimeError("Coverage requirements agent returned no requirements.")
+    registry_actors = _resolved_actor_entries(actor_registry)
+    if registry_actors:
+        for requirement in requirements:
+            if str(requirement.get("category") or "") != "actor":
+                continue
+            primary_actor = _primary_actor_contract(
+                actor_registry=actor_registry,
+                actor_id=str(requirement.get("actor_id") or "").strip() or None,
+                actor_label=str(requirement.get("actor_label") or requirement.get("subject") or "").strip() or None,
+                field_name="coverage requirement actor",
+            )
+            requirement["actor_id"] = primary_actor["id"]
+            requirement["actor_label"] = primary_actor["label"]
+            if str(requirement.get("category") or "") == "actor":
+                requirement["subject"] = primary_actor["label"]
+    return {
+        "idea_id": idea_id,
+        "generated_at": _iso_now(),
+        "evaluation_mode": "agentic",
+        "requirements": requirements,
+    }
+
+
+def _validate_story_shape(story: dict[str, Any], *, index: int) -> list[str]:
+    findings: list[str] = []
+    required = ("title", "actor", "goal", "benefit", "user_value", "acceptance_criteria")
+    for field in required:
+        if field == "acceptance_criteria":
+            values = _normalize_list(story.get(field))
+            if len(values) < 2:
+                findings.append(f"story {index} needs at least two acceptance criteria")
+            continue
+        value = str(story.get(field) or "").strip()
+        if not value:
+            findings.append(f"story {index} missing {field}")
+        if value.lower() in {"placeholder", "todo", "tbd", "template"}:
+            findings.append(f"story {index} contains placeholder {field}")
+    return findings
+
+
+def _coverage_deficiency_prompt(*, sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any], stories: list[dict[str, Any]], pass_index: int) -> dict[str, Any]:
+    return {
+        "task": "evaluate_traditional_story_coverage_deficiencies",
+        "pass_index": pass_index,
+        "sufficient_idea": sufficient_idea,
+        "coverage_requirements": coverage_requirements,
+        "stories": stories,
+        "instructions": [
+            "Return JSON only. No markdown. No prose outside JSON.",
+            "Evaluate whether the traditional story set fully covers the atomic coverage requirements.",
+            "Judge coverage semantically, but report deficiencies only against the provided requirement IDs.",
+            "Maintain actor correctness, but do not require separate stories per actor when the same capability/workflow is shared.",
+            "Only flag actor-specific gaps when auth, permissions, approvals, routing, or other workflow behavior materially changes for that actor.",
+            "If coverage is insufficient, list the uncovered or weakly covered requirement IDs and concise findings.",
+            "Do not invent fallback requirements.",
+        ],
+        "output_schema": {
+            "passed": True,
+            "findings": ["string"],
+            "uncovered_requirement_ids": ["string"],
+            "weak_requirement_ids": ["string"],
+            "covered_requirement_ids": ["string"],
+            "deficiencies": [
+                {
+                    "requirement_id": "string",
+                    "severity": "missing|weak",
+                    "finding": "string",
+                }
+            ],
+        },
+    }
+
+
+def _build_actor_specificity_repair_plan(*, coverage_requirements: dict[str, Any], weak_requirement_ids: list[str]) -> list[dict[str, Any]]:
+    by_id = _requirements_by_id(coverage_requirements)
+    repairs: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for req_id in weak_requirement_ids:
+        requirement = by_id.get(str(req_id).strip()) or {}
+        actor_id = str(requirement.get("actor_id") or "").strip()
+        actor_label = str(requirement.get("actor_label") or requirement.get("subject") or "").strip()
+        if not actor_id and not actor_label:
+            continue
+        key = (actor_id, actor_label)
+        if key in seen:
+            continue
+        seen.add(key)
+        repairs.append({
+            "type": "clarify_actor_distinction",
+            "actor_id": actor_id or None,
+            "actor_label": actor_label or None,
+            "requirement_ids": [
+                rid for rid in weak_requirement_ids
+                if ((str((by_id.get(str(rid).strip()) or {}).get("actor_id") or "").strip() == actor_id) and actor_id)
+                or ((str((by_id.get(str(rid).strip()) or {}).get("actor_label") or (by_id.get(str(rid).strip()) or {}).get("subject") or "").strip() == actor_label) and actor_label)
+            ],
+            "instruction": (
+                f"Keep the shared capability-first story shape for {actor_label or actor_id} unless that actor has a materially different permission, approval, "
+                "or workflow branch. Prefer capturing the role distinction in acceptance criteria or story notes before splitting into a separate story."
+            ),
+        })
+    return repairs
+
+
+def evaluate_traditional_story_sufficiency(*, repo_root: Path, stories: list[dict[str, Any]], sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any], pass_index: int) -> dict[str, Any]:
+    findings: list[str] = []
+    if not stories:
+        findings.append("missing stories")
+        return {"passed": False, "findings": findings, "coverage": {"story_count": 0}, "evaluation_mode": "agentic"}
+
+    for index, story in enumerate(stories, start=1):
+        findings.extend(_validate_story_shape(story, index=index))
+    if findings:
+        return {"passed": False, "findings": findings, "coverage": {"story_count": len(stories)}, "evaluation_mode": "agentic"}
+
+    prompt = _coverage_deficiency_prompt(
+        sufficient_idea=sufficient_idea,
+        coverage_requirements=coverage_requirements,
+        stories=stories,
+        pass_index=pass_index,
+    )
+    evaluation = _call_json_agent(repo_root=repo_root, prompt=prompt, error_message="story coverage deficiency evaluator LLM command failed")
+    eval_findings = [str(item) for item in (evaluation.get("findings") or []) if str(item).strip()]
+    covered_requirement_ids = [str(item).strip() for item in (evaluation.get("covered_requirement_ids") or []) if str(item).strip()]
+    uncovered_requirement_ids = [str(item).strip() for item in (evaluation.get("uncovered_requirement_ids") or []) if str(item).strip()]
+    weak_requirement_ids = [str(item).strip() for item in (evaluation.get("weak_requirement_ids") or []) if str(item).strip()]
+    deficiencies = [
+        {
+            "requirement_id": str(item.get("requirement_id") or "").strip(),
+            "severity": str(item.get("severity") or "").strip(),
+            "finding": str(item.get("finding") or "").strip(),
+        }
+        for item in (evaluation.get("deficiencies") or [])
+        if isinstance(item, dict)
+    ]
+
+    actor_coverage_ids: set[str] = set()
+    for requirement in (coverage_requirements.get("requirements") or []):
+        if not isinstance(requirement, dict) or str(requirement.get("category") or "") != "actor":
+            continue
+        req_id = str(requirement.get("requirement_id") or "").strip()
+        req_actor_id = str(requirement.get("actor_id") or "").strip()
+        req_actor_label = str(requirement.get("actor_label") or requirement.get("subject") or "").strip()
+        for story in stories:
+            story_actor_id = str(story.get("actor_id") or "").strip()
+            story_actor = str(story.get("actor") or "").strip()
+            if req_actor_id and story_actor_id and req_actor_id == story_actor_id:
+                actor_coverage_ids.add(req_id)
+                break
+            if req_actor_label and story_actor and normalize_actor_label(req_actor_label) == normalize_actor_label(story_actor):
+                actor_coverage_ids.add(req_id)
+                break
+
+    for req_id in sorted(actor_coverage_ids):
+        if req_id and req_id not in covered_requirement_ids:
+            covered_requirement_ids.append(req_id)
+        if req_id in uncovered_requirement_ids:
+            uncovered_requirement_ids.remove(req_id)
+        if req_id in weak_requirement_ids:
+            weak_requirement_ids.remove(req_id)
+        deficiencies = [item for item in deficiencies if item.get("requirement_id") != req_id]
+        eval_findings = [item for item in eval_findings if req_id not in item]
+
+    weak_requirements = _select_requirement_subset(coverage_requirements=coverage_requirements, requirement_ids=weak_requirement_ids, limit=20)
+    actor_specificity_warning = bool(weak_requirement_ids) and not uncovered_requirement_ids
+    repair_plan = _build_actor_specificity_repair_plan(coverage_requirements=coverage_requirements, weak_requirement_ids=weak_requirement_ids)
+    coverage = {
+        "story_count": len(stories),
+        "requirement_count": len(coverage_requirements.get("requirements") or []),
+        "covered_requirement_ids": covered_requirement_ids,
+        "uncovered_requirement_ids": uncovered_requirement_ids,
+        "weak_requirement_ids": weak_requirement_ids,
+        "deficiencies": deficiencies,
+        "weak_requirements": weak_requirements,
+        "actor_specificity_warning": actor_specificity_warning,
+        "repair_plan": repair_plan,
+    }
+    passed = not coverage["uncovered_requirement_ids"]
+    if actor_specificity_warning:
+        eval_findings.append(
+            "Behavioral coverage is complete, but some actor-specific requirements remain weakly attributed; passing with actor-specificity warning and repair plan."
+        )
+    return {
+        "passed": passed,
+        "findings": eval_findings,
+        "coverage": coverage,
+        "evaluation_mode": "agentic",
+        "warnings": ["actor_specificity_weak"] if actor_specificity_warning else [],
+        "repair_plan": repair_plan,
+    }
+
+
+
+
+def _compact_requirement(requirement: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "requirement_id": str(requirement.get("requirement_id") or "").strip(),
+        "category": str(requirement.get("category") or "").strip(),
+        "actor_id": str(requirement.get("actor_id") or "").strip() or None,
+        "actor_label": str(requirement.get("actor_label") or "").strip() or None,
+        "subject": str(requirement.get("subject") or "").strip(),
+        "requirement": str(requirement.get("requirement") or "").strip(),
+    }
+
+
+def _compact_story(story: dict[str, Any]) -> dict[str, Any]:
+    ac = [str(item).strip() for item in (story.get("acceptance_criteria") or []) if str(item).strip()]
+    return {
+        "story_id": str(story.get("story_id") or story.get("id") or "").strip() or None,
+        "title": str(story.get("title") or "").strip(),
+        "actor_id": str(story.get("actor_id") or "").strip() or None,
+        "actor": str(story.get("actor") or "").strip(),
+        "goal": str(story.get("goal") or "").strip(),
+        "benefit": str(story.get("benefit") or "").strip(),
+        "coverage_tags": [str(item).strip() for item in (story.get("coverage_tags") or []) if str(item).strip()],
+        "acceptance_criteria": ac[:4],
+    }
+
+
+def _compact_sufficient_idea(sufficient_idea: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "summary": str(sufficient_idea.get("summary") or sufficient_idea.get("description") or "").strip(),
+        "target_users": [str(item).strip() for item in (sufficient_idea.get("target_users") or sufficient_idea.get("users") or []) if str(item).strip()],
+        "key_constraints": [str(item).strip() for item in (sufficient_idea.get("constraints") or []) if str(item).strip()][:10],
+    }
+
+
+def _requirements_by_id(coverage_requirements: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    return {str(item.get("requirement_id") or "").strip(): item for item in (coverage_requirements.get("requirements") or []) if isinstance(item, dict) and str(item.get("requirement_id") or "").strip()}
+
+
+def _select_requirement_subset(*, coverage_requirements: dict[str, Any], requirement_ids: list[str] | None = None, limit: int = 8) -> list[dict[str, Any]]:
+    reqs = [item for item in (coverage_requirements.get("requirements") or []) if isinstance(item, dict)]
+    if not requirement_ids:
+        return [_compact_requirement(item) for item in reqs[:limit]]
+    by_id = _requirements_by_id(coverage_requirements)
+    subset=[]
+    seen=set()
+    for req_id in requirement_ids:
+        rid=str(req_id).strip()
+        if rid and rid in by_id and rid not in seen:
+            subset.append(_compact_requirement(by_id[rid]))
+            seen.add(rid)
+    return subset[:limit]
+
+
+def _select_story_subset(*, stories: list[dict[str, Any]], titles: list[str] | None = None, limit: int = 6) -> list[dict[str, Any]]:
+    if not titles:
+        return [_compact_story(item) for item in stories[:limit]]
+    wanted={str(item).strip().lower() for item in titles if str(item).strip()}
+    subset=[]
+    for story in stories:
+        title=str(story.get("title") or "").strip()
+        if title.lower() in wanted:
+            subset.append(_compact_story(story))
+    if not subset:
+        subset=[_compact_story(item) for item in stories[:limit]]
+    return subset[:limit]
+
+def _decomposition_check_prompt(*, sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any], stories: list[dict[str, Any]], iteration: int) -> dict[str, Any]:
+    return {
+        "task": "evaluate_traditional_story_decomposition",
+        "iteration": iteration,
+        "sufficient_idea": sufficient_idea,
+        "coverage_requirements": coverage_requirements,
+        "stories": stories,
+        "instructions": [
+            "Return JSON only. No markdown. No prose outside JSON.",
+            "Evaluate whether the covered traditional story set is cleanly decomposed into atomic, non-overlapping user-visible stories.",
+            "Identify overlaps, duplicate coverage, assembly stories, and stories that are not independently meaningful.",
+            "Treat actor-first clones of the same underlying capability or workflow as overlap unless the actor changes permissions, approvals, or flow semantics in a material way.",
+            "Do not use heuristics or fallback behavior.",
+        ],
+        "output_schema": {
+            "passed": True,
+            "findings": ["string"],
+            "issues": [
+                {
+                    "story_title": "string",
+                    "issue": "string",
+                }
+            ],
+        },
+    }
+
+
+def _decomposition_refine_prompt(*, sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any], stories: list[dict[str, Any]], iteration: int, check_findings: list[str], check_issues: list[dict[str, str]]) -> dict[str, Any]:
+    return {
+        "task": "refine_traditional_story_decomposition",
+        "iteration": iteration,
+        "sufficient_idea": sufficient_idea,
+        "coverage_requirements": coverage_requirements,
+        "stories": stories,
+        "check_findings": check_findings,
+        "check_issues": check_issues,
+        "instructions": [
+            "Return JSON only. No markdown. No prose outside JSON.",
+            "Revise the story set to improve decomposition while preserving semantic coverage of the provided coverage requirements.",
+            "Merge overlapping stories when they represent the same user-visible outcome.",
+            "Collapse parallel actor-first clones into capability-first stories unless the actor changes permissions, approvals, routing, or flow semantics in a materially different way.",
+            "When multiple actors can perform the same capability, keep one primary actor and capture the other allowed actors or constraints in acceptance criteria.",
+            "Fold technical or infrastructure-only concerns into acceptance criteria on user-visible stories instead of keeping them as standalone stories.",
+            "Preserve actor specificity and requirement traceability.",
+            "Return the full revised story set, not a patch.",
+            "Do not use heuristics or fallback behavior.",
+        ],
+        "output_schema": {
+            "stories": [
+                {
+                    "title": "string",
+                    "actor_id": "string",
+                    "actor_id": "string",
+                    "actor": "string",
+                    "goal": "string",
+                    "benefit": "string",
+                    "user_value": "string",
+                    "acceptance_criteria": ["string", "string"],
+                    "coverage_tags": ["string"],
+                }
+            ],
+            "merge_log": [
+                {
+                    "action": "merge|drop|rewrite|retain",
+                    "story_title": "string",
+                    "reason": "string",
+                }
+            ],
+        },
+    }
+
+
+def _normalize_decomposition_check(check: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "passed": bool(check.get("passed")),
+        "findings": [str(item) for item in (check.get("findings") or []) if str(item).strip()],
+        "issues": [
+            {
+                "story_title": str(item.get("story_title") or "").strip(),
+                "issue": str(item.get("issue") or "").strip(),
+            }
+            for item in (check.get("issues") or [])
+            if isinstance(item, dict)
+        ],
+    }
+
+
+def _normalize_refine_payload(refined: dict[str, Any], revised_stories: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "merge_log": [
+            {
+                "action": str(item.get("action") or "").strip(),
+                "story_title": str(item.get("story_title") or "").strip(),
+                "reason": str(item.get("reason") or "").strip(),
+            }
+            for item in (refined.get("merge_log") or [])
+            if isinstance(item, dict)
+        ],
+        "stories": revised_stories,
+    }
+
+
+def _build_resume_cursor(*, story_set_id: str, iteration: int, phase: str, artifact_path: Path | None = None) -> dict[str, Any]:
+    payload: dict[str, Any] = {'kind': 'traditional_story_decomposition', 'story_set_id': story_set_id, 'iteration': iteration, 'phase': phase}
+    if artifact_path is not None:
+        payload['artifact'] = artifact_path.name
+    return payload
+
+
+def run_traditional_story_decomposition_loop(*, repo_root: Path, root: Path, stories: list[dict[str, Any]], sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any]) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    if not stories:
+        report = {
+            "passed": False, "approved": True, "hit_max_iterations": False, "approved_by_iteration_cap": False, "iteration_count": 0,
+            "findings": ["missing stories"], "issues": [], "history": [], "evaluation_mode": "agentic",
+            "resume_cursor": _build_resume_cursor(story_set_id=root.name, iteration=1, phase='check'),
+        }
+        return stories, report
+
+    current_stories = list(stories)
+    history: list[dict[str, Any]] = []
+    latest_check = {"passed": True, "findings": [], "issues": []}
+    resume_cursor: dict[str, Any] | None = None
+
+    for iteration in range(1, MAX_DECOMPOSITION_ITERATIONS + 1):
+        check_path = root / f"decomposition_check_{iteration:03d}.json"
+        refine_path = root / f"decomposition_refine_{iteration:03d}.json"
+        validate_path = root / f"decomposition_validate_{iteration:03d}.json"
+        iteration_payload: dict[str, Any] = {"iteration": iteration}
+
+        if check_path.exists():
+            normalized_check = json.loads(check_path.read_text(encoding='utf-8'))
+        else:
+            check_prompt = _decomposition_check_prompt(sufficient_idea=sufficient_idea, coverage_requirements=coverage_requirements, stories=current_stories, iteration=iteration)
+            check = _call_json_agent(repo_root=repo_root, prompt=check_prompt, error_message="story decomposition evaluator LLM command failed", artifact_root=root)
+            normalized_check = _normalize_decomposition_check(check)
+            _write_json(check_path, normalized_check)
+        latest_check = normalized_check
+        iteration_payload.update({"check": normalized_check, "check_artifact": check_path.name})
+        if normalized_check["passed"]:
+            history.append(iteration_payload)
+            resume_cursor = None
+            break
+
+        if refine_path.exists():
+            refine_payload = json.loads(refine_path.read_text(encoding='utf-8'))
+            revised_stories = list(refine_payload.get('stories') or [])
+        else:
+            refine_prompt = _decomposition_refine_prompt(sufficient_idea=sufficient_idea, coverage_requirements=coverage_requirements, stories=current_stories, iteration=iteration, check_findings=normalized_check["findings"], check_issues=normalized_check["issues"])
+            refined = _call_json_agent(repo_root=repo_root, prompt=refine_prompt, error_message="story decomposition refinement LLM command failed", artifact_root=root)
+            revised_stories = _call_story_agent(repo_root=repo_root, prompt=refine_prompt, artifact_root=root)
+            refine_payload = _normalize_refine_payload(refined, revised_stories)
+            _write_json(refine_path, refine_payload)
+
+        if validate_path.exists():
+            validate = json.loads(validate_path.read_text(encoding='utf-8'))
+        else:
+            validate = evaluate_traditional_story_sufficiency(repo_root=repo_root, stories=revised_stories, sufficient_idea=sufficient_idea, coverage_requirements=coverage_requirements, pass_index=MAX_COVERAGE_ATTEMPTS + iteration)
+            _write_json(validate_path, validate)
+
+        iteration_payload.update({"refine_artifact": refine_path.name, "validate_artifact": validate_path.name, "validation": validate})
+        history.append(iteration_payload)
+        current_stories = revised_stories
+        latest_check = {"passed": bool(validate.get("passed")), "findings": [str(item) for item in (validate.get("findings") or []) if str(item).strip()], "issues": normalized_check["issues"]}
+        resume_cursor = None if latest_check['passed'] else _build_resume_cursor(story_set_id=root.name, iteration=min(iteration + 1, MAX_DECOMPOSITION_ITERATIONS), phase='check', artifact_path=validate_path)
+
+    hit_max_iterations = not bool(latest_check.get("passed")) and len(history) >= MAX_DECOMPOSITION_ITERATIONS
+    report = {
+        "passed": bool(latest_check.get("passed")), "approved": True, "hit_max_iterations": hit_max_iterations, "approved_by_iteration_cap": hit_max_iterations,
+        "iteration_count": len(history), "findings": list(latest_check.get("findings") or []), "issues": list(latest_check.get("issues") or []),
+        "history": history, "evaluation_mode": "agentic", "resume_cursor": resume_cursor,
+    }
+    return current_stories, report
+
+
+def _resolved_actor_labels(actor_registry: dict[str, Any]) -> list[str]:
+    return [str(item.get("label") or "").strip() for item in _resolved_actor_entries(actor_registry)]
+
+
+def _lint_story_actor(*, actor: str, actor_registry: dict[str, Any]) -> str:
+    validate_canonical_actor_label(actor)
+    canonical_actor = canonicalize_story_actor(actor=actor, actor_registry=actor_registry)
+    if canonical_actor is None:
+        allowed = ", ".join(_resolved_actor_labels(actor_registry)) or "<none>"
+        raise RuntimeError(f"Story actor {actor!r} is not present in canonical actor registry. Allowed actors: {allowed}")
+    return canonical_actor
+
+
+def _story_prompt(*, idea_id: str, payload: dict[str, Any], sufficient_idea: dict[str, Any], coverage_requirements: dict[str, Any], actor_registry: dict[str, Any], pass_index: int, prior_stories: list[dict[str, Any]], current_findings: list[str], current_deficiencies: list[dict[str, Any]]) -> dict[str, Any]:
+    resolved_actor_labels = _resolved_actor_labels(actor_registry)
+    resolved_actor_catalog = [
+        {
+            "id": str(item.get("id") or "").strip(),
+            "label": str(item.get("label") or "").strip(),
+            "kind": str(item.get("kind") or "human").strip() or "human",
+            "inherits_from": str(item.get("inherits_from") or "").strip() or None,
+        }
+        for item in _resolved_actor_entries(actor_registry)
+    ]
+    return {
+        "task": "generate_traditional_user_stories",
+        "idea_id": idea_id,
+        "pass_index": pass_index,
+        "sufficient_idea": sufficient_idea,
+        "coverage_requirements": coverage_requirements,
+        "actor_registry": actor_registry,
+        "resolved_actor_catalog": resolved_actor_catalog,
+        "idea_title": str(payload.get("title") or sufficient_idea.get("summary") or idea_id),
+        "current_findings": current_findings,
+        "current_deficiencies": current_deficiencies,
+        "prior_stories": prior_stories,
+        "instructions": [
+            "Return JSON only. No markdown. No prose outside JSON.",
+            "Generate materially useful traditional user stories that satisfy every atomic coverage requirement.",
+            "Default to capability-first / process-first decomposition: organize stories around distinct user-visible capabilities or workflow steps.",
+            "Do not clone the same story across user types or actors when the capability, workflow, and outcome are materially the same.",
+            "Split stories by actor only when permissions, approvals, routing, data scope, or workflow behavior materially differs for that actor.",
+            f"Use only these resolved actor labels in the story actor field: {resolved_actor_labels}",
+            f"Use only these resolved actor ids in the story actor_id field: {_resolved_actor_ids(actor_registry)}",
+            "Every story must have exactly one primary actor from the resolved actor set for this run.",
+            "Canonical actor labels must name exactly one actor class. Never use slash-separated aliases, merged synonym labels, 'or'-joined labels, or hybrid names like employee/respondent or admin/operator.",
+            "If multiple roles are involved in the same shared capability, keep one representative primary actor in the story actor field and mention the other permitted roles or constraints only inside acceptance criteria.",
+            "Stay at the user-visible story level. Do not drift into implementation details.",
+            "When current_deficiencies is non-empty, revise the full story set to close those exact requirement gaps.",
+            "Do not use placeholder text.",
+        ],
+        "output_schema": {
+            "stories": [
+                {
+                    "title": "string",
+                    "actor_id": "string",
+                    "actor": "string",
+                    "goal": "string",
+                    "benefit": "string",
+                    "user_value": "string",
+                    "acceptance_criteria": ["string", "string"],
+                    "coverage_tags": ["string"],
+                }
+            ]
+        },
+    }
+
+
+def _call_story_agent(*, repo_root: Path, prompt: dict[str, Any], artifact_root: Path | None = None) -> list[dict[str, Any]]:
+    parsed = _call_json_agent(repo_root=repo_root, prompt=prompt, error_message="story generation LLM command failed", artifact_root=artifact_root)
+    stories = parsed.get("stories") if isinstance(parsed, dict) else None
+    if not isinstance(stories, list):
+        raise RuntimeError("LLM output missing stories[].")
+    actor_registry = prompt.get("actor_registry") if isinstance(prompt.get("actor_registry"), dict) else {}
+    registry_actors = list(actor_registry.get("canonical_actors") or actor_registry.get("actors") or [])
+    normalized: list[dict[str, Any]] = []
+    for story in stories:
+        if not isinstance(story, dict):
+            continue
+        actor = str(story.get("actor") or "").strip()
+        actor_id = str(story.get("actor_id") or "").strip() or None
+        if registry_actors:
+            primary_actor = _primary_actor_contract(actor_registry=actor_registry, actor_id=actor_id, actor_label=actor, field_name="story primary actor")
+            actor = primary_actor["label"]
+            actor_id = primary_actor["id"]
+        else:
+            validate_canonical_actor_label(actor)
+            primary_actor = {"id": actor_id or actor.lower().replace(" ", "_"), "label": actor, "kind": "human", "inherits_from": None}
+        normalized.append(
+            {
+                "title": str(story.get("title") or "").strip(),
+                "actor_id": actor_id,
+                "actor": actor,
+                "primary_actor": primary_actor,
+                "goal": str(story.get("goal") or "").strip(),
+                "benefit": str(story.get("benefit") or "").strip(),
+                "user_value": str(story.get("user_value") or "").strip(),
+                "acceptance_criteria": _normalize_list(story.get("acceptance_criteria")),
+                "coverage_tags": _normalize_list(story.get("coverage_tags")),
+            }
+        )
+    return normalized
+
+
+def _render_story_markdown(*, index: int, story: dict[str, Any]) -> str:
+    lines = [
+        f"# User Story {index}",
+        "",
+        f"**Title:** {story['title']}",
+        "",
+        f"As a {story['actor']},",
+        f"I want {story['goal'].rstrip('.')},",
+        f"so that {story['benefit'].rstrip('.')}",
+        "",
+        "## User Value",
+        story["user_value"],
+        "",
+        "## Acceptance Criteria",
+    ]
+    for idx, criterion in enumerate(_normalize_list(story.get("acceptance_criteria")), start=1):
+        lines.append(f"{idx}. {criterion.rstrip('.') }.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _clear_previous_story_files(root: Path) -> None:
+    for candidate in root.glob("US-*.md"):
+        candidate.unlink()
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _report_history_entry(*, pass_index: int, evaluation: dict[str, Any], stories: list[dict[str, Any]], attempt_path: Path) -> dict[str, Any]:
+    return {
+        "pass_index": pass_index,
+        "passed": bool(evaluation.get("passed")),
+        "findings": list(evaluation.get("findings") or []),
+        "coverage": dict(evaluation.get("coverage") or {}),
+        "story_count": len(stories),
+        "attempt_artifact": attempt_path.name,
+    }
+
+
+def generate_traditional_user_story_set(*, repo_root: Path, idea_id: str, max_stories: int | None = None, story_set_id: str | None = None, coverage_requirements: dict[str, Any] | None = None, actor_registry: dict[str, Any] | None = None) -> TraditionalStorySet:
+    del max_stories  # agentic story generation currently decides cardinality from coverage requirements.
+    payload, sufficient_idea = load_sufficient_idea(repo_root, idea_id=idea_id)
+    actor_registry = actor_registry or load_actor_registry(repo_root)
+    coverage_requirements = coverage_requirements or generate_story_coverage_requirements(
+        repo_root=repo_root,
+        idea_id=idea_id,
+        payload=payload,
+        sufficient_idea=sufficient_idea,
+        actor_registry=actor_registry,
+    )
+    resolved_story_set_id = story_set_id or _stable_story_set_id(
+        idea_id=idea_id,
+        sufficient_idea=sufficient_idea,
+        coverage_requirements=coverage_requirements,
+    )
+    root = _traditional_root(repo_root, idea_id=idea_id) / resolved_story_set_id
+    manifest_path = root / "manifest.json"
+    report_path = root / "sufficiency_report.json"
+
+    if manifest_path.exists():
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        story_paths = [repo_root / rel_path for rel_path in manifest.get("story_paths", [])]
+        report = json.loads(report_path.read_text(encoding="utf-8")) if report_path.exists() else dict(manifest.get("sufficiency") or {})
+        return TraditionalStorySet(story_set_id=resolved_story_set_id, root=root, story_paths=story_paths, sufficiency_report=report)
+
+    root.mkdir(parents=True, exist_ok=True)
+    coverage_requirements_path = root / "coverage_requirements.json"
+    _write_json(coverage_requirements_path, coverage_requirements)
+
+    resolved_actor_catalog = [
+        {
+            "id": str(item.get("id") or "").strip(),
+            "label": str(item.get("label") or "").strip(),
+            "kind": str(item.get("kind") or "human").strip() or "human",
+            "inherits_from": str(item.get("inherits_from") or "").strip() or None,
+        }
+        for item in _resolved_actor_entries(actor_registry)
+    ]
+    history: list[dict[str, Any]] = []
+    prior_stories: list[dict[str, Any]] = []
+    current_deficiencies: list[dict[str, Any]] = []
+    stories: list[dict[str, Any]] = []
+    evaluation: dict[str, Any] = {"passed": False, "findings": ["generation did not run"], "coverage": {}}
+
+    for pass_index in range(1, MAX_COVERAGE_ATTEMPTS + 1):
+        prompt = _story_prompt(
+            idea_id=idea_id,
+            payload=payload,
+            sufficient_idea=sufficient_idea,
+            coverage_requirements=coverage_requirements,
+            actor_registry=actor_registry,
+            pass_index=pass_index,
+            prior_stories=prior_stories,
+            current_findings=list(evaluation.get("findings") or []) if pass_index > 1 else [],
+            current_deficiencies=current_deficiencies,
+        )
+        stories = _call_story_agent(repo_root=repo_root, prompt=prompt, artifact_root=root)
+        evaluation = evaluate_traditional_story_sufficiency(
+            repo_root=repo_root,
+            stories=stories,
+            sufficient_idea=sufficient_idea,
+            coverage_requirements=coverage_requirements,
+            pass_index=pass_index,
+        )
+        attempt_payload = {
+            "pass_index": pass_index,
+            "prompt": prompt,
+            "stories": stories,
+            "coverage_evaluation": evaluation,
+        }
+        attempt_path = root / f"attempt_{pass_index:03d}.json"
+        _write_json(attempt_path, attempt_payload)
+        history.append(_report_history_entry(pass_index=pass_index, evaluation=evaluation, stories=stories, attempt_path=attempt_path))
+        current_deficiencies = list(evaluation.get("coverage", {}).get("deficiencies") or [])
+        prior_stories = stories
+        if evaluation.get("passed"):
+            break
+
+    try:
+        decomposed_stories, decomposition_report = run_traditional_story_decomposition_loop(
+            repo_root=repo_root,
+            root=root,
+            stories=stories,
+            sufficient_idea=sufficient_idea,
+            coverage_requirements=coverage_requirements,
+        )
+    except Exception as exc:
+        resume_cursor = _build_resume_cursor(story_set_id=resolved_story_set_id, iteration=1, phase='check')
+        for iteration in range(1, MAX_DECOMPOSITION_ITERATIONS + 1):
+            check_path = root / f"decomposition_check_{iteration:03d}.json"
+            refine_path = root / f"decomposition_refine_{iteration:03d}.json"
+            validate_path = root / f"decomposition_validate_{iteration:03d}.json"
+            if check_path.exists() and not refine_path.exists():
+                resume_cursor = _build_resume_cursor(story_set_id=resolved_story_set_id, iteration=iteration, phase='refine', artifact_path=check_path)
+                break
+            if refine_path.exists() and not validate_path.exists():
+                resume_cursor = _build_resume_cursor(story_set_id=resolved_story_set_id, iteration=iteration, phase='validate', artifact_path=refine_path)
+                break
+            if validate_path.exists():
+                resume_cursor = _build_resume_cursor(story_set_id=resolved_story_set_id, iteration=min(iteration + 1, MAX_DECOMPOSITION_ITERATIONS), phase='check', artifact_path=validate_path)
+        raise TraditionalStoryGenerationError(root=root, story_set_id=resolved_story_set_id, resume_cursor=resume_cursor, cause=exc) from exc
+    final_coverage_report = evaluate_traditional_story_sufficiency(
+        repo_root=repo_root,
+        stories=decomposed_stories,
+        sufficient_idea=sufficient_idea,
+        coverage_requirements=coverage_requirements,
+        pass_index=MAX_COVERAGE_ATTEMPTS + MAX_DECOMPOSITION_ITERATIONS + 1,
+    )
+    final_coverage_path = root / "final_coverage_validation.json"
+    decomposition_report_path = root / "decomposition_report.json"
+    _write_json(final_coverage_path, final_coverage_report)
+    _write_json(decomposition_report_path, decomposition_report)
+
+    passed = bool(evaluation.get("passed")) and bool(final_coverage_report.get("passed")) and bool(decomposition_report.get("passed"))
+    report = {
+        "story_set_id": resolved_story_set_id,
+        "idea_id": idea_id,
+        "created_at": _iso_now(),
+        "passed": passed,
+        "coverage_passed": bool(evaluation.get("passed")),
+        "final_coverage_passed": bool(final_coverage_report.get("passed")),
+        "decomposition_passed": bool(decomposition_report.get("passed")),
+        "approved": True,
+        "pass_count": len(history),
+        "history": history,
+        "coverage_requirements_path": coverage_requirements_path.name,
+        "decomposition_report_path": decomposition_report_path.name,
+        "final_coverage_validation_path": final_coverage_path.name,
+        "final_findings": list(evaluation.get("findings") or []) + list(decomposition_report.get("findings") or []) + list(final_coverage_report.get("findings") or []),
+        "final_coverage": dict(final_coverage_report.get("coverage") or {}),
+        "coverage_requirements": coverage_requirements,
+        "actor_registry": actor_registry,
+        "resolved_actor_catalog": resolved_actor_catalog,
+        "decomposition": decomposition_report,
+    }
+    _write_json(report_path, report)
+
+    _clear_previous_story_files(root)
+    story_paths: list[Path] = []
+    for index, story in enumerate(decomposed_stories, start=1):
+        out_path = root / f"US-{index:03d}.md"
+        out_path.write_text(_render_story_markdown(index=index, story=story), encoding="utf-8")
+        story_paths.append(out_path)
+
+    manifest = {
+        "story_set_id": resolved_story_set_id,
+        "idea_id": idea_id,
+        "kind": "traditional_user_stories",
+        "created_at": _iso_now(),
+        "source": "sufficient_idea",
+        "canonical_story_contract": False,
+        "traceability": {
+            "idea_id": idea_id,
+            "idea_artifact": str((get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json").relative_to(repo_root)),
+            "handoff": "promote_or_dag_to_canonical_devflow_story",
+        },
+        "coverage_requirements_path": str(coverage_requirements_path.relative_to(repo_root)),
+        "decomposition_report_path": str(decomposition_report_path.relative_to(repo_root)),
+        "story_paths": [str(path.relative_to(repo_root)) for path in story_paths],
+        "sufficiency": report,
+    }
+    _write_json(manifest_path, manifest)
+
+    report = {
+        "story_set_id": resolved_story_set_id,
+        "idea_id": idea_id,
+        "created_at": _iso_now(),
+        "passed": passed,
+        "coverage_passed": bool(evaluation.get("passed")),
+        "final_coverage_passed": bool(final_coverage_report.get("passed")),
+        "decomposition_passed": bool(decomposition_report.get("passed")),
+        "approved": True,
+        "pass_count": len(history),
+        "history": history,
+        "coverage_requirements_path": coverage_requirements_path.name,
+        "decomposition_report_path": decomposition_report_path.name,
+        "final_coverage_validation_path": final_coverage_path.name,
+        "final_findings": list(evaluation.get("findings") or []) + list(decomposition_report.get("findings") or []) + list(final_coverage_report.get("findings") or []),
+        "final_coverage": dict(final_coverage_report.get("coverage") or {}),
+        "coverage_requirements": coverage_requirements,
+        "actor_registry": actor_registry,
+        "resolved_actor_catalog": resolved_actor_catalog,
+        "decomposition": decomposition_report,
+    }
+    _write_json(report_path, report)
+
+    _clear_previous_story_files(root)
+    story_paths: list[Path] = []
+    for index, story in enumerate(decomposed_stories, start=1):
+        out_path = root / f"US-{index:03d}.md"
+        out_path.write_text(_render_story_markdown(index=index, story=story), encoding="utf-8")
+        story_paths.append(out_path)
+
+    manifest = {
+        "story_set_id": resolved_story_set_id,
+        "idea_id": idea_id,
+        "kind": "traditional_user_stories",
+        "created_at": _iso_now(),
+        "source": "sufficient_idea",
+        "canonical_story_contract": False,
+        "traceability": {
+            "idea_id": idea_id,
+            "idea_artifact": str((get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json").relative_to(repo_root)),
+            "handoff": "promote_or_dag_to_canonical_devflow_story",
+        },
+        "coverage_requirements_path": str(coverage_requirements_path.relative_to(repo_root)),
+        "decomposition_report_path": str(decomposition_report_path.relative_to(repo_root)),
+        "story_paths": [str(path.relative_to(repo_root)) for path in story_paths],
+        "sufficiency": report,
+    }
+    _write_json(manifest_path, manifest)
+
+    if not passed:
+        raise TraditionalStoryInsufficiencyError(
+            root=root,
+            story_set_id=resolved_story_set_id,
+            report_path=report_path,
+            report=report,
+        )
+
+    return TraditionalStorySet(story_set_id=resolved_story_set_id, root=root, story_paths=story_paths, sufficiency_report=report)