@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/swarm_readiness.py

@@ -0,0 +1,554 @@
+#!/usr/bin/env python3
+"""Report whether vBRIEF candidates are ready for concurrent swarm allocation."""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+from _vbrief_story_quality import (  # noqa: E402
+    acceptance_texts_from_items,
+    as_str_list as _as_str_list,
+    deprecated_subitems_issues,
+    item_has_traces,
+    items_have_acceptance,
+    missing_required_swarm_fields,
+    story_quality_issues,
+)
+
+reconfigure_stdio()
+
+LIFECYCLE_FOLDERS = ("proposed", "pending", "active", "completed", "cancelled")
+READY = "ready"
+
+
+@dataclass
+class Candidate:
+    path: Path
+    relpath: str
+    data: dict[str, Any]
+    plan: dict[str, Any]
+    story_id: str
+    title: str
+    status: str
+    folder: str
+    kind: str
+    swarm: dict[str, Any]
+    missing: list[str] = field(default_factory=list)
+    blocked: list[str] = field(default_factory=list)
+    decomposition_needed: bool = False
+
+
+def _load_json(path: Path) -> dict[str, Any] | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _project_rel(project_root: Path, path: Path) -> str:
+    try:
+        return path.resolve().relative_to(project_root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _expand_paths(project_root: Path, patterns: list[str]) -> list[Path]:
+    if not patterns:
+        patterns = ["vbrief/active/*.vbrief.json"]
+    out: list[Path] = []
+    seen: set[Path] = set()
+    for pattern in patterns:
+        raw = Path(pattern)
+        matches: list[str]
+        if any(ch in pattern for ch in "*?["):
+            matches = glob.glob(str(raw if raw.is_absolute() else project_root / pattern))
+        else:
+            matches = [str(raw if raw.is_absolute() else project_root / pattern)]
+        for match in matches:
+            path = Path(match).resolve()
+            if path in seen or not path.is_file():
+                continue
+            seen.add(path)
+            out.append(path)
+    return sorted(out)
+
+
+def _folder_for(path: Path) -> str:
+    return path.parent.name if path.parent.name in LIFECYCLE_FOLDERS else ""
+
+
+def _plan(data: dict[str, Any]) -> dict[str, Any]:
+    plan = data.get("plan")
+    return plan if isinstance(plan, dict) else {}
+
+
+def _metadata(plan: dict[str, Any]) -> dict[str, Any]:
+    metadata = plan.get("metadata")
+    return metadata if isinstance(metadata, dict) else {}
+
+
+def _swarm(metadata: dict[str, Any]) -> dict[str, Any]:
+    swarm = metadata.get("swarm")
+    return swarm if isinstance(swarm, dict) else {}
+
+
+def _has_child_plan_refs(plan: dict[str, Any]) -> bool:
+    refs = plan.get("references")
+    if not isinstance(refs, list):
+        return False
+    return any(isinstance(ref, dict) and ref.get("type") == "x-vbrief/plan" for ref in refs)
+
+
+def _looks_like_phase(path: Path, plan: dict[str, Any]) -> bool:
+    title = str(plan.get("title") or "")
+    plan_id = str(plan.get("id") or "")
+    narratives = plan.get("narratives")
+    has_acceptance_narrative = (
+        isinstance(narratives, dict)
+        and isinstance(narratives.get("Acceptance"), str)
+        and bool(narratives["Acceptance"].strip())
+    )
+    has_items = bool(plan.get("items"))
+    stem = path.name
+    return (
+        "-ip" in stem
+        or title.lower().startswith("ip-")
+        or plan_id.lower().startswith("ip-")
+        or (not has_items and has_acceptance_narrative)
+    )
+
+
+def _kind(path: Path, plan: dict[str, Any]) -> str:
+    metadata = _metadata(plan)
+    explicit = metadata.get("kind")
+    if explicit in {"story", "epic", "phase"}:
+        return str(explicit)
+    if _has_child_plan_refs(plan):
+        return "epic"
+    if _looks_like_phase(path, plan):
+        return "phase"
+    return "story"
+
+
+def _story_id(path: Path, plan: dict[str, Any]) -> str:
+    value = plan.get("id")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    name = path.name
+    return name[: -len(".vbrief.json")] if name.endswith(".vbrief.json") else path.stem
+
+
+def _has_traces(plan: dict[str, Any], swarm: dict[str, Any]) -> bool:
+    narratives = plan.get("narratives")
+    if isinstance(narratives, dict):
+        traces = narratives.get("Traces")
+        if isinstance(traces, str) and traces.strip():
+            return True
+    items = plan.get("items")
+    if isinstance(items, list):
+        for item in items:
+            if isinstance(item, dict) and item_has_traces(item):
+                return True
+    refs = plan.get("references")
+    if isinstance(refs, list):
+        for ref in refs:
+            if isinstance(ref, dict) and ref.get("type") == "x-vbrief/spec-section":
+                return True
+    return bool(_as_str_list(swarm.get("missing_traces_justification")))
+
+
+def _plan_narrative(plan: dict[str, Any], key: str) -> str:
+    narratives = plan.get("narratives")
+    if not isinstance(narratives, dict):
+        return ""
+    value = narratives.get(key)
+    return value.strip() if isinstance(value, str) and value.strip() else ""
+
+
+def _acceptance_count_justification(plan: dict[str, Any], swarm: dict[str, Any]) -> str:
+    value = swarm.get("acceptance_criteria_justification")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return _plan_narrative(plan, "AcceptanceJustification")
+
+
+def _all_scope_ids(project_root: Path) -> dict[str, tuple[Path, str]]:
+    ids: dict[str, tuple[Path, str]] = {}
+    vbrief_dir = project_root / "vbrief"
+    for folder in LIFECYCLE_FOLDERS:
+        for path in sorted((vbrief_dir / folder).glob("*.vbrief.json")):
+            data = _load_json(path)
+            if not data:
+                continue
+            plan = _plan(data)
+            scope_id = _story_id(path, plan)
+            ids[scope_id] = (path, str(plan.get("status") or ""))
+            name = path.name
+            stem = name[: -len(".vbrief.json")] if name.endswith(".vbrief.json") else path.stem
+            ids.setdefault(stem, (path, str(plan.get("status") or "")))
+    return ids
+
+
+def _candidate(path: Path, project_root: Path) -> Candidate | None:
+    data = _load_json(path)
+    if not data:
+        return None
+    plan = _plan(data)
+    metadata = _metadata(plan)
+    swarm = _swarm(metadata)
+    return Candidate(
+        path=path,
+        relpath=_project_rel(project_root, path),
+        data=data,
+        plan=plan,
+        story_id=_story_id(path, plan),
+        title=str(plan.get("title") or path.name),
+        status=str(plan.get("status") or ""),
+        folder=_folder_for(path),
+        kind=_kind(path, plan),
+        swarm=swarm,
+    )
+
+
+def _validate_candidate(candidate: Candidate, known_ids: dict[str, tuple[Path, str]]) -> None:
+    if candidate.kind in {"epic", "phase"}:
+        candidate.decomposition_needed = True
+        return
+    if candidate.kind != "story" or _metadata(candidate.plan).get("kind") != "story":
+        candidate.missing.append("plan.metadata.kind=story")
+    if not isinstance(candidate.plan.get("id"), str) or not candidate.plan["id"].strip():
+        candidate.missing.append("plan.id")
+    if not isinstance(candidate.plan.get("title"), str) or not candidate.plan["title"].strip():
+        candidate.missing.append("plan.title")
+    description = _plan_narrative(candidate.plan, "Description")
+    implementation_plan = _plan_narrative(candidate.plan, "ImplementationPlan")
+    user_story = _plan_narrative(candidate.plan, "UserStory")
+    if not description:
+        candidate.missing.append("plan.narratives.Description")
+    if not implementation_plan:
+        candidate.missing.append("plan.narratives.ImplementationPlan")
+    if not user_story:
+        candidate.missing.append("plan.narratives.UserStory")
+    if candidate.folder == "active" and candidate.status != "running":
+        candidate.blocked.append("active candidate plan.status must be running")
+    if candidate.status == "running" and candidate.folder != "active":
+        candidate.blocked.append("plan.status=running is only valid in vbrief/active/")
+    if candidate.status == "blocked":
+        candidate.blocked.append("plan.status=blocked")
+
+    items = candidate.plan.get("items")
+    if not isinstance(items, list) or not items:
+        candidate.missing.append("plan.items")
+    else:
+        if not items_have_acceptance(items):
+            candidate.missing.append("plan.items[].narrative.Acceptance")
+        candidate.blocked.extend(deprecated_subitems_issues(items))
+
+    if candidate.swarm.get("readiness") != READY:
+        candidate.missing.append("plan.metadata.swarm.readiness=ready for concurrent allocation")
+    parallel_safe = candidate.swarm.get("parallel_safe")
+    if parallel_safe is not True and parallel_safe is not False:
+        candidate.missing.append("plan.metadata.swarm.parallel_safe")
+    candidate.missing.extend(missing_required_swarm_fields(candidate.swarm))
+    if not _has_traces(candidate.plan, candidate.swarm):
+        candidate.missing.append("Traces or missing_traces_justification")
+    candidate.blocked.extend(
+        story_quality_issues(
+            title=candidate.title,
+            description=description,
+            implementation_plan=implementation_plan,
+            user_story=user_story,
+            acceptance_texts=acceptance_texts_from_items(items),
+            acceptance_count_justification=_acceptance_count_justification(
+                candidate.plan, candidate.swarm
+            ),
+            swarm=candidate.swarm,
+            concurrent_ready=candidate.swarm.get("readiness") == READY,
+        )
+    )
+    if candidate.swarm.get("size") == "large" and candidate.swarm.get("parallel_safe") is True:
+        candidate.blocked.append("size=large cannot be parallel_safe=true")
+
+    for dep in _as_str_list(candidate.swarm.get("depends_on")):
+        if dep not in known_ids:
+            candidate.blocked.append(f"dependency {dep!r} does not resolve")
+
+
+def _candidate_dep_graph(
+    candidates: list[Candidate],
+    known_ids: dict[str, tuple[Path, str]],
+) -> dict[str, list[str]]:
+    candidate_ids = {candidate.story_id for candidate in candidates}
+    graph: dict[str, list[str]] = {}
+    for candidate in candidates:
+        deps: list[str] = []
+        for dep in _as_str_list(candidate.swarm.get("depends_on")):
+            if dep in candidate_ids:
+                deps.append(dep)
+                continue
+            known = known_ids.get(dep)
+            if known is None:
+                continue
+            _dep_path, dep_status = known
+            if dep_status not in {"completed", "failed", "cancelled"}:
+                candidate.blocked.append(f"dependency {dep!r} is not completed or a candidate")
+        graph[candidate.story_id] = deps
+    return graph
+
+
+def _mark_cycles(candidates: list[Candidate], graph: dict[str, list[str]]) -> None:
+    by_id = {candidate.story_id: candidate for candidate in candidates}
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(story_id: str, path: list[str]) -> None:
+        if story_id in visited:
+            return
+        if story_id in visiting:
+            start = path.index(story_id) if story_id in path else 0
+            cycle = [*path[start:], story_id]
+            message = f"dependency cycle: {' -> '.join(cycle)}"
+            for node in cycle:
+                if node in by_id and message not in by_id[node].blocked:
+                    by_id[node].blocked.append(message)
+            return
+        visiting.add(story_id)
+        for dep in graph.get(story_id, []):
+            visit(dep, [*path, story_id])
+        visiting.remove(story_id)
+        visited.add(story_id)
+
+    for candidate in candidates:
+        visit(candidate.story_id, [])
+
+
+def _propagate_blocked_dependencies(
+    candidates: list[Candidate],
+    graph: dict[str, list[str]],
+) -> None:
+    by_id = {candidate.story_id: candidate for candidate in candidates}
+    changed = True
+    while changed:
+        changed = False
+        for candidate in candidates:
+            if candidate.kind != "story":
+                continue
+            for dep in graph.get(candidate.story_id, []):
+                dep_candidate = by_id.get(dep)
+                if dep_candidate is None:
+                    continue
+                if (
+                    not dep_candidate.missing
+                    and not dep_candidate.blocked
+                    and not dep_candidate.decomposition_needed
+                ):
+                    continue
+                message = f"dependency {dep!r} is blocked"
+                if message not in candidate.blocked:
+                    candidate.blocked.append(message)
+                    changed = True
+
+
+def _ready_stories(candidates: list[Candidate]) -> list[Candidate]:
+    return [
+        candidate
+        for candidate in candidates
+        if candidate.kind == "story"
+        and not candidate.missing
+        and not candidate.blocked
+        and not candidate.decomposition_needed
+    ]
+
+
+def _dependency_waves(candidates: list[Candidate], graph: dict[str, list[str]]) -> list[list[str]]:
+    ready_ids = {candidate.story_id for candidate in _ready_stories(candidates)}
+    remaining = set(ready_ids)
+    waves: list[list[str]] = []
+    while remaining:
+        wave = sorted(
+            story_id
+            for story_id in remaining
+            if all(dep not in remaining for dep in graph.get(story_id, []))
+        )
+        if not wave:
+            waves.append(sorted(remaining))
+            break
+        waves.append(wave)
+        remaining.difference_update(wave)
+    return waves
+
+
+def _transitive_deps(story_id: str, graph: dict[str, list[str]]) -> set[str]:
+    out: set[str] = set()
+    stack = list(graph.get(story_id, []))
+    while stack:
+        dep = stack.pop()
+        if dep in out:
+            continue
+        out.add(dep)
+        stack.extend(graph.get(dep, []))
+    return out
+
+
+def _file_overlaps(
+    candidates: list[Candidate],
+    graph: dict[str, list[str]],
+) -> dict[str, list[str]]:
+    file_to_ids: dict[str, list[str]] = defaultdict(list)
+    for candidate in _ready_stories(candidates):
+        for file_path in _as_str_list(candidate.swarm.get("file_scope")):
+            file_to_ids[file_path].append(candidate.story_id)
+
+    overlaps: dict[str, list[str]] = {}
+    for file_path, ids in file_to_ids.items():
+        unsafe_pairs: set[str] = set()
+        for index, left in enumerate(ids):
+            for right in ids[index + 1:]:
+                if right in _transitive_deps(left, graph) or left in _transitive_deps(right, graph):
+                    continue
+                unsafe_pairs.add(left)
+                unsafe_pairs.add(right)
+        if unsafe_pairs:
+            overlaps[file_path] = sorted(unsafe_pairs)
+    return overlaps
+
+
+def _conflict_groups(candidates: list[Candidate]) -> dict[str, list[str]]:
+    groups: dict[str, list[str]] = defaultdict(list)
+    for candidate in candidates:
+        group = candidate.swarm.get("conflict_group")
+        if isinstance(group, str) and group.strip():
+            groups[group].append(candidate.story_id)
+    return dict(sorted(groups.items()))
+
+
+def _render_report(
+    candidates: list[Candidate],
+    graph: dict[str, list[str]],
+    overlaps: dict[str, list[str]],
+) -> str:
+    ready = _ready_stories(candidates)
+    blocked = [
+        candidate
+        for candidate in candidates
+        if candidate.kind == "story" and (candidate.missing or candidate.blocked)
+    ]
+    needs_decomposition = [candidate for candidate in candidates if candidate.decomposition_needed]
+    lines: list[str] = ["Swarm readiness report", ""]
+
+    lines.append("Ready stories:")
+    if ready:
+        for candidate in ready:
+            lines.append(f"- {candidate.story_id}: {candidate.title} ({candidate.relpath})")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Blocked stories:")
+    if blocked:
+        for candidate in blocked:
+            reasons = [*candidate.missing, *candidate.blocked]
+            lines.append(f"- {candidate.story_id}: {candidate.title} -- {'; '.join(reasons)}")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Decomposition-needed epics/phases:")
+    if needs_decomposition:
+        for candidate in needs_decomposition:
+            lines.append(f"- {candidate.story_id}: kind={candidate.kind} ({candidate.relpath})")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Dependency waves:")
+    waves = _dependency_waves(candidates, graph)
+    if waves:
+        for index, wave in enumerate(waves, start=1):
+            lines.append(f"- wave {index}: {', '.join(wave)}")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Conflict groups:")
+    groups = _conflict_groups(candidates)
+    if groups:
+        for group, ids in groups.items():
+            lines.append(f"- {group}: {', '.join(sorted(ids))}")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("File overlap matrix:")
+    if overlaps:
+        for file_path, ids in sorted(overlaps.items()):
+            lines.append(f"- {file_path}: {', '.join(ids)}")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Missing fields:")
+    missing_any = False
+    for candidate in candidates:
+        if candidate.missing:
+            missing_any = True
+            lines.append(f"- {candidate.story_id}: {', '.join(candidate.missing)}")
+    if not missing_any:
+        lines.append("- none")
+    return "\n".join(lines)
+
+
+def readiness_report(project_root: Path, paths: list[Path]) -> tuple[int, str]:
+    candidates = [candidate for path in paths if (candidate := _candidate(path, project_root))]
+    if not candidates:
+        return 1, "Swarm readiness report\n\nNo candidate vBRIEFs found."
+    known_ids = _all_scope_ids(project_root)
+    for candidate in candidates:
+        known_ids.setdefault(candidate.story_id, (candidate.path, candidate.status))
+    for candidate in candidates:
+        _validate_candidate(candidate, known_ids)
+    graph = _candidate_dep_graph(candidates, known_ids)
+    _mark_cycles(candidates, graph)
+    _propagate_blocked_dependencies(candidates, graph)
+    overlaps = _file_overlaps(candidates, graph)
+    report = _render_report(candidates, graph, overlaps)
+    failed = any(
+        candidate.missing
+        or candidate.blocked
+        or candidate.decomposition_needed
+        for candidate in candidates
+    ) or bool(overlaps)
+    return 1 if failed else 0, report
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Report whether vBRIEF candidates are ready for concurrent swarm allocation."
+    )
+    parser.add_argument("paths", nargs="*", help="Candidate vBRIEF paths or globs")
+    parser.add_argument("--project-root", default=".", help="Project root containing vbrief/")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(sys.argv[1:] if argv is None else argv)
+    project_root = Path(args.project_root).resolve()
+    paths = _expand_paths(project_root, args.paths)
+    code, report = readiness_report(project_root, paths)
+    print(report)
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())