feat: add release CLI for deterministic data gathering

Add `release.py` CLI with 14 subcommands that extract deterministic work
(counting, URL-encoding, template filling) from agent workflows. The agent
calls the CLI first and adds judgment on top.

New scripts:
- release.py — argparse CLI: check, dates, future-dates, status, teams,
  team-breakdown, blockers, epics, cves, notes, slack {feature-freeze-update,
  feature-freeze, code-freeze-update, code-freeze}
- jql.py — parse 12 JQL templates from jql-release.md at runtime
- slack_templates.py — parse 4 Slack templates from slack-templates.md
- formatters.py — symlink to shared OutputFormatter

Updated:
- SKILL.md routing table: CLI command as primary, workflow as fallback
- All 13 workflows: Step 1 Run CLI added, manual steps kept as fallback
- check-structural.md: CLI existence check added (check 10)

Tests: 34 new unit tests for jql parsing, slack templates, CLI arg parsing,
acli count parsing. Showboat demo at tests/demo-release-cli.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: durandom

skills/rhdh-release/SKILL.md

@@ -83,21 +83,23 @@ What would you like to do?
 
 <routing>
 
-| Response | Workflow |
-|----------|----------|
-| 1, "release dates", "key dates", "freeze dates", "milestone dates" | Read `workflows/release-dates.md` and follow it |
-| 2, "future releases", "upcoming releases", "release roadmap", "future dates" | Read `workflows/future-release-dates.md` and follow it |
-| 3, "release status", "active releases", "release health", "release overview" | Read `workflows/release-status.md` and follow it |
-| 4, "teams", "team leads", "team list", "team contacts", "team directory" | Read `workflows/teams-and-leads.md` and follow it |
-| 5, "team breakdown", "issues by team", "team workload", "team counts" | Read `workflows/issues-by-team.md` and follow it |
-| 6, "blocker bugs", "blockers", "critical issues", "blocking issues" | Read `workflows/blocker-bugs.md` and follow it |
-| 7, "epics", "engineering epics", "open epics", "active epics" | Read `workflows/engineering-epics.md` and follow it |
-| 8, "cves", "vulnerabilities", "security issues", "security bugs" | Read `workflows/cves.md` and follow it |
-| 9, "release notes", "missing release notes", "release note gaps" | Read `workflows/release-notes.md` and follow it |
-| 10, "feature freeze update", "feature freeze status", "feature freeze progress" | Read `workflows/announce-feature-freeze-update.md` and follow it |
-| 11, "feature freeze announcement", "announce feature freeze", "feature freeze reached" | Read `workflows/announce-feature-freeze.md` and follow it |
-| 12, "code freeze update", "code freeze status", "code freeze progress" | Read `workflows/announce-code-freeze-update.md` and follow it |
-| 13, "code freeze announcement", "announce code freeze", "code freeze reached" | Read `workflows/announce-code-freeze.md` and follow it |
+**Preferred:** Run the `release` CLI first (`python scripts/release.py <command> --json`). If the CLI fails, fall back to the workflow's manual steps.
+
+| Response | CLI Command | Workflow (fallback) |
+|----------|-------------|---------------------|
+| 1, "release dates", "key dates", "freeze dates", "milestone dates" | `python scripts/release.py dates --json` | `workflows/release-dates.md` |
+| 2, "future releases", "upcoming releases", "release roadmap", "future dates" | `python scripts/release.py future-dates VERSION --json` | `workflows/future-release-dates.md` |
+| 3, "release status", "active releases", "release health", "release overview" | `python scripts/release.py status VERSION --json` | `workflows/release-status.md` |
+| 4, "teams", "team leads", "team list", "team contacts", "team directory" | `python scripts/release.py teams --json` | `workflows/teams-and-leads.md` |
+| 5, "team breakdown", "issues by team", "team workload", "team counts" | `python scripts/release.py team-breakdown VERSION --json` | `workflows/issues-by-team.md` |
+| 6, "blocker bugs", "blockers", "critical issues", "blocking issues" | `python scripts/release.py blockers VERSION --json` | `workflows/blocker-bugs.md` |
+| 7, "epics", "engineering epics", "open epics", "active epics" | `python scripts/release.py epics VERSION --json` | `workflows/engineering-epics.md` |
+| 8, "cves", "vulnerabilities", "security issues", "security bugs" | `python scripts/release.py cves VERSION --json` | `workflows/cves.md` |
+| 9, "release notes", "missing release notes", "release note gaps" | `python scripts/release.py notes VERSION --json` | `workflows/release-notes.md` |
+| 10, "feature freeze update", "feature freeze status", "feature freeze progress" | `python scripts/release.py slack feature-freeze-update VERSION --json` | `workflows/announce-feature-freeze-update.md` |
+| 11, "feature freeze announcement", "announce feature freeze", "feature freeze reached" | `python scripts/release.py slack feature-freeze VERSION --json` | `workflows/announce-feature-freeze.md` |
+| 12, "code freeze update", "code freeze status", "code freeze progress" | `python scripts/release.py slack code-freeze-update VERSION --json` | `workflows/announce-code-freeze-update.md` |
+| 13, "code freeze announcement", "announce code freeze", "code freeze reached" | `python scripts/release.py slack code-freeze VERSION --json` | `workflows/announce-code-freeze.md` |
 
 </routing>
 

skills/rhdh-release/scripts/formatters.py

@@ -0,0 +1 @@
+../../rhdh/rhdh/formatters.py

skills/rhdh-release/scripts/jql.py

@@ -0,0 +1,106 @@
+"""Parse JQL templates from references/jql-release.md.
+
+Reads the markdown file at runtime so the CLI and agent share one source of truth.
+Supports placeholder rendering ({{RELEASE_VERSION}}, {{ISSUE_TYPE}}) and
+URL-encoded Jira search links.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from urllib.parse import quote
+
+JIRA_SEARCH_BASE = "https://issues.redhat.com/issues/?jql="
+
+_REFERENCES_DIR = Path(__file__).resolve().parent.parent / "references"
+_JQL_FILE = _REFERENCES_DIR / "jql-release.md"
+
+_TEMPLATE_CACHE: dict[str, str] | None = None
+
+
+def _parse_jql_file(path: Path | None = None) -> dict[str, str]:
+    """Parse ## headings and ```jql code blocks from jql-release.md."""
+    path = path or _JQL_FILE
+    text = path.read_text()
+    templates: dict[str, str] = {}
+    current_name: str | None = None
+    jql_lines: list[str] | None = None
+
+    for line in text.splitlines():
+        heading = re.match(r"^##\s+(\S+)", line)
+        if heading:
+            current_name = heading.group(1)
+            continue
+
+        if current_name and line.strip() == "```jql":
+            jql_lines = []
+            continue
+
+        if current_name and jql_lines is not None and line.strip() == "```":
+            templates[current_name] = " ".join(jql_lines).strip()
+            current_name = None
+            jql_lines = None
+            continue
+
+        if jql_lines is not None:
+            jql_lines.append(line.strip())
+
+    return templates
+
+
+def load_templates(path: Path | None = None) -> dict[str, str]:
+    """Load and cache JQL templates from jql-release.md."""
+    global _TEMPLATE_CACHE
+    if path is not None:
+        return _parse_jql_file(path)
+    if _TEMPLATE_CACHE is None:
+        _TEMPLATE_CACHE = _parse_jql_file()
+    return _TEMPLATE_CACHE
+
+
+def get_template(name: str, path: Path | None = None) -> str:
+    """Get a single JQL template by name. Raises KeyError if not found."""
+    templates = load_templates(path)
+    if name not in templates:
+        available = ", ".join(sorted(templates))
+        raise KeyError(f"Unknown JQL template '{name}'. Available: {available}")
+    return templates[name]
+
+
+def render(
+    name: str,
+    *,
+    version: str | None = None,
+    issue_type: str | None = None,
+    path: Path | None = None,
+) -> str:
+    """Render a JQL template with placeholder substitution."""
+    jql = get_template(name, path)
+    if version is not None:
+        jql = jql.replace("{{RELEASE_VERSION}}", version)
+    if issue_type is not None:
+        jql = jql.replace("{{ISSUE_TYPE}}", issue_type)
+    return jql
+
+
+def jira_url(jql: str) -> str:
+    """Build a Jira search URL from a JQL string."""
+    return JIRA_SEARCH_BASE + quote(jql, safe="")
+
+
+def render_with_url(
+    name: str,
+    *,
+    version: str | None = None,
+    issue_type: str | None = None,
+    path: Path | None = None,
+) -> tuple[str, str]:
+    """Render a JQL template and return (jql, jira_url)."""
+    jql = render(name, version=version, issue_type=issue_type, path=path)
+    return jql, jira_url(jql)
+
+
+def list_templates(path: Path | None = None) -> list[str]:
+    """Return sorted list of available template names."""
+    return sorted(load_templates(path))