@ikon85/agent-workflow-kit 0.10.0

package/scripts/pr-body-check.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""
+pr-body-check.py — mechanical guard for the PR-body conventions that were until
+now prose-only.
+
+Called by `wrapup` Step 0c AFTER the PR has been created/reused, BEFORE the
+merge gate. Turns three instruction-only rules into a check that actually fires:
+
+  1. Anker-Slice (Issue HAS a parent) → body MUST contain `Part of #<parent>`
+     and MUST NOT contain a close-keyword on the **parent anchor** number
+     (close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved, case-insens.)
+     — the incident: `closes #<anker>` on a slice-PR closed the wave anchor.
+     A `closes #<foreign-leaf>` (any number ≠ parent) stays ALLOWED.
+  2. Atomar Leaf (Issue has NO parent / FREI) → body MUST contain an ACTIVE
+     `closes #<issue>` — not inside a code span / backticks (else GitHub's
+     auto-close never fires, wrapup Step 5b lesson).
+  3. `**Retro:**`-Pflichtzeile present in one of the Slice-7 forms
+     (`gefahren …` | `übersprungen …`), with a space after the marker.
+
+Scope: this script checks ONLY the closes/Part-of anchor rule and the
+`**Retro:**` line. It does NOT parse or validate `annahme-drift` markers
+(those are prose-/judgment-driven in wrapup Step 0c + 5e, deliberately not
+mechanised — R2-F6). The annahme-drift block therefore runs BEFORE this
+check in wrapup Step 0c so the body the script sees is final.
+
+Exit codes:
+  0 — green (no violations)
+  1 — violation(s) found → wrapup STOPs, fix body via `gh pr edit --body-file`
+  2 — not checkable (no issue-number derivable from the branch, or PR body
+      unavailable) → warn, do NOT block (fail-open, like drift-guard).
+
+The pure functions below carry the logic + the unit tests; gh/git access is a
+thin shell. NOT a hook — `wrapup` invokes it (Design).
+
+Usage:
+  pr-body-check.py [--branch <name>] [--issue <n>] [--parent <n>|FREI]
+                   [--body-file <path>]
+All flags optional; unset → derived from the current branch + live PR via gh.
+
+Audit log: .claude/logs/pr-body-check.log
+"""
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from board_config import ConfigError, load_board_config  # noqa: E402
+
+try:
+    _CFG = load_board_config()
+except ConfigError as exc:
+    print(f"[FAIL] pr-body-check: Board-Profil nicht verfügbar — {exc}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _spaced(marker: str) -> str:
+    """Escape a marker, letting any run of whitespace inside it match `\\s+`."""
+    return r"\s+".join(re.escape(tok) for tok in marker.split())
+
+
+LOG_DIR = Path(".claude/logs")
+LOG_NAME = "pr-body-check"
+
+# Branch prefixes + the `Part of` / `**Retro:**` markers are PROJECT conventions
+# → read from the board profile. GitHub's auto-close keywords are a PLATFORM
+# constant (GitHub only auto-closes on exactly this set), so they stay hardcoded
+# here — configuring them would be a footgun, not a portability win.
+BRANCH_ISSUE_RE = re.compile(
+    r"^(?:" + "|".join(re.escape(p) for p in _CFG["branchPrefixes"]) + r")/(\d+)-")
+CLOSE_KEYWORDS = r"close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved"
+RETRO_RE = re.compile(
+    re.escape(_CFG["prMarkers"]["retroMarker"]) + r"\s+("
+    + "|".join(re.escape(v) for v in _CFG["prMarkers"]["retroValues"]) + r")\b",
+    re.IGNORECASE)
+PART_OF_RE_SRC = _spaced(_CFG["prMarkers"]["partOf"])
+INLINE_CODE_RE = re.compile(r"`[^`]*`")
+FENCED_CODE_RE = re.compile(r"```.*?```", re.DOTALL)
+
+
+def log(msg: str) -> None:
+    try:
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        with (LOG_DIR / f"{LOG_NAME}.log").open("a", encoding="utf-8") as f:
+            f.write(f"{datetime.now().isoformat(timespec='seconds')} {msg}\n")
+    except Exception:
+        pass
+
+
+# --- pure parsers / checks --------------------------------------------------
+def parse_issue_from_branch(branch: str):
+    """Issue number from `feat/<n>-slug` (also fix/chore/docs), or None."""
+    m = BRANCH_ISSUE_RE.match(branch or "")
+    return int(m.group(1)) if m else None
+
+
+def strip_code(text: str) -> str:
+    """Remove fenced + inline code spans so a keyword that only lives inside
+    backticks does not count as active (GitHub ignores it for auto-close)."""
+    return INLINE_CODE_RE.sub(" ", FENCED_CODE_RE.sub(" ", text or ""))
+
+
+def _close_on(body: str, n: int) -> bool:
+    """True if an ACTIVE close-keyword targets #n (outside code spans).
+
+    Matches `closes #n`, the colon form `closes: #n` (GitHub auto-closes on both
+    — the colon form was the R2-F3 bypass on the anchor guard), AND the
+    full-URL form `closes https://github.com/<owner>/<repo>/issues/<n>` (GitHub
+    auto-closes on this too — exactly the class bypass this script exists
+    to catch).
+    """
+    target = rf"(?:#0*{n}(?!\d)|https?://\S+/issues/0*{n}(?!\d))"
+    pat = re.compile(
+        rf"\b(?:{CLOSE_KEYWORDS})(?::\s*|\s+){target}", re.IGNORECASE)
+    return bool(pat.search(strip_code(body)))
+
+
+def _part_of(body: str, n: int) -> bool:
+    return bool(re.search(
+        rf"\b{PART_OF_RE_SRC}(?::\s*|\s+)#0*{n}(?!\d)", body or "", re.IGNORECASE))
+
+
+def check_pr_body(body: str, issue: int, parent, is_anchor: bool = False):
+    """Return a list of violation strings ([] = green).
+
+    parent is the anchor issue number, or None for an atomar Leaf.
+    is_anchor: the branch issue IS itself a Wellen-Anker (type:cluster) —
+    Wave-PR-Fall: ein PR auf `feat/<anker#>-…` closed die Leaf-Issues,
+    nie den Anker selbst.
+    """
+    violations = []
+    body = body or ""
+
+    if parent is not None:
+        # Anker-Slice
+        if not _part_of(body, parent):
+            violations.append(
+                f"Anker-Slice: Body braucht `Part of #{parent}` (fehlt).")
+        if _close_on(body, parent):
+            violations.append(
+                f"Anker-Slice: Body enthält ein close-Keyword auf den Anker "
+                f"#{parent} — das schließt den Wellen-Anker beim Merge verfrüht "
+                f". `Part of #{parent}` nutzen, kein closes.")
+    elif is_anchor:
+        # Wave-PR auf dem Anker-Branch selbst (Branch trägt die Anker-Nummer)
+        if not _part_of(body, issue):
+            violations.append(
+                f"Wave-PR auf Anker-Branch: Body braucht `Part of #{issue}` (fehlt).")
+        if _close_on(body, issue):
+            violations.append(
+                f"Wave-PR: Body enthält ein close-Keyword auf den Anker #{issue} "
+                f"— das schließt den Anker beim Merge. Entfernen; die "
+                f"Leaf-Issues per `closes #<leaf>` schließen.")
+    else:
+        # Atomar Leaf
+        if not _close_on(body, issue):
+            violations.append(
+                f"Leaf-PR: aktives `closes #{issue}` fehlt (oder steht in "
+                f"Backticks → GitHub-Auto-Close greift dann nicht).")
+
+    if not RETRO_RE.search(body):
+        violations.append(
+            "Pflichtzeile `**Retro:** gefahren — …` oder "
+            "`**Retro:** übersprungen — <Grund>` fehlt.")
+
+    return violations
+
+
+# --- thin git/gh shell ------------------------------------------------------
+def _run(cmd, timeout=15):
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return r.returncode, r.stdout.strip()
+    except Exception:
+        return -1, ""
+
+
+def current_branch():
+    rc, out = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+    return out if rc == 0 and out else None
+
+
+def fetch_parent(number: int):
+    """Parent issue number via board-sync.py, or None (FREI = atomar)."""
+    rc, out = _run(["python3", "scripts/board-sync.py", "parent-of", str(number)])
+    if rc != 0 or not out or out.strip() == "FREI":
+        return None
+    try:
+        return int(out.strip())
+    except ValueError:
+        return None
+
+
+def fetch_pr_body(branch: str):
+    rc, out = _run(["gh", "pr", "view", branch, "--json", "body", "-q", ".body"])
+    return out if rc == 0 else None
+
+
+def fetch_is_anchor(number: int) -> bool:
+    """True wenn das Issue selbst ein Wellen-Anker ist (Label type:cluster)."""
+    rc, out = _run(["gh", "issue", "view", str(number),
+                    "--json", "labels", "-q", ".labels[].name"])
+    if rc != 0:
+        return False  # fail-open in den Leaf-Pfad (bisheriges Verhalten)
+    return "type:cluster" in out.splitlines()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[1])
+    ap.add_argument("--branch", help="default: current git branch")
+    ap.add_argument("--issue", type=int, help="override branch-derived issue #")
+    ap.add_argument("--parent", help="override parent (number or FREI)")
+    ap.add_argument("--body-file", help="read PR body from file instead of gh")
+    args = ap.parse_args()
+
+    branch = args.branch or current_branch()
+    issue = args.issue if args.issue is not None else (
+        parse_issue_from_branch(branch) if branch else None)
+    if issue is None:
+        print(f"[WARN] pr-body-check: keine Issue-Nummer aus Branch '{branch}' "
+              f"ableitbar — übersprungen (kein Block).")
+        log(f"branch={branch} no-issue → exit 2")
+        return 2
+
+    if args.body_file:
+        try:
+            body = Path(args.body_file).read_text(encoding="utf-8")
+        except Exception as e:
+            print(f"[WARN] pr-body-check: --body-file unlesbar ({e}) — übersprungen.")
+            return 2
+    else:
+        body = fetch_pr_body(branch)
+        if body is None:
+            print(f"[WARN] pr-body-check: PR-Body für '{branch}' nicht abrufbar "
+                  f"(kein PR? gh/Netz?) — übersprungen (kein Block).")
+            log(f"branch={branch} issue={issue} no-pr-body → exit 2")
+            return 2
+
+    if args.parent is not None:
+        parent = None if args.parent.strip().upper() == "FREI" else int(args.parent)
+    else:
+        parent = fetch_parent(issue)
+
+    is_anchor = fetch_is_anchor(issue) if parent is None else False
+    violations = check_pr_body(body, issue, parent, is_anchor=is_anchor)
+    kind = ("Anker-Slice" if parent is not None
+            else "Wave-PR" if is_anchor else "Leaf")
+    log(f"branch={branch} issue={issue} parent={parent} kind={kind} "
+        f"violations={len(violations)}")
+
+    if violations:
+        print(f"[FAIL] pr-body-check #{issue} ({kind}, parent={parent}):")
+        for v in violations:
+            print(f"  - {v}")
+        return 1
+    print(f"[OK] pr-body-check #{issue} ({kind}) — Body-Konventionen erfüllt.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/program_graph.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""program_graph.py — public assembly + report layer for the Programm-Graph.
+
+board-sync.py's `validate-graph` command imports from this one module. The
+implementation is split by concern across three cohesive files (a single file
+would exceed the 300-line size gate):
+
+  - program_graph_parse.py     — parse the Program-PRD body into dataclasses +
+                                  the Wellenplan-table / Slice-block renderers
+                                  (parser↔renderer roundtrip pairs).
+  - program_graph_validate.py  — the 8 pure validation axes over the parsed graph.
+  - this file                  — the `GraphReport` model, the `validate_program_graph`
+                                  orchestrator wiring the axes together, the counted
+                                  `render_report`, plus a flat re-export of the
+                                  parse/validate symbols consumers use.
+
+PURE — no gh / no I/O / no board_config (mirrors anchor_table.py's purity
+contract). The CLI handler in board-sync.py reads `phase_options`
+defensively from the board profile and passes it in (CR#1).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from program_graph_parse import (  # noqa: F401
+    ProgramGraph,
+    SliceBlock,
+    WaveRow,
+    parse_phase_gates,
+    parse_plan_revision,
+    parse_program_prd,
+    parse_scope_items,
+    parse_slice_blocks,
+    parse_wellenplan_table,
+    render_slice_block,
+    render_wellenplan_table,
+)
+from program_graph_validate import (  # noqa: F401
+    GATE_TYPES,
+    check_capacity,
+    check_phase_options,
+    check_revision_coherence,
+    check_rollup,
+    check_scope_coverage,
+    find_backward_refs,
+    find_cycles,
+    find_duplicate_slice_ids,
+    find_gate_dependents_outside_wave,
+    find_unknown_refs,
+)
+
+
+@dataclass
+class GraphReport:
+    scope_total: int
+    scope_covered: int
+    scope_gaps: list[str]
+    rollup_gaps: list[str]
+    cycles: list[list[str]]
+    backward_refs: list[str]
+    gate_warnings: list[str]
+    capacity_errors: list[str]
+    phase_errors: list[str]
+    revision_mismatches: list[str]
+    duplicate_id_errors: list[str]
+
+    @property
+    def cycle_messages(self) -> list[str]:
+        return [f"Zyklus: {' → '.join(c)}" for c in self.cycles]
+
+    @property
+    def errors(self) -> list[str]:
+        """Blocking findings — Vorschau-Gate publish must not proceed."""
+        return [*self.cycle_messages, *self.backward_refs, *self.capacity_errors,
+                *self.phase_errors, *self.revision_mismatches, *self.duplicate_id_errors]
+
+    @property
+    def warnings(self) -> list[str]:
+        """Advisory findings — shown + counted, but a human decides."""
+        return [*self.gate_warnings, *self.rollup_gaps, *self.scope_gaps]
+
+    @property
+    def blocking(self) -> bool:
+        return bool(self.errors)
+
+
+def validate_program_graph(prd_body: str, *, phase_options: Optional[list[str]] = None,
+                           max_children: int = 100,
+                           stub_revisions: Optional[list[dict]] = None) -> GraphReport:
+    """The single entry point: parse a Program-PRD body and run all 8 axes."""
+    graph = parse_program_prd(prd_body)
+    covered, total, scope_gaps = check_scope_coverage(graph)
+    return GraphReport(
+        scope_total=total,
+        scope_covered=covered,
+        scope_gaps=scope_gaps,
+        rollup_gaps=check_rollup(graph),
+        cycles=find_cycles(graph.slices),
+        backward_refs=[*find_backward_refs(graph.slices), *find_unknown_refs(graph.slices)],
+        gate_warnings=find_gate_dependents_outside_wave(graph.slices),
+        capacity_errors=check_capacity(graph.waves, max_children),
+        phase_errors=check_phase_options(graph, phase_options),
+        revision_mismatches=check_revision_coherence(graph.plan_revision, stub_revisions),
+        duplicate_id_errors=find_duplicate_slice_ids(graph.slices),
+    )
+
+
+def render_report(report: GraphReport) -> str:
+    """The counted Vorschau-Gate summary line + detail lines (AC1)."""
+    summary = (
+        f"Scope-Abdeckung {report.scope_covered} von {report.scope_total} · "
+        f"Rollup-Kette {'✓' if not report.rollup_gaps else 'Lücken'} · "
+        f"zyklenfrei {'✓' if not report.cycles else '✗'} · "
+        f"Kapazität {'✓' if not report.capacity_errors else '✗'} · "
+        f"Phasen-Optionen {'✓' if not report.phase_errors else '✗'}"
+    )
+    lines = [summary]
+    for msg in report.errors:
+        lines.append(f"  FEHLER: {msg}")
+    for msg in report.warnings:
+        lines.append(f"  WARNUNG: {msg}")
+    if not report.errors and not report.warnings:
+        lines.append("  keine weiteren Befunde")
+    return "\n".join(lines)

package/scripts/program_graph_parse.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""program_graph_parse.py — pure parser for the Programm-PRD grammar.
+
+Parses a Program-PRD issue body (per `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md`)
+into structured dataclasses: plan_revision, Scope-Items (S1, S2, …), the Wellenplan
+table (Welle/Status/Name/Phase/Slices/Gate/covers), the Phasen-Gates checklist,
+and the per-Slice metadata blocks (per
+`.claude/skills/to-waves/SLICE-METADATA-FORMAT.md`).
+
+PURE — no gh / no I/O / no board_config. Reuses the generic pipe-table primitives
+from anchor_table.py (a different table GRAMMAR — different columns, different
+node kinds — but the same markdown mechanics, so the parse/render primitives are
+shared rather than re-implemented design decision).
+
+The Wellenplan-table renderer lives here too (parser↔renderer roundtrip pair,
+consumed later by `program-sync`).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from anchor_table import col_index, parse_pipe_table, render_pipe_table
+
+PLAN_REV_RE = re.compile(r"\*\*plan_revision:\*\*\s*r(\d+)\b")
+_H2_RE = re.compile(r"^##\s+(.+?)\s*$")
+SCOPE_ITEM_RE = re.compile(r"^-\s+\*\*(S\d+):\*\*\s*(.+)$")
+PHASE_GATE_RE = re.compile(r"^-\s+\[([ xX])\]\s*(P\d+):\s*(.+)$")
+
+WELLENPLAN_START = "<!-- wellenplan:start -->"
+WELLENPLAN_END = "<!-- wellenplan:end -->"
+
+WELLENPLAN_HEADERS = ["Welle", "Status", "Issue", "Name", "Phase", "Slices", "Gate", "covers"]
+_ENABLER = "enabler"
+# Tokens that mean "no value" in an optional cell — shared by the Wellenplan phase
+# and covers cells and the Slice-block phase/blocked_by fields so `—` normalizes
+# consistently everywhere.
+_NONE_TOKENS = {"none", "", "—", "-"}
+
+
+def _none_if_blank(value: str) -> Optional[str]:
+    """The trimmed value, or None if it is one of the `_NONE_TOKENS` sentinels."""
+    v = (value or "").strip()
+    return None if v.lower() in _NONE_TOKENS else v
+
+
+@dataclass
+class WaveRow:
+    number: int
+    name: str
+    phase: Optional[str]
+    slice_ids: list[str]
+    gate: str
+    covers: list[str]
+    is_enabler: bool = False
+    # Volatile, board-derived — ⬜ (not started) at authoring, regenerated
+    # monotonically by `program-sync` (see program_sync.refresh_wave_status).
+    # Not a validate-graph input (no axis reads it) and — unlike the semantic
+    # columns above — TOLERANT-optional on parse (docs/adr/0054 Folge-Arbeit:
+    # one Wellenplan grammar, this is a column within it, not a second table).
+    status: str = "⬜"
+    # The promoted Wave-Anchor issue number (`#<n>` cell) — the navigation link
+    # from the program table down to the wave. Machine-written (to-waves
+    # publish / program-sync), `—` pre-publish; TOLERANT-optional like status,
+    # and identity once set (program-sync fills but never overwrites it).
+    issue: Optional[int] = None
+
+
+@dataclass
+class SliceBlock:
+    local_id: str
+    title: str
+    wave: Optional[int]
+    phase: Optional[str]
+    area: Optional[str]
+    gate: str
+    blocked_by: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ProgramGraph:
+    plan_revision: Optional[int]
+    scope_items: dict[str, str]
+    waves: list[WaveRow]
+    slices: list[SliceBlock]
+    phase_gates: dict[str, str]
+
+
+def parse_plan_revision(body: str) -> Optional[int]:
+    """The PRD's top-level `**plan_revision:** rN`, or None if absent/malformed."""
+    m = PLAN_REV_RE.search(body or "")
+    return int(m.group(1)) if m else None
+
+
+def _section_lines(body: str, heading: str) -> list[str]:
+    """Lines of a `## <heading>` section, up to (excl.) the next `##` heading."""
+    lines = (body or "").splitlines()
+    start = None
+    for i, ln in enumerate(lines):
+        m = _H2_RE.match(ln)
+        if m and m.group(1).strip() == heading:
+            start = i + 1
+            break
+    if start is None:
+        return []
+    end = len(lines)
+    for j in range(start, len(lines)):
+        if _H2_RE.match(lines[j]):
+            end = j
+            break
+    return lines[start:end]
+
+
+def parse_scope_items(body: str) -> dict[str, str]:
+    """`{S1: "description", ...}` from the `## Scope` chapter's `- **S1:** …` list."""
+    items: dict[str, str] = {}
+    for ln in _section_lines(body, "Scope"):
+        m = SCOPE_ITEM_RE.match(ln.strip())
+        if m:
+            items[m.group(1)] = m.group(2).strip()
+    return items
+
+
+def parse_phase_gates(body: str) -> dict[str, str]:
+    """`{P1: "criterion text", ...}` from the `## Phasen-Gates` checklist."""
+    gates: dict[str, str] = {}
+    for ln in _section_lines(body, "Phasen-Gates"):
+        m = PHASE_GATE_RE.match(ln.strip())
+        if m:
+            gates[m.group(2)] = m.group(3).strip()
+    return gates
+
+
+def _split_csv(cell: str) -> list[str]:
+    return [t.strip() for t in (cell or "").split(",") if t.strip()]
+
+
+def _parse_covers_cell(cell: str) -> tuple[list[str], bool]:
+    tokens = _split_csv(cell)
+    if len(tokens) == 1 and tokens[0].lower() == _ENABLER:
+        return [], True
+    # `—`/`-`/`none` tokens are the same "no value" sentinels as the phase and
+    # blocked_by cells — an all-sentinel covers cell must normalize to [], not
+    # a phantom covers=['—'] that then fools check_scope_coverage (Bug 1).
+    tokens = [t for t in tokens if t.lower() not in _NONE_TOKENS]
+    return tokens, False
+
+
+def parse_wellenplan_table(body: str) -> list[WaveRow]:
+    """The Wellenplan table between the `wellenplan:start/end` markers. `Phase` is an
+    optional column (Phasen sind optional) — absent column ⇒ every row's phase=None.
+    `Status` is likewise optional, but for a different reason: it is volatile,
+    board-derived state (never authored by hand), so an absent column or blank
+    cell ⇒ every row's status defaults to `⬜` rather than raising — same
+    tolerant treatment as Phase, distinct from the required semantic columns."""
+    if WELLENPLAN_START not in body or WELLENPLAN_END not in body:
+        return []
+    inner = body.split(WELLENPLAN_START, 1)[1].split(WELLENPLAN_END, 1)[0]
+    headers, rows = parse_pipe_table(inner.splitlines())
+    if not headers:
+        return []
+    idx = {name: col_index(headers, name) for name in WELLENPLAN_HEADERS}
+    i_phase = idx["Phase"]  # optional column — may be None
+    i_status = idx["Status"]  # optional column — may be None, defaults to ⬜
+    i_issue = idx["Issue"]  # optional column — may be None, defaults to no link
+    missing = [name for name in WELLENPLAN_HEADERS
+               if name not in ("Phase", "Status", "Issue") and idx[name] is None]
+    if missing:
+        raise ValueError(
+            f"Wellenplan table missing column(s) {', '.join(missing)} "
+            f"(headers: {headers})")
+    out: list[WaveRow] = []
+    for row in rows:
+        cell = lambda i: row[i].strip() if i is not None and i < len(row) else ""
+        covers, is_enabler = _parse_covers_cell(cell(idx["covers"]))
+        issue_m = re.search(r"#(\d+)", cell(i_issue))
+        out.append(WaveRow(
+            number=int(cell(idx["Welle"])),
+            name=cell(idx["Name"]),
+            phase=_none_if_blank(cell(i_phase)),
+            slice_ids=_split_csv(cell(idx["Slices"])),
+            gate=cell(idx["Gate"]) or "—",
+            covers=covers,
+            is_enabler=is_enabler,
+            status=cell(i_status) or "⬜",
+            issue=int(issue_m.group(1)) if issue_m else None,
+        ))
+    return out
+
+
+def render_wellenplan_table(waves: list[WaveRow], *, include_phase: bool = True) -> str:
+    """Render the Wellenplan table (markers + pipe table) — inverse of
+    `parse_wellenplan_table` (roundtrip pair). `Status` and `Issue` are always
+    emitted (both always present, unlike `Phase` which is toggled by
+    `include_phase`) — the two machine-written columns `program-sync` rewrites
+    (: `Issue` is the navigation link down to the promoted Wave-Anchor)."""
+    headers = [h for h in WELLENPLAN_HEADERS if include_phase or h != "Phase"]
+    rows = []
+    for w in waves:
+        covers_cell = _ENABLER if w.is_enabler else ", ".join(w.covers)
+        cells = {
+            "Welle": str(w.number),
+            "Status": w.status,
+            "Issue": f"#{w.issue}" if w.issue is not None else "—",
+            "Name": w.name,
+            "Phase": w.phase or "",
+            "Slices": ", ".join(w.slice_ids),
+            "Gate": w.gate,
+            "covers": covers_cell,
+        }
+        rows.append([cells[h] for h in headers])
+    table = render_pipe_table(headers, rows)
+    return f"{WELLENPLAN_START}\n{table}\n{WELLENPLAN_END}"
+
+
+SLICE_HEADING_RE = re.compile(r"^####\s+(\S+)\s+—\s+(.+)$")
+META_FIELD_RE = re.compile(r"^<!--\s*(wave|phase|area|gate|blocked_by):\s*(.*?)\s*-->$")
+
+
+def parse_slice_blocks(body: str) -> list[SliceBlock]:
+    """The `#### <local-id> — <Title>` sections of `## Slices`, each carrying a
+    5-field HTML-comment metadata block (SLICE-METADATA-FORMAT.md)."""
+    lines = (body or "").splitlines()
+    heads = []
+    for i, ln in enumerate(lines):
+        m = SLICE_HEADING_RE.match(ln.strip())
+        if m:
+            heads.append((i, m.group(1), m.group(2).strip()))
+    blocks: list[SliceBlock] = []
+    for idx, (start, local_id, title) in enumerate(heads):
+        end = heads[idx + 1][0] if idx + 1 < len(heads) else len(lines)
+        fields: dict[str, str] = {}
+        for ln in lines[start + 1:end]:
+            m = META_FIELD_RE.match(ln.strip())
+            if m:
+                fields[m.group(1)] = m.group(2)
+        wave_raw = fields.get("wave", "").strip()
+        blocked_raw = fields.get("blocked_by", "none").strip()
+        blocked_by = [] if blocked_raw.lower() in _NONE_TOKENS else _split_csv(blocked_raw)
+        blocks.append(SliceBlock(
+            local_id=local_id,
+            title=title,
+            wave=int(wave_raw) if wave_raw.isdigit() else None,
+            phase=_none_if_blank(fields.get("phase", "")),
+            area=(fields.get("area") or "").strip() or None,
+            gate=(fields.get("gate") or "").strip() or "—",
+            blocked_by=blocked_by,
+        ))
+    return blocks
+
+
+def render_slice_block(s: SliceBlock) -> str:
+    """Render one Slice section — inverse of the per-block parse in
+    `parse_slice_blocks` (roundtrip pair)."""
+    blocked = "none" if not s.blocked_by else ", ".join(s.blocked_by)
+    return (
+        f"#### {s.local_id} — {s.title}\n"
+        f"<!-- wave: {s.wave if s.wave is not None else ''} -->\n"
+        f"<!-- phase: {s.phase or '—'} -->\n"
+        f"<!-- area: {s.area or ''} -->\n"
+        f"<!-- gate: {s.gate} -->\n"
+        f"<!-- blocked_by: {blocked} -->\n"
+    )
+
+
+def parse_program_prd(body: str) -> ProgramGraph:
+    """The full ProgramGraph parsed from a Program-PRD issue body."""
+    return ProgramGraph(
+        plan_revision=parse_plan_revision(body),
+        scope_items=parse_scope_items(body),
+        waves=parse_wellenplan_table(body),
+        slices=parse_slice_blocks(body),
+        phase_gates=parse_phase_gates(body),
+    )