@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/roadmap_render.py

@@ -0,0 +1,635 @@
+#!/usr/bin/env python3
+"""
+roadmap_render.py -- Render ROADMAP.md from vbrief/pending/ contents.
+
+Deterministic tool that generates ROADMAP.md grouped by phase (vBRIEF
+item hierarchy) with dependency-based ordering (vBRIEF edges). Surfaces
+GitHub issue numbers from vBRIEF references entries.
+
+Usage:
+    uv run python scripts/roadmap_render.py [pending_dir] [out_file]
+
+    pending_dir -- path to vbrief/pending/ (default: <cwd>/vbrief/pending)
+    out_file    -- output path (default: <cwd>/ROADMAP.md)
+
+Exit codes:
+    0 -- rendered successfully
+    1 -- error during rendering
+
+Part of #309 (RFC: vBRIEF-centric document model). Closes #311.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+# UTF-8 stdout guard (#540).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+
+reconfigure_stdio()
+
+# Canonical 4-line machine-generated banner per
+# ``conventions/machine-generated-banner.md`` (#572). All four lines
+# are populated (Purpose / Source of truth / Regenerate with) so
+# downstream detectors can match on a stable token.
+BANNER = (
+    "<!-- AUTO-GENERATED by task roadmap:render -- DO NOT EDIT MANUALLY -->\n"
+    "<!-- Purpose: rendered roadmap -->\n"
+    "<!-- Source of truth: vbrief/pending/ (scope vBRIEFs) -->\n"
+    "<!-- Regenerate with: task roadmap:render -->\n"
+)
+
+
+def _scope_metadata_rank(plan: dict) -> int | None:
+    """Return ``plan.metadata.rank`` as an int, or ``None`` when absent/invalid.
+
+    Deliberate mirror of ``scripts/triage_queue.scope_metadata_rank`` so
+    the roadmap render and the triage queue share one rank interpretation
+    (#1419 Slice 1 / #987) without this lightweight renderer importing the
+    triage-cache module's dependency surface. A real int or an integer-
+    valued string (including a leading-minus negative) is accepted; ``bool``
+    is rejected because it subclasses ``int``; any other non-integer string
+    (e.g. ``"--3"``) returns ``None`` rather than raising. Both copies are
+    test-covered so the semantics cannot silently drift.
+    """
+    if not isinstance(plan, dict):
+        return None
+    metadata = plan.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    rank = metadata.get("rank")
+    if isinstance(rank, bool):
+        return None
+    if isinstance(rank, int):
+        return rank
+    if isinstance(rank, str):
+        try:
+            return int(rank.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _scope_rank_sort_key(vbrief: dict) -> tuple[int, int]:
+    """Stable-sort key ordering scopes by ``plan.metadata.rank`` ascending.
+
+    Ranked scopes sort first by ascending rank value (bucket 0); un-ranked
+    scopes tail-sort together (bucket 1). Because the caller pre-sorts by
+    filename and Python's sort is stable, filename order is the natural
+    tiebreaker within each bucket (#1419 Slice 1 / #987).
+    """
+    plan = vbrief.get("plan", {})
+    rank = _scope_metadata_rank(plan)
+    if rank is None:
+        return (1, 0)
+    return (0, rank)
+
+
+def _load_vbriefs(folder: Path) -> list[dict]:
+    """Load all .vbrief.json files from a folder, ordered by rank then name.
+
+    Files are first sorted by filename, then stably re-sorted by
+    ``plan.metadata.rank`` ascending (#1419 Slice 1 / #987) so ROADMAP.md
+    lists pending scopes in rank order. Un-ranked scopes tail-sort after
+    ranked ones, with filename as the within-bucket tiebreaker.
+    """
+    if not folder.is_dir():
+        return []
+    files = sorted(folder.glob("*.vbrief.json"))
+    vbriefs = []
+    for f in files:
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+            data["_source_file"] = f.name
+            vbriefs.append(data)
+        except (json.JSONDecodeError, OSError):
+            # Skip malformed files silently
+            continue
+    vbriefs.sort(key=_scope_rank_sort_key)
+    return vbriefs
+
+
+def _extract_issue_refs(references: list[dict]) -> list[str]:
+    """Extract GitHub issue numbers from vBRIEF references entries.
+
+    Accepts both the canonical v0.6 shape ``{uri, type, title}`` (#613)
+    and the legacy ``{id}`` / ``{url}`` shapes so ROADMAP.md renders
+    correctly against mixed-shape worktrees during the migrator flip.
+    """
+    issues: list[str] = []
+    for ref in references:
+        if not isinstance(ref, dict):
+            continue
+        # Legacy shape: explicit ``#N`` in ``id``.
+        ref_id = ref.get("id", "")
+        if isinstance(ref_id, str) and ref_id.startswith("#"):
+            issues.append(ref_id)
+            continue
+        # Canonical v0.6 (``uri``) and legacy (``url``) both carry a
+        # ``/issues/{N}`` suffix when the reference points at a GitHub
+        # issue; check both so no issue number is silently dropped.
+        for key in ("uri", "url"):
+            url = ref.get(key, "")
+            if isinstance(url, str) and "/issues/" in url:
+                num = url.rstrip("/").rsplit("/", 1)[-1]
+                if num.isdigit():
+                    issues.append(f"#{num}")
+                    break
+    return issues
+
+
+def _extract_phases(vbrief: dict) -> list[dict]:
+    """Extract phase-level items from a vBRIEF plan.
+
+    Each top-level plan.item is treated as a phase. SubItems within
+    are the individual work items within that phase.
+    """
+    plan = vbrief.get("plan", {})
+    if not isinstance(plan, dict):
+        return []
+    return plan.get("items", [])
+
+
+def _read_edge_endpoints(edge: dict) -> tuple[str, str]:
+    """Read an edge's from/to endpoints, supporting both schema conventions.
+
+    Prefers schema-canonical ``from``/``to`` keys. Falls back to legacy
+    ``source``/``target`` keys when the canonical keys are absent. If both
+    forms are present on the same edge, ``from``/``to`` wins. See #458 for
+    rationale -- silent-empty dep maps occur when schema-compliant inputs
+    meet code that only reads one convention.
+    """
+    if not isinstance(edge, dict):
+        return "", ""
+    frm = edge.get("from") or edge.get("source", "") or ""
+    to = edge.get("to") or edge.get("target", "") or ""
+    return frm, to
+
+
+def _build_edge_map(vbrief: dict) -> dict[str, list[str]]:
+    """Build a dependency map from plan.edges.
+
+    Returns dict mapping item id -> list of ids it depends on.
+    Edges are directional: ``{from, to}`` means ``to`` depends on ``from``,
+    or equivalently ``from`` must complete before ``to``. Legacy
+    ``{source, target}`` edges are read with the same semantics (see #458).
+    """
+    plan = vbrief.get("plan", {})
+    if not isinstance(plan, dict):
+        return {}
+    edges = plan.get("edges", [])
+    if not isinstance(edges, list):
+        return {}
+    dep_map: dict[str, list[str]] = {}
+    for edge in edges:
+        frm, to = _read_edge_endpoints(edge)
+        if frm and to:
+            dep_map.setdefault(to, []).append(frm)
+    return dep_map
+
+
+def _topo_sort_items(items: list[dict], dep_map: dict[str, list[str]]) -> list[dict]:
+    """Sort items by dependency order using topological sort.
+
+    Items without dependencies come first. Falls back to original
+    order for items with equal dependency depth.
+    """
+    if not items:
+        return []
+
+    id_to_item = {item.get("id", f"_anon_{i}"): item for i, item in enumerate(items)}
+    item_ids = list(id_to_item.keys())
+
+    # Compute depth for each item (longest dependency chain)
+    depths: dict[str, int] = {}
+
+    def _depth(item_id: str, visited: set[str] | None = None) -> int:
+        if item_id in depths:
+            return depths[item_id]
+        if visited is None:
+            visited = set()
+        if item_id in visited:
+            # Cycle detected -- break it
+            return 0
+        visited.add(item_id)
+        deps = dep_map.get(item_id, [])
+        if not deps:
+            depths[item_id] = 0
+            return 0
+        in_scope_deps = [d for d in deps if d in id_to_item]
+        if not in_scope_deps:
+            depths[item_id] = 0
+            return 0
+        max_dep = max(_depth(d, visited) for d in in_scope_deps)
+        result = max_dep + 1
+        depths[item_id] = result
+        return result
+
+    for iid in item_ids:
+        _depth(iid)
+
+    # Stable sort: by depth first, then by original order
+    sorted_ids = sorted(item_ids, key=lambda x: (depths.get(x, 0), item_ids.index(x)))
+    return [id_to_item[iid] for iid in sorted_ids]
+
+
+def _render_item(item: dict, dep_map: dict[str, list[str]], indent: int = 0) -> list[str]:
+    """Render a single item (and its subItems) as markdown lines."""
+    lines: list[str] = []
+    item_id = item.get("id", "")
+    title = item.get("title", "Untitled")
+    status = item.get("status", "")
+
+    # Build display line
+    prefix = "  " * indent + "- "
+    parts = []
+    if item_id:
+        parts.append(f"**{item_id}**")
+    parts.append(title)
+    if status:
+        parts.append(f"`[{status}]`")
+
+    # Show dependencies
+    deps = dep_map.get(item_id, [])
+    if deps:
+        dep_str = ", ".join(sorted(deps))
+        parts.append(f"(depends on: {dep_str})")
+
+    lines.append(prefix + " -- ".join(parts))
+
+    # Render subItems recursively
+    sub_items = item.get("subItems", [])
+    if sub_items:
+        sorted_subs = _topo_sort_items(sub_items, dep_map)
+        for sub in sorted_subs:
+            lines.extend(_render_item(sub, dep_map, indent + 1))
+
+    return lines
+
+
+def render_roadmap(
+    pending_dir: str,
+    out_path: str,
+    completed_dir: str | None = None,
+) -> tuple[bool, str]:
+    """Render ROADMAP.md from vBRIEF files in pending_dir and completed_dir.
+
+    Returns:
+        (True, message) on success.
+        (False, error_message) on failure.
+    """
+    try:
+        cd = Path(completed_dir) if completed_dir else None
+        content = generate_roadmap_content(Path(pending_dir), completed_dir=cd)
+        Path(out_path).write_text(content, encoding="utf-8")
+        return True, f"✓ Rendered ROADMAP.md to {out_path}"
+    except OSError as exc:
+        return False, f"✗ Failed to write {out_path}: {exc}"
+
+
+# #616: migrator-internal provenance (Phase / Tier / PhaseDescription)
+# now lives under ``plan.metadata['x-migrator']`` on scope vBRIEFs
+# produced by ``task migrate:vbrief``. Scope vBRIEFs authored before the
+# clamp still carry these keys under ``plan.narratives``, so the
+# grouping helpers below consult BOTH locations: metadata wins when
+# present (new shape), narratives are the fallback (legacy / hand-
+# authored files).
+_MIGRATOR_METADATA_KEY: str = "x-migrator"
+
+
+def _migrator_metadata(plan: dict) -> dict:
+    """Return ``plan.metadata['x-migrator']`` as a dict (empty if absent)."""
+    metadata = plan.get("metadata", {}) if isinstance(plan, dict) else {}
+    if not isinstance(metadata, dict):
+        return {}
+    bucket = metadata.get(_MIGRATOR_METADATA_KEY, {})
+    if not isinstance(bucket, dict):
+        return {}
+    return bucket
+
+
+def _migrator_field(plan: dict, key: str) -> str:
+    """Return ``plan.metadata['x-migrator'][key]`` falling back to ``plan.narratives[key]``.
+
+    Returns the empty string if neither location carries a non-empty
+    string value. Used for Phase / Tier / PhaseDescription lookups that
+    were relocated from narratives to metadata in #616 while keeping
+    backwards compatibility with legacy scope vBRIEFs.
+    """
+    bucket = _migrator_metadata(plan)
+    value = bucket.get(key, "")
+    if isinstance(value, str) and value:
+        return value
+    narratives = plan.get("narratives", {}) if isinstance(plan, dict) else {}
+    if isinstance(narratives, dict):
+        fallback = narratives.get(key, "")
+        if isinstance(fallback, str):
+            return fallback
+    return ""
+
+
+# #641: ``task roadmap:render`` previously preserved insertion order
+# of phase labels as they were first encountered while scanning
+# ``vbrief/pending/``. That made the rendered section order depend on
+# file-discovery / glob order rather than numeric phase, so ROADMAP.md
+# could render Phase 6 before Phase 1. ``_PHASE_NUMBER_RE`` and
+# ``_phase_sort_key`` give us a deterministic numeric-first ordering
+# (Phase 1, Phase 2, ...) with non-numbered groups (e.g. "Ungrouped")
+# sorted alphabetically AFTER all numbered phases.
+_PHASE_NUMBER_RE: re.Pattern[str] = re.compile(r"^Phase\s+(\d+)\b")
+
+
+def _phase_sort_key(phase_name: str) -> tuple[int, int, str]:
+    """Sort key for phase group names.
+
+    Numbered phases (``^Phase\\s+(\\d+)\\b``) sort FIRST in ascending
+    numeric order (tuple slot 0 == 0). Non-numbered phase labels (e.g.
+    ``Ungrouped``, ``Backlog``, ``Completed``) sort AFTER all numbered
+    phases (tuple slot 0 == 1), then alphabetically by label.
+
+    The numeric slot is unused for non-numbered phases (set to 0) so the
+    alphabetical tiebreaker comes from slot 2. Fixes #641.
+    """
+    match = _PHASE_NUMBER_RE.match(phase_name)
+    if match is not None:
+        return (0, int(match.group(1)), phase_name)
+    return (1, 0, phase_name)
+
+
+def _sorted_phase_names(phase_names: list[str]) -> list[str]:
+    """Return phase names sorted by ``_phase_sort_key`` (#641).
+
+    Numbered phases (``Phase 1``, ``Phase 2``, ...) come first in
+    ascending numeric order; non-numbered groups come after in
+    alphabetical order. Duplicates are preserved (caller responsibility).
+    """
+    return sorted(phase_names, key=_phase_sort_key)
+
+
+def _group_by_phase(
+    vbriefs: list[dict],
+) -> tuple[dict[str, list[dict]], dict[str, str]]:
+    """Group flat scope vBRIEFs by their Phase label.
+
+    Reads Phase / PhaseDescription from ``plan.metadata['x-migrator']``
+    first (canonical post-#616 location) and falls back to
+    ``plan.narratives`` for legacy / hand-authored vBRIEFs.
+
+    Phase groups are returned in numeric-first ascending order: any
+    ``^Phase\\s+(\\d+)\\b`` label sorts by the parsed integer, and
+    non-numbered groups (e.g. ``Ungrouped``) sort after all numbered
+    phases in alphabetical order. This replaces the previous
+    insertion-order behaviour that depended on file-discovery order
+    (#641).
+
+    Returns:
+      - phase_groups: dict of phase -> list of vBRIEFs, keys iterated
+        in numeric-phase-first order
+      - phase_descriptions: dict of phase -> PhaseDescription
+    """
+    # First pass: accumulate in insertion order so per-phase vBRIEF
+    # order is still filename-sorted (from ``_load_vbriefs``).
+    insertion_groups: dict[str, list[dict]] = {}
+    phase_descriptions: dict[str, str] = {}
+
+    for vb in vbriefs:
+        plan = vb.get("plan", {})
+        if not isinstance(plan, dict):
+            continue
+        phase = _migrator_field(plan, "Phase") or "Ungrouped"
+        insertion_groups.setdefault(phase, []).append(vb)
+        # Capture phase description from the first vBRIEF that has one
+        if phase not in phase_descriptions:
+            pd = _migrator_field(plan, "PhaseDescription")
+            if pd:
+                phase_descriptions[phase] = pd
+
+    # Second pass: rebuild the dict in sorted phase order so downstream
+    # iteration (e.g. ``generate_roadmap_content``) emits ``## Phase 1``
+    # before ``## Phase 2`` before ``## Ungrouped`` (#641).
+    phase_groups: dict[str, list[dict]] = {
+        name: insertion_groups[name]
+        for name in _sorted_phase_names(list(insertion_groups.keys()))
+    }
+
+    return phase_groups, phase_descriptions
+
+
+def _group_by_tier(vbriefs: list[dict]) -> dict[str, list[dict]]:
+    """Group vBRIEFs by their Tier label within a phase (bilingual reader)."""
+    tier_groups: dict[str, list[dict]] = {}
+    for vb in vbriefs:
+        plan = vb.get("plan", {})
+        if not isinstance(plan, dict):
+            continue
+        tier = _migrator_field(plan, "Tier")
+        tier_groups.setdefault(tier, []).append(vb)
+    return tier_groups
+
+
+def _render_scope_item(vbrief_data: dict) -> list[str]:
+    """Render a single scope vBRIEF as a markdown list item."""
+    plan = vbrief_data.get("plan", {})
+    if not isinstance(plan, dict):
+        return []
+    title = plan.get("title", "Untitled")
+    status = plan.get("status", "")
+    references = plan.get("references", [])
+    if not isinstance(references, list):
+        references = []
+    issue_refs = _extract_issue_refs(references)
+
+    parts = []
+    if issue_refs:
+        parts.append(f"**{issue_refs[0]}**")
+    parts.append(title)
+    if status and status != "pending":
+        parts.append(f"`[{status}]`")
+
+    return ["- " + " -- ".join(parts)]
+
+
+def generate_roadmap_content(
+    pending_dir: Path,
+    completed_dir: Path | None = None,
+) -> str:
+    """Generate the ROADMAP.md content string from pending/ and completed/ vBRIEFs.
+
+    This is the pure function used by both render and drift check.
+    Groups scope vBRIEFs by Phase narrative key, renders phase headings
+    with descriptions, includes tier subgroupings, and appends a Completed
+    section from completed/ folder.
+    """
+    vbriefs = _load_vbriefs(pending_dir)
+
+    # Infer completed_dir from pending_dir if not provided
+    if completed_dir is None:
+        completed_dir = pending_dir.parent / "completed"
+    completed_vbriefs = _load_vbriefs(completed_dir)
+
+    lines: list[str] = [BANNER, "# Roadmap\n"]
+
+    if not vbriefs and not completed_vbriefs:
+        lines.append("No pending work items.\n")
+        return "\n".join(lines) + "\n"
+
+    # Check if any vBRIEFs use the flat scope model. Post-#616 the
+    # migrator writes Phase to ``plan.metadata['x-migrator']``; legacy
+    # vBRIEFs still carry it under ``plan.narratives``. Accept either so
+    # a mid-transition repo renders consistently.
+    has_phase_narratives = any(
+        _migrator_field(vb.get("plan", {}), "Phase")
+        for vb in vbriefs
+        if isinstance(vb.get("plan", {}), dict)
+    )
+
+    if has_phase_narratives:
+        # --- Flat scope vBRIEFs grouped by Phase narrative ---
+        phase_groups, phase_descs = _group_by_phase(vbriefs)
+
+        for phase_name, phase_vbriefs in phase_groups.items():
+            lines.append(f"## {phase_name}\n")
+            desc = phase_descs.get(phase_name, "")
+            if desc:
+                lines.append(f"{desc}\n")
+
+            # Group by tier within phase
+            tier_groups = _group_by_tier(phase_vbriefs)
+            has_tiers = any(t for t in tier_groups if t)
+
+            if has_tiers:
+                # Render named tiers first, then untiered items
+                untiered = tier_groups.pop("", [])
+                for tier_name, tier_vbs in tier_groups.items():
+                    lines.append(f"### {tier_name}\n")
+                    for vb in tier_vbs:
+                        lines.extend(_render_scope_item(vb))
+                    lines.append("")
+                if untiered:
+                    for vb in untiered:
+                        lines.extend(_render_scope_item(vb))
+                    lines.append("")
+            else:
+                for vb in phase_vbriefs:
+                    lines.extend(_render_scope_item(vb))
+                lines.append("")
+    else:
+        # --- Hierarchical vBRIEFs (original behavior) ---
+        for vbrief in vbriefs:
+            plan = vbrief.get("plan", {})
+            if not isinstance(plan, dict):
+                continue
+
+            plan_title = plan.get("title", "Untitled")
+            references = plan.get("references", [])
+            if not isinstance(references, list):
+                references = []
+            issue_refs = _extract_issue_refs(references)
+
+            title_parts = [f"## {plan_title}"]
+            if issue_refs:
+                title_parts.append(f"({', '.join(issue_refs)})")
+            lines.append(" ".join(title_parts) + "\n")
+
+            narratives = plan.get("narratives", {})
+            if isinstance(narratives, dict):
+                overview = narratives.get("Overview", "")
+                if overview:
+                    lines.append(f"{overview}\n")
+
+            dep_map = _build_edge_map(vbrief)
+            phases = _extract_phases(vbrief)
+            sorted_phases = _topo_sort_items(phases, dep_map)
+
+            for phase in sorted_phases:
+                phase_id = phase.get("id", "")
+                phase_title = phase.get("title", "Untitled Phase")
+                phase_status = phase.get("status", "")
+
+                heading_parts = []
+                if phase_id:
+                    heading_parts.append(f"### {phase_id}: {phase_title}")
+                else:
+                    heading_parts.append(f"### {phase_title}")
+                if phase_status:
+                    heading_parts[0] += f" `[{phase_status}]`"
+                lines.append(heading_parts[0] + "\n")
+
+                narrative = phase.get("narrative", {})
+                if isinstance(narrative, dict):
+                    for key, val in narrative.items():
+                        if key not in ("Traces", "Acceptance"):
+                            lines.append(f"{val}\n")
+
+                sub_items = phase.get("subItems", [])
+                if sub_items:
+                    sorted_subs = _topo_sort_items(sub_items, dep_map)
+                    for item in sorted_subs:
+                        lines.extend(_render_item(item, dep_map))
+                    lines.append("")
+
+            lines.append("---\n")
+
+    # --- Completed section ---
+    if completed_vbriefs:
+        lines.append("## Completed\n")
+        for vb in completed_vbriefs:
+            lines.extend(_render_scope_item(vb))
+        lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+
+def check_drift(pending_dir: str, roadmap_path: str) -> tuple[bool, str]:
+    """Check if ROADMAP.md matches what roadmap:render would produce.
+
+    Returns:
+        (True, message) if ROADMAP.md is up to date.
+        (False, message) if ROADMAP.md has drifted.
+    """
+    expected = generate_roadmap_content(Path(pending_dir))
+    roadmap = Path(roadmap_path)
+
+    if not roadmap.exists():
+        # If no ROADMAP.md exists and we'd generate empty content, that's OK
+        pending_p = Path(pending_dir)
+        inferred_completed = pending_p.parent / "completed"
+        has_pending = pending_p.is_dir() and list(
+            pending_p.glob("*.vbrief.json")
+        )
+        has_completed = inferred_completed.is_dir() and list(
+            inferred_completed.glob("*.vbrief.json")
+        )
+        if not has_pending and not has_completed:
+            return True, "✓ No ROADMAP.md needed (no pending or completed vBRIEFs)"
+        return False, "✗ ROADMAP.md does not exist but vBRIEFs found"
+
+    actual = roadmap.read_text(encoding="utf-8")
+    if actual == expected:
+        return True, "✓ ROADMAP.md is up to date"
+    return False, "✗ ROADMAP.md has drifted from pending/ vBRIEFs -- run: task roadmap:render"
+
+
+def main() -> int:
+    """CLI entry point."""
+    positional = [a for a in sys.argv[1:] if not a.startswith("--")]
+    pending_dir = positional[0] if len(positional) >= 1 else str(Path.cwd() / "vbrief" / "pending")
+    out_path = positional[1] if len(positional) >= 2 else str(Path.cwd() / "ROADMAP.md")
+
+    # Check for --check flag
+    if "--check" in sys.argv:
+        ok, msg = check_drift(pending_dir, out_path)
+        print(msg)
+        return 0 if ok else 1
+
+    ok, msg = render_roadmap(pending_dir, out_path)
+    print(msg)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())