@deftai/directive-content 0.58.0 → 0.60.0

package/scripts/roadmap_render.py

@@ -1,635 +0,0 @@
-#!/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())