From 51d6e7b58285d4c3fd69839e7e1542ef31866236 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Mon, 24 Aug 2026 01:29:07 +0000
Subject: [PATCH] Add ready-for-dev issue and PR readiness gates

- .github/workflows/issue-readiness-check.yml: manages the ready-for-dev
  label on issues with type-specific criteria (bugs: reproducible command
  in Actual Behavior plus Acceptance Criteria checklist; enhancements:
  Desired Behavior plus Acceptance Criteria checklist). The readiness step
  emits JSON and always exits 0 so not-ready issues do not abort the
  workflow under set -euo pipefail; label add/remove and the feedback
  comment still run. Comments are upserted via a hidden marker so repeated
  runs update a single comment.
- .github/workflows/pr-description-check.yml: pull_request_target gate
  requiring the Why/Summary/How to Test template sections and blocking PRs
  whose linked issues lack ready-for-dev (pre-rollout issues grandfathered).
- .github/scripts/refresh_linked_pr_checks.py: re-runs the PR Description
  Check for open PRs linked to an issue when its ready-for-dev label
  changes, so the gate does not go stale.
- Tests for all three scripts under tests/.

Fixes #508

Co-authored-by: openhands <openhands@all-hands.dev>
---
 .github/scripts/check_issue_readiness.py    | 272 ++++++++++++++++++++
 .github/scripts/check_pr_description.py     | 226 ++++++++++++++++
 .github/scripts/post-readiness-comment.mjs  | 184 +++++++++++++
 .github/scripts/refresh_linked_pr_checks.py | 171 ++++++++++++
 .github/workflows/issue-readiness-check.yml | 142 ++++++++++
 .github/workflows/pr-description-check.yml  |  37 +++
 AGENTS.md                                   |   2 +
 tests/test_check_issue_readiness.py         | 135 ++++++++++
 tests/test_check_pr_description.py          | 228 ++++++++++++++++
 tests/test_refresh_linked_pr_checks.py      | 130 ++++++++++
 10 files changed, 1527 insertions(+)
 create mode 100644 .github/scripts/check_issue_readiness.py
 create mode 100644 .github/scripts/check_pr_description.py
 create mode 100644 .github/scripts/post-readiness-comment.mjs
 create mode 100644 .github/scripts/refresh_linked_pr_checks.py
 create mode 100644 .github/workflows/issue-readiness-check.yml
 create mode 100644 .github/workflows/pr-description-check.yml
 create mode 100644 tests/test_check_issue_readiness.py
 create mode 100644 tests/test_check_pr_description.py
 create mode 100644 tests/test_refresh_linked_pr_checks.py

diff --git a/.github/scripts/check_issue_readiness.py b/.github/scripts/check_issue_readiness.py
new file mode 100644
index 00000000..1707254b
--- /dev/null
+++ b/.github/scripts/check_issue_readiness.py
@@ -0,0 +1,272 @@
+"""Determine whether an issue meets the `ready-for-dev` readiness criteria.
+
+The criteria are type-specific and tailored to extension contributions
+(skills, plugins, integrations, and automations):
+
+- Bug reports (labeled `bug`): the Actual Behavior section must describe a
+  reproducible run and include a supported validation command (`uv`,
+  `pytest`, `python`, `pip`, `npm`, or `node`), plus a non-empty Acceptance
+  Criteria section with at least one checklist item.
+
+- Enhancements (labeled `enhancement`): the body must contain non-empty
+  Desired Behavior and Acceptance Criteria sections, the latter with at
+  least one checklist item.
+
+GitHub issue forms render each field as an `### <Label>` (h3) heading followed
+by the field text, with empty optional fields rendered as `_No response_`. This
+parser splits the body on those headings so each criterion is checked against
+the right field rather than the whole body.
+
+Local usage:
+
+    python .github/scripts/check_issue_readiness.py --body-file /tmp/issue.md \
+        --labels bug
+    python .github/scripts/check_issue_readiness.py --event-path "$GITHUB_EVENT_PATH"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+BUG_LABEL = "bug"
+ENHANCEMENT_LABEL = "enhancement"
+
+# Issue-form fields render as `### Label` h3 headings. Match case-insensitively
+# and tolerate trailing whitespace/colons. `^###\s+` is specific enough because
+# h1/h2 are not produced by issue forms.
+HEADING_RE = re.compile(r"(?m)^###\s+(.+?)\s*$")
+
+# `_No response_` is what GitHub writes for an empty optional form field.
+NO_RESPONSE = "_No response_"
+
+# A reproducible command must appear in the Actual Behavior section. These are
+# the commands a contributor can run in this repository: the Python test
+# tooling (`uv run pytest`, `pytest`, `python`, `pip`) and the catalog build /
+# validation tooling (`npm run build:*`, `node`).
+RUN_METHOD_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\bpython\b", re.IGNORECASE),
+    re.compile(r"\bpytest\b", re.IGNORECASE),
+    re.compile(r"\buv\b", re.IGNORECASE),
+    re.compile(r"\bpip\b", re.IGNORECASE),
+    re.compile(r"\bnpm\b", re.IGNORECASE),
+    re.compile(r"\bnode\b", re.IGNORECASE),
+)
+
+# An Acceptance Criteria item is a markdown checklist bullet (`- [ ]` or
+# `- [x]`). We require at least one so the section is verifiable.
+CHECKLIST_ITEM_RE = re.compile(r"(?m)^\s*[-*]\s*\[[ xX]\]")
+
+
+@dataclass
+class ReadinessResult:
+    """Outcome of a readiness check."""
+
+    ready: bool
+    reasons: list[str] = field(default_factory=list)
+
+    def add(self, reason: str) -> None:
+        self.reasons.append(reason)
+        self.ready = False
+
+
+def visible_text(text: str) -> str:
+    """Return field text with HTML comments stripped and emptiness normalized."""
+    cleaned = re.sub(r"<!--[\s\S]*?-->", "", text).strip()
+    if cleaned == NO_RESPONSE:
+        return ""
+    return cleaned
+
+
+def extract_sections(body: str) -> dict[str, str]:
+    """Split the body into a {heading: text} map using `### <heading>` boundaries.
+
+    Issue forms render every field this way. Free-form issues (not created via a
+    form) may still use `###` headings; if they don't, the map is empty and the
+    caller falls back to whole-body checks.
+    """
+    matches = list(HEADING_RE.finditer(body))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
+        sections[match.group(1).strip().lower()] = body[start:end]
+    return sections
+
+
+def find_section(sections: dict[str, str], *labels: str) -> str:
+    """Return the first matching section text by case-insensitive label."""
+    for label in labels:
+        if label in sections:
+            return sections[label]
+    return ""
+
+
+def references_run_method(text: str) -> bool:
+    return any(pattern.search(text) for pattern in RUN_METHOD_PATTERNS)
+
+
+def has_checklist_item(text: str) -> bool:
+    return bool(CHECKLIST_ITEM_RE.search(text))
+
+
+def check_bug(sections: dict[str, str]) -> ReadinessResult:
+    result = ReadinessResult(ready=True)
+
+    actual = visible_text(find_section(sections, "actual behavior", "actual"))
+    if not actual:
+        result.add(
+            "Fill in the `### Actual Behavior` section with reproducible steps "
+            "and the observed result."
+        )
+    elif not references_run_method(actual):
+        result.add(
+            "The Actual Behavior section must include a reproducible command "
+            "such as `uv run pytest`, `pytest`, `python`, `pip`, `npm run`, "
+            "or `node`."
+        )
+
+    acceptance = visible_text(
+        find_section(sections, "acceptance criteria", "acceptance")
+    )
+    if not acceptance:
+        result.add(
+            "Add an `### Acceptance Criteria` section with testable checklist items."
+        )
+    elif not has_checklist_item(acceptance):
+        result.add(
+            "The Acceptance Criteria section must contain at least one checklist item "
+            "(`- [ ] ...`)."
+        )
+
+    return result
+
+
+def check_enhancement(sections: dict[str, str]) -> ReadinessResult:
+    result = ReadinessResult(ready=True)
+
+    desired = visible_text(find_section(sections, "desired behavior", "desired"))
+    if not desired:
+        result.add(
+            "Add a `### Desired Behavior` section describing the behavior you want."
+        )
+
+    acceptance = visible_text(
+        find_section(sections, "acceptance criteria", "acceptance")
+    )
+    if not acceptance:
+        result.add(
+            "Add an `### Acceptance Criteria` section with testable checklist items."
+        )
+    elif not has_checklist_item(acceptance):
+        result.add(
+            "The Acceptance Criteria section must contain at least one checklist item "
+            "(`- [ ] ...`)."
+        )
+
+    return result
+
+
+def evaluate_readiness(body: str, labels: list[str]) -> ReadinessResult:
+    """Return the readiness result for an issue body + label set.
+
+    An issue is only a candidate when it carries the `bug` or `enhancement`
+    label. If it has neither, it is treated as not-ready-for-dev (the gate does
+    not apply a label it cannot validate).
+    """
+    label_set = {label.lower() for label in labels}
+    sections = extract_sections(body or "")
+
+    if BUG_LABEL in label_set:
+        return check_bug(sections)
+    if ENHANCEMENT_LABEL in label_set:
+        return check_enhancement(sections)
+
+    return ReadinessResult(
+        ready=False,
+        reasons=[
+            "The issue has neither the `bug` nor `enhancement` label, so its "
+            "readiness criteria cannot be evaluated. Add the appropriate label."
+        ],
+    )
+
+
+def body_and_labels_from_event(event_path: Path) -> tuple[str, list[str]]:
+    payload = json.loads(event_path.read_text())
+    issue = payload.get("issue") or payload.get("pull_request")
+    if not isinstance(issue, dict):
+        raise ValueError("GitHub event payload does not contain an issue object")
+    body = issue.get("body")
+    body = body if isinstance(body, str) else ""
+    labels = [
+        label["name"] for label in issue.get("labels", []) if isinstance(label, dict)
+    ]
+    return body, labels
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Evaluate whether an issue meets the ready-for-dev criteria."
+    )
+    parser.add_argument(
+        "--body-file", type=Path, help="Read the issue body from a file."
+    )
+    parser.add_argument(
+        "--labels",
+        help="Comma-separated issue labels (e.g. 'bug,skills').",
+        default="",
+    )
+    parser.add_argument(
+        "--event-path",
+        type=Path,
+        default=Path(os.environ["GITHUB_EVENT_PATH"])
+        if "GITHUB_EVENT_PATH" in os.environ
+        else None,
+        help="Read body and labels from a GitHub event payload.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit a JSON result instead of human-readable text.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    if args.body_file is not None:
+        body = args.body_file.read_text()
+        labels = [label.strip() for label in args.labels.split(",") if label.strip()]
+    elif args.event_path is not None:
+        body, labels = body_and_labels_from_event(args.event_path)
+    else:
+        raise SystemExit("Pass --body-file or set GITHUB_EVENT_PATH.")
+
+    result = evaluate_readiness(body, labels)
+
+    if args.json:
+        print(json.dumps({"ready": result.ready, "reasons": result.reasons}))
+        # In --json mode the exit code is not meaningful: the result is consumed
+        # via the printed JSON, and the workflow must run to completion for both
+        # ready and not-ready issues (label add/remove, feedback comment).
+        return 0
+
+    if result.ready:
+        print("Issue meets ready-for-dev criteria.")
+    else:
+        print("Issue does not meet ready-for-dev criteria:")
+        for reason in result.reasons:
+            print(f"  - {reason}")
+
+    return 0 if result.ready else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/scripts/check_pr_description.py b/.github/scripts/check_pr_description.py
new file mode 100644
index 00000000..9a72a133
--- /dev/null
+++ b/.github/scripts/check_pr_description.py
@@ -0,0 +1,226 @@
+"""Validate a pull request description against the repository PR template.
+
+Two gates:
+
+1. Template sections: the `## Why`, `## Summary`, and `## How to Test`
+   sections from `.github/pull_request_template.md` must be present and
+   filled in.
+
+2. Linked-issue readiness: every issue linked via a closing keyword
+   (`Fixes #123`, `Closes #123`, `Resolves #123`) or referenced in the
+   `## Issue Number` section must exist and, unless it predates the
+   `ready-for-dev` rollout, carry the `ready-for-dev` label. This blocks
+   PRs until their linked issue meets the readiness criteria.
+
+Local usage:
+
+    python .github/scripts/check_pr_description.py --body-file /tmp/pr.md
+    GITHUB_TOKEN=... python .github/scripts/check_pr_description.py \
+        --event-path "$GITHUB_EVENT_PATH"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+# These are the only PR-template sections that must remain and contain content.
+REQUIRED_TEMPLATE_FIELDS: tuple[str, ...] = ("Why", "Summary", "How to Test")
+
+HTML_COMMENT_RE = re.compile(r"<!--[\s\S]*?-->")
+HEADING_RE = re.compile(r"(?m)^##\s+(.+?)\s*$")
+ISSUE_REF_RE = re.compile(r"(?i)\b(?:fix|clos|resolv)(?:e?(?:s|d)?|ing)?\s+#(\d+)")
+BARE_ISSUE_REF_RE = re.compile(r"(?<!\w)#(\d+)")
+READY_FOR_DEV_LABEL = "ready-for-dev"
+# Issues created before the `ready-for-dev` rollout are grandfathered: the
+# issue-readiness workflow only labels issues on `issues` events, so long-open
+# issues were never evaluated. Requiring the label retroactively would block
+# existing PRs linked to those issues. The cutoff is the UTC day AFTER the
+# rollout/deployment day (2026-08-24), so every issue predating deployment -
+# including ones opened earlier that same day, before the workflow existed -
+# is exempt. Issues created on or after 2026-08-25 must carry the label.
+READY_FOR_DEV_ROLLOUT_ISO = "2026-08-25"
+
+
+def visible_text(text: str) -> str:
+    """Return PR body content that should count as author-provided text."""
+    lines = []
+    for line in HTML_COMMENT_RE.sub("", text).splitlines():
+        stripped = line.strip()
+        if stripped and stripped != "-":
+            lines.append(stripped)
+    return "\n".join(lines).strip()
+
+
+def extract_sections(body: str) -> dict[str, str]:
+    matches = list(HEADING_RE.finditer(body))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
+        sections[match.group(1).strip()] = body[start:end]
+    return sections
+
+
+def extract_linked_issue_numbers(body: str) -> list[int]:
+    numbers: list[int] = []
+    seen: set[int] = set()
+    for match in ISSUE_REF_RE.finditer(body):
+        number = int(match.group(1))
+        if number not in seen:
+            numbers.append(number)
+            seen.add(number)
+
+    sections = extract_sections(body)
+    issue_section = sections.get("Issue Number", "")
+    for match in BARE_ISSUE_REF_RE.finditer(issue_section):
+        number = int(match.group(1))
+        if number not in seen:
+            numbers.append(number)
+            seen.add(number)
+    return numbers
+
+
+def fetch_issue_details(
+    repo: str, issue_number: int, token: str
+) -> tuple[list[str], str]:
+    """Return an issue's (labels, created_at) from the GitHub API."""
+    request = urllib.request.Request(
+        f"https://api.github.com/repos/{repo}/issues/{issue_number}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+        },
+    )
+    with urllib.request.urlopen(request, timeout=10) as response:  # noqa: S310 - trusted HTTPS API
+        issue = json.loads(response.read().decode())
+    labels = [
+        label["name"] for label in issue.get("labels", []) if isinstance(label, dict)
+    ]
+    created_at = issue.get("created_at", "")
+    return labels, created_at
+
+
+def validate_linked_issue_ready(
+    body: str, repo: str | None = None, token: str | None = None
+) -> list[str]:
+    numbers = extract_linked_issue_numbers(body)
+    if not numbers:
+        return [
+            "Link an issue in the `## Issue Number` section (e.g. `Fixes #123`). "
+            "Newly opened issues must carry the `ready-for-dev` label."
+        ]
+    if not repo or not token:
+        return []
+
+    checked: list[int] = []
+    not_ready_new: list[int] = []
+    for number in numbers:
+        try:
+            labels, created_at = fetch_issue_details(repo, number, token)
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                continue
+            raise
+        checked.append(number)
+        if READY_FOR_DEV_LABEL in (label.lower() for label in labels):
+            continue
+        if created_at[:10] < READY_FOR_DEV_ROLLOUT_ISO:
+            # Predates the rollout; grandfathered to avoid retroactive blocking.
+            continue
+        not_ready_new.append(number)
+
+    if not checked:
+        refs = ", ".join(f"#{number}" for number in numbers)
+        return [f"Referenced issue(s) {refs} could not be found in this repository."]
+    if not_ready_new:
+        refs = ", ".join(f"#{number}" for number in not_ready_new)
+        return [
+            f"Linked issue(s) ({refs}) carry neither `ready-for-dev` nor a "
+            "pre-rollout creation date. Newly referenced issues must meet the "
+            "readiness criteria before a PR can be opened."
+        ]
+    return []
+
+
+def validate_pr_body(body: str) -> list[str]:
+    errors: list[str] = []
+
+    sections = extract_sections(body)
+    for section in REQUIRED_TEMPLATE_FIELDS:
+        if section not in sections:
+            errors.append(f"Keep the `## {section}` section from the PR template.")
+        elif not visible_text(sections[section]):
+            errors.append(f"Fill in the `## {section}` section of the PR template.")
+
+    return errors
+
+
+def body_from_event(event_path: Path) -> tuple[str, str | None]:
+    """Return the (pull request body, repository full name) from an event payload."""
+    payload = json.loads(event_path.read_text())
+    pull_request = payload.get("pull_request")
+    if not isinstance(pull_request, dict):
+        raise ValueError("GitHub event payload does not contain a pull_request object")
+    body = pull_request.get("body")
+    body = body if isinstance(body, str) else ""
+    repo = payload.get("repository", {}).get("full_name")
+    return body, repo if isinstance(repo, str) else None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Validate pull request description readiness from --body-file "
+            "or a GitHub event payload."
+        )
+    )
+    parser.add_argument(
+        "--body-file", type=Path, help="Read a PR description body from a file."
+    )
+    parser.add_argument(
+        "--event-path",
+        type=Path,
+        default=Path(os.environ["GITHUB_EVENT_PATH"])
+        if "GITHUB_EVENT_PATH" in os.environ
+        else None,
+        help="Read the PR description body from a GitHub event payload.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.body_file is not None:
+        body = args.body_file.read_text()
+        repo = None
+    elif args.event_path is not None:
+        body, repo = body_from_event(args.event_path)
+    else:
+        raise SystemExit("Pass --body-file or set GITHUB_EVENT_PATH.")
+
+    errors = validate_pr_body(body)
+
+    token = os.environ.get("GITHUB_TOKEN")
+    errors.extend(validate_linked_issue_ready(body, repo, token))
+
+    for error in errors:
+        print(f"::error::{error}")
+
+    if errors:
+        print(f"PR description validation failed with {len(errors)} error(s).")
+        return 1
+
+    print("PR description validation passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/scripts/post-readiness-comment.mjs b/.github/scripts/post-readiness-comment.mjs
new file mode 100644
index 00000000..145cb3b5
--- /dev/null
+++ b/.github/scripts/post-readiness-comment.mjs
@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+/**
+ * Post (or update) a `ready-for-dev` readiness comment on an issue.
+ *
+ * Upserts by a hidden HTML marker so repeated runs update the same comment
+ * instead of spamming duplicates. Uses the GITHUB_TOKEN available to the
+ * workflow via the GH_TOKEN env var.
+ *
+ * Usage:
+ *   node post-readiness-comment.mjs \
+ *     --issue-number 123 \
+ *     --repo OpenHands/extensions \
+ *     --reasons-file /tmp/reasons.txt \
+ *     --ready           # optional: post a "ready" message instead of "not ready"
+ */
+
+import { readFileSync } from "node:fs";
+
+const MARKER = "<!-- issue-readiness-check -->";
+const API_ROOT = process.env.GITHUB_API_URL ?? "https://api.github.com";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      i += 1;
+    } else {
+      args[key] = "";
+    }
+  }
+  return args;
+}
+
+function requireValue(name, value) {
+  if (!value) throw new Error(`Missing required value: ${name}`);
+  return value;
+}
+
+async function listComments(repo, issueNumber, token) {
+  // Paginate through all comments so the marker is found even on issues
+  // with >100 comments.
+  const all = [];
+  let page = 1;
+  while (true) {
+    const url = `${API_ROOT}/repos/${repo}/issues/${issueNumber}/comments?per_page=100&page=${page}`;
+    const resp = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    });
+    if (!resp.ok) {
+      throw new Error(`Failed to list comments: ${resp.status} ${await resp.text()}`);
+    }
+    const batch = await resp.json();
+    all.push(...batch);
+    if (batch.length < 100) break;
+    page += 1;
+  }
+  return all;
+}
+
+async function createComment(repo, issueNumber, body, token) {
+  const url = `${API_ROOT}/repos/${repo}/issues/${issueNumber}/comments`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ body }),
+  });
+  if (!resp.ok) {
+    throw new Error(`Failed to create comment: ${resp.status} ${await resp.text()}`);
+  }
+  return resp.json();
+}
+
+async function updateComment(repo, commentId, body, token) {
+  const url = `${API_ROOT}/repos/${repo}/issues/comments/${commentId}`;
+  const resp = await fetch(url, {
+    method: "PATCH",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ body }),
+  });
+  if (!resp.ok) {
+    throw new Error(`Failed to update comment: ${resp.status} ${await resp.text()}`);
+  }
+  return resp.json();
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const issueNumber = requireValue("issue-number", args.issue_number);
+  const repo = requireValue("repo", args.repo);
+  const token = process.env.GH_TOKEN;
+  if (!token) throw new Error("GH_TOKEN env var is required");
+
+  const isReady = args.ready === "" || args.ready === "true";
+  const reasonsFile = args.reasons_file || args.reasons;
+  const reasons = reasonsFile
+    ? readFileSync(reasonsFile, "utf8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+    : [];
+
+  const reasonList = reasons.length
+    ? reasons.map((r) => `- ${r}`).join("\n")
+    : "- The issue does not meet the ready-for-dev criteria.";
+
+  const body = isReady
+    ? [
+        MARKER,
+        "### \u2705 `ready-for-dev` label applied",
+        "",
+        "This issue meets the readiness criteria and is ready for contribution.",
+        "A contributor can now open a PR that links this issue (`Fixes #<number>`).",
+        "",
+        "_This is an automated readiness check posted by a workflow._",
+      ].join("\n")
+    : [
+        MARKER,
+        "### \u26a0\ufe0f Not yet `ready-for-dev`",
+        "",
+        "This issue does not yet meet the readiness criteria, so the",
+        "`ready-for-dev` label has not been applied (or has been removed).",
+        "The criteria are type-specific:",
+        "",
+        "**Bug reports** (`bug` label):",
+        "- The `### Actual Behavior` section must describe reproducible steps",
+        "  and include a command such as `uv run pytest`, `pytest`, `python`,",
+        "  `pip`, `npm run`, or `node`.",
+        "- An `### Acceptance Criteria` section with at least one checklist item (`- [ ] ...`).",
+        "",
+        "**Enhancements** (`enhancement` label):",
+        "- A `### Desired Behavior` section.",
+        "- An `### Acceptance Criteria` section with at least one checklist item.",
+        "",
+        "What is missing:",
+        "",
+        reasonList,
+        "",
+        "Edit the issue to address the gaps and the `ready-for-dev` label will be",
+        "applied automatically.",
+        "",
+        "_This is an automated readiness check posted by a workflow._",
+      ].join("\n");
+
+  const comments = await listComments(repo, issueNumber, token);
+  const existing = comments.find((comment) => comment.body?.includes(MARKER));
+
+  if (existing) {
+    await updateComment(repo, existing.id, body, token);
+    console.log(`Updated readiness comment ${existing.id} on issue #${issueNumber}`);
+  } else {
+    const created = await createComment(repo, issueNumber, body, token);
+    console.log(`Created readiness comment ${created.id} on issue #${issueNumber}`);
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/.github/scripts/refresh_linked_pr_checks.py b/.github/scripts/refresh_linked_pr_checks.py
new file mode 100644
index 00000000..694c01cc
--- /dev/null
+++ b/.github/scripts/refresh_linked_pr_checks.py
@@ -0,0 +1,171 @@
+"""Re-run the PR Description Check for open PRs linked to an issue.
+
+Invoked from the issue-readiness workflow when the `ready-for-dev` label is
+added to or removed from an issue, so the PR gate reflects the settled
+readiness state without waiting for the next PR event.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from check_pr_description import extract_linked_issue_numbers
+
+
+def _run(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(args, capture_output=True, text=True, check=False)
+
+
+def _linked_open_prs(repo: str, issue_number: int) -> list[dict]:
+    """Return open PRs that cross-reference ``issue_number``."""
+    owner, name = repo.split("/", 1)
+    query = """
+query($owner: String!, $name: String!, $num: Int!) {
+  repository(owner: $owner, name: $name) {
+    issue(number: $num) {
+      timelineItems(first: 100, itemTypes: [CROSS_REFERENCED_EVENT]) {
+        nodes {
+          __typename
+          ... on CrossReferencedEvent {
+            source {
+              __typename
+              ... on PullRequest { number headRefOid state }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+"""
+    result = _run(
+        [
+            "gh",
+            "api",
+            "graphql",
+            "-f",
+            f"query={query}",
+            "-F",
+            f"owner={owner}",
+            "-F",
+            f"name={name}",
+            "-F",
+            f"num={issue_number}",
+            "--jq",
+            ".data.repository.issue.timelineItems.nodes",
+        ]
+    )
+    if result.returncode != 0:
+        print(f"::warning::Could not query linked PRs: {result.stderr.strip()}")
+        return []
+    try:
+        nodes = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        print(f"::warning::Unexpected linked-PR query output: {exc}")
+        return []
+    prs = []
+    for node in nodes:
+        source = node.get("source") if isinstance(node, dict) else None
+        if not isinstance(source, dict):
+            continue
+        if source.get("__typename") != "PullRequest":
+            continue
+        if source.get("state") != "OPEN":
+            continue
+        prs.append(source)
+    return prs
+
+
+def _rerun_pr_description_check(repo: str, head_sha: str) -> bool:
+    """Re-run the latest PR Description Check for the given head SHA."""
+    runs_result = _run(
+        [
+            "gh",
+            "api",
+            "-X",
+            "GET",
+            f"repos/{repo}/actions/runs",
+            "-f",
+            f"head_sha={head_sha}",
+            "-f",
+            "per_page=100",
+            "--jq",
+            r'.workflow_runs[] | select(.name=="PR Description Check") | '
+            r'select(.event=="pull_request_target") | "\(.id) \(.created_at)"',
+        ]
+    )
+    if runs_result.returncode != 0:
+        print(f"::warning::Could not list PR checks: {runs_result.stderr.strip()}")
+        return False
+    lines = [line.split() for line in runs_result.stdout.splitlines() if line.strip()]
+    if not lines:
+        return False
+    # Created-at is sortable; pick the most recent run for this commit.
+    latest = sorted(lines, key=lambda item: " ".join(item[1:]))[-1][0]
+    rerun = _run(
+        ["gh", "api", "-X", "POST", f"repos/{repo}/actions/runs/{latest}/rerun"]
+    )
+    if rerun.returncode != 0:
+        print(
+            f"::warning::Could not re-run PR description check ({latest}): "
+            f"{rerun.stderr.strip()}"
+        )
+        return False
+    print(f"Re-ran PR description check (run {latest}) for linked open PR.")
+    return True
+
+
+def main() -> int:
+    payload = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text())
+    if {"action", "issue", "label", "repository"} - set(payload):
+        return 0
+    action = payload["action"]
+    raw_label = payload.get("label")
+    label = raw_label.get("name") if isinstance(raw_label, dict) else None
+    if action not in ("labeled", "unlabeled") or label != "ready-for-dev":
+        return 0
+    raw_repo = payload.get("repository")
+    repo = raw_repo.get("full_name") if isinstance(raw_repo, dict) else None
+    raw_issue = payload.get("issue")
+    issue_number = raw_issue.get("number") if isinstance(raw_issue, dict) else None
+    if not repo or not issue_number:
+        return 0
+
+    print(
+        f"ready-for-dev {action}: refreshing PR gates linked to issue #{issue_number}."
+    )
+    refreshed = 0
+    for pr in _linked_open_prs(repo, issue_number):
+        pr_number = pr["number"]
+        body_result = _run(
+            [
+                "gh",
+                "pr",
+                "view",
+                str(pr_number),
+                "--repo",
+                repo,
+                "--json",
+                "body",
+                "--jq",
+                ".body",
+            ]
+        )
+        if body_result.returncode != 0:
+            continue
+        if issue_number not in extract_linked_issue_numbers(body_result.stdout):
+            # Cross-referenced but not treated as a linked issue by the gate;
+            # nothing to refresh.
+            continue
+        if _rerun_pr_description_check(repo, pr["headRefOid"]):
+            refreshed += 1
+    print(f"Refreshed PR gates for {refreshed} linked PR(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/workflows/issue-readiness-check.yml b/.github/workflows/issue-readiness-check.yml
new file mode 100644
index 00000000..15a3ddba
--- /dev/null
+++ b/.github/workflows/issue-readiness-check.yml
@@ -0,0 +1,142 @@
+---
+name: Issue Readiness Check
+
+# Manages the `ready-for-dev` label based on type-specific readiness criteria
+# tailored to extension contributions (skills, plugins, integrations,
+# automations).
+#
+# Bug reports (label `bug`): the Actual Behavior section must reference a
+# reproducible command (`uv run pytest`, `pytest`, `python`, `pip`, `npm run`,
+# or `node`), plus an Acceptance Criteria section with at least one checklist
+# item.
+#
+# Enhancements (label `enhancement`): the body must contain Desired Behavior and
+# Acceptance Criteria sections, the latter with at least one checklist item.
+#
+# When criteria are met the label is added (idempotently); when they are not the
+# label is removed. A feedback comment is posted (or updated) in three cases:
+#   1. The issue is first opened or reopened - always comment so the author
+#      knows whether their issue is ready or what is missing.
+#   2. The label is being added (issue became ready) - comment celebrating it.
+#   3. The label is being removed (issue was ready but is no longer) - comment
+#      explaining what changed.
+# Edits that do not change the label state do not produce a new comment. All
+# comments are upserted by a hidden marker so there is at most one per issue.
+#
+# The readiness step uses `--json`, which always exits 0, so a not-ready result
+# never aborts the workflow under `set -euo pipefail`; label and comment steps
+# run for both outcomes.
+
+on:
+    issues:
+        types: [opened, edited, reopened, labeled, unlabeled]
+
+permissions:
+    issues: write
+    pull-requests: read
+    contents: read
+
+concurrency:
+    group: issue-readiness-${{ github.event.issue.number }}
+    cancel-in-progress: false
+
+jobs:
+    check:
+        if: github.event.issue.state == 'open' && github.event.issue.pull_request == null
+        runs-on: ubuntu-latest
+        timeout-minutes: 5
+        steps:
+            - name: Checkout trusted workflow scripts
+              uses: actions/checkout@v4
+
+            - name: Evaluate issue readiness
+              id: readiness
+              env:
+                  GITHUB_EVENT_PATH: ${{ github.event_path }}
+              run: |
+                  set -euo pipefail
+                  python .github/scripts/check_issue_readiness.py --json > /tmp/result.json
+                  echo "ready=$(jq -r '.ready' /tmp/result.json)" >> "$GITHUB_OUTPUT"
+                  # Write reasons to a file so the comment step can read them
+                  # without shell-escaping multiline text.
+                  jq -r '.reasons[]?' /tmp/result.json > /tmp/reasons.txt || true
+                  echo "reasons_file=/tmp/reasons.txt" >> "$GITHUB_OUTPUT"
+
+            - name: Add ready-for-dev label
+              if: steps.readiness.outputs.ready == 'true'
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: |
+                  set -euo pipefail
+                  # Capture stderr — tolerate "label already present" (exit 0
+                  # from gh) but surface unexpected errors to the step summary.
+                  if ! gh issue edit "${{ github.event.issue.number }}" \
+                      --repo "${{ github.repository }}" \
+                      --add-label "ready-for-dev" 2>/tmp/gh-err.txt; then
+                    echo "::warning::Failed to add ready-for-dev label:" >> "$GITHUB_STEP_SUMMARY"
+                    cat /tmp/gh-err.txt >> "$GITHUB_STEP_SUMMARY"
+                  fi
+
+            - name: Remove ready-for-dev label
+              if: steps.readiness.outputs.ready != 'true' && contains(github.event.issue.labels.*.name, 'ready-for-dev')
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: |
+                  set -euo pipefail
+                  # Capture stderr — tolerate "label already removed" but
+                  # surface unexpected errors.
+                  if ! gh issue edit "${{ github.event.issue.number }}" \
+                      --repo "${{ github.repository }}" \
+                      --remove-label "ready-for-dev" 2>/tmp/gh-err.txt; then
+                    echo "::warning::Failed to remove ready-for-dev label:" >> "$GITHUB_STEP_SUMMARY"
+                    cat /tmp/gh-err.txt >> "$GITHUB_STEP_SUMMARY"
+                  fi
+
+            - name: Post feedback comment
+              if: >-
+                  github.event.action == 'opened'
+                  || github.event.action == 'reopened'
+                  || (steps.readiness.outputs.ready == 'true' && !contains(github.event.issue.labels.*.name, 'ready-for-dev'))
+                  || (steps.readiness.outputs.ready != 'true' && contains(github.event.issue.labels.*.name, 'ready-for-dev'))
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: |
+                  set -euo pipefail
+                  if [ "${{ steps.readiness.outputs.ready }}" = "true" ]; then
+                    node .github/scripts/post-readiness-comment.mjs \
+                        --issue-number "${{ github.event.issue.number }}" \
+                        --repo "${{ github.repository }}" \
+                        --ready
+                  else
+                    node .github/scripts/post-readiness-comment.mjs \
+                        --issue-number "${{ github.event.issue.number }}" \
+                        --repo "${{ github.repository }}" \
+                        --reasons-file "${{ steps.readiness.outputs.reasons_file }}"
+                  fi
+
+    # When the ready-for-dev label is added or removed, re-run the PR
+    # description check for every open PR that links this issue, so the
+    # `ready-for-dev` gate does not go stale between PR events. Runs after
+    # `check` so the label reflects the settled readiness state.
+    refresh-linked-pr-gates:
+        name: Refresh PR gates for linked issues
+        needs: check
+        if: >-
+            github.event.issue.state == 'open'
+            && github.event.issue.pull_request == null
+            && (github.event.action == 'labeled' || github.event.action == 'unlabeled')
+            && github.event.label.name == 'ready-for-dev'
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        permissions:
+            contents: read
+            pull-requests: read
+            actions: write
+        steps:
+            - name: Checkout trusted workflow scripts
+              uses: actions/checkout@v4
+
+            - name: Re-run PR description checks for linked open PRs
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: python .github/scripts/refresh_linked_pr_checks.py
diff --git a/.github/workflows/pr-description-check.yml b/.github/workflows/pr-description-check.yml
new file mode 100644
index 00000000..e80ace92
--- /dev/null
+++ b/.github/workflows/pr-description-check.yml
@@ -0,0 +1,37 @@
+---
+name: PR Description Check
+
+# Use pull_request_target so fork PR descriptions can be checked, but only run
+# trusted validation code from the base branch checkout below.
+
+on:
+    pull_request_target:
+        types: [opened, edited, reopened, ready_for_review, synchronize]
+
+permissions:
+    contents: read
+    pull-requests: read
+    issues: read
+
+jobs:
+    validate-pr-description:
+        name: Validate PR description
+        # Draft PRs may still have incomplete descriptions; validate when review starts.
+        # Release PRs are generated by the trusted prepare-release workflow without
+        # the standard human-authored PR template.
+        if: >-
+            github.event.pull_request.draft == false &&
+            github.event.pull_request.user.login != 'dependabot[bot]' &&
+            !(github.event.pull_request.head.repo.full_name == github.repository &&
+            startsWith(github.event.pull_request.head.ref, 'release-please-'))
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout trusted workflow scripts
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.base.sha }}
+
+            - name: Validate PR template sections and linked-issue readiness
+              env:
+                  GITHUB_TOKEN: ${{ github.token }}
+              run: python .github/scripts/check_pr_description.py
diff --git a/AGENTS.md b/AGENTS.md
index 41cb7712..6813a72c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -124,6 +124,8 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - `scripts/sync_extensions.py` keeps generated artifacts in sync: Claude Code command files, README catalog section, coverage checks, and vendor symlinks. Run `python scripts/sync_extensions.py --check` (or just push — CI runs it) to verify everything is consistent. Run without `--check` to auto-fix. The "Quick Start" section in `README.md` (OpenHands SDK, Claude Code, and Codex setup instructions) is **manually maintained** above the auto-generated catalog markers and is intentionally not generated by the sync script.
 - The sync script uses PyYAML to parse SKILL.md frontmatter. If you add a skill with a slash trigger (e.g., `triggers: ["/mycommand"]`), the script auto-generates `commands/mycommand.md`. **Note:** Slash triggers in SKILL.md frontmatter are deprecated — prefer adding a `commands/command-name.md` file to the plugin's `commands/` directory instead. Keyword triggers (non-slash) remain the recommended way to activate skills by topic.
 
+- The `ready-for-dev` gates live in `.github/workflows/issue-readiness-check.yml` and `.github/workflows/pr-description-check.yml`, backed by `.github/scripts/check_issue_readiness.py`, `check_pr_description.py`, `refresh_linked_pr_checks.py`, and `post-readiness-comment.mjs`. Issues labeled `bug` or `enhancement` must meet type-specific readiness criteria (reproducible command plus Acceptance Criteria checklist for bugs; Desired Behavior plus Acceptance Criteria checklist for enhancements) to receive the `ready-for-dev` label. Non-draft PRs must keep the `## Why`, `## Summary`, and `## How to Test` template sections filled, and any issue linked via a closing keyword or the `## Issue Number` section must carry `ready-for-dev` unless it predates the 2026-08-25 rollout. Label transitions on an issue re-run the PR Description Check for linked open PRs. Tests live in `tests/test_check_issue_readiness.py`, `tests/test_check_pr_description.py`, and `tests/test_refresh_linked_pr_checks.py`.
+
 ## OpenHands SDK documentation policy
 
 - **Do NOT add SDK-specific or SDK-related documentation to this repo.** The canonical source of truth for SDK documentation is the [OpenHands docs site](https://docs.openhands.dev/sdk) and its structured index at <https://docs.openhands.dev/llms.txt>.
diff --git a/tests/test_check_issue_readiness.py b/tests/test_check_issue_readiness.py
new file mode 100644
index 00000000..f155e225
--- /dev/null
+++ b/tests/test_check_issue_readiness.py
@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+
+def _load_prod_module():
+    repo_root = Path(__file__).resolve().parents[1]
+    script_path = repo_root / ".github" / "scripts" / "check_issue_readiness.py"
+    name = "check_issue_readiness"
+    spec = importlib.util.spec_from_file_location(name, script_path)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_prod = _load_prod_module()
+evaluate_readiness = _prod.evaluate_readiness
+extract_sections = _prod.extract_sections
+
+
+ENHANCEMENT_READY = """### Problem or Use Case
+
+The integration catalog lacks a Linear entry.
+
+### Desired Behavior
+
+`integrations/catalog/linear.json` describes the Linear MCP server so the
+catalog build picks it up.
+
+### Acceptance Criteria
+
+- [ ] `npm run build:integrations` succeeds with the new entry
+- [ ] `getIntegrationCatalogEntry("linear")` returns the Linear catalog model
+"""
+
+BUG_READY = """### Actual Behavior
+
+Running `uv run --group test pytest tests/` fails in
+`test_skills_catalog.py` with a KeyError when a skill is missing from the
+marketplace.
+
+### Acceptance Criteria
+
+- [ ] `uv run --group test pytest tests/` passes with a clear error message
+"""
+
+
+def test_extract_sections_splits_on_headings():
+    sections = extract_sections("### Alpha\n\ntext\n\n### Beta\n\nmore\n")
+    assert sections["alpha"] == "\ntext\n\n"
+    assert sections["beta"] == "\nmore\n"
+
+
+def test_enhancement_ready_passes():
+    result = evaluate_readiness(ENHANCEMENT_READY, ["enhancement"])
+    assert result.ready is True
+    assert result.reasons == []
+
+
+def test_enhancement_missing_acceptance_criteria_fails():
+    body = "### Desired Behavior\n\nSome desired change.\n"
+    result = evaluate_readiness(body, ["enhancement"])
+    assert result.ready is False
+    assert any("Acceptance Criteria" in r for r in result.reasons)
+
+
+def test_enhancement_missing_desired_behavior_fails():
+    body = ENHANCEMENT_READY.replace(
+        "### Desired Behavior\n\n"
+        "`integrations/catalog/linear.json` describes the Linear MCP server so the\n"
+        "catalog build picks it up.\n\n",
+        "",
+    )
+    result = evaluate_readiness(body, ["enhancement"])
+    assert result.ready is False
+    assert any("Desired Behavior" in r for r in result.reasons)
+
+
+def test_bug_ready_passes():
+    result = evaluate_readiness(BUG_READY, ["bug"])
+    assert result.ready is True
+    assert result.reasons == []
+
+
+def test_bug_missing_run_method_fails():
+    body = BUG_READY.replace(
+        "Running `uv run --group test pytest tests/` fails",
+        "Running the test suite fails",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is False
+    assert any("reproducible command" in r for r in result.reasons)
+
+
+def test_bug_npm_build_command_is_a_valid_run_method():
+    body = BUG_READY.replace(
+        "Running `uv run --group test pytest tests/` fails in\n"
+        "`test_skills_catalog.py` with a KeyError when a skill is missing from the\n"
+        "marketplace.",
+        "Running `npm run build:skills` fails with a schema error.",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is True
+    assert result.reasons == []
+
+
+def test_bug_acceptance_needs_checklist_item():
+    body = BUG_READY.replace(
+        "- [ ] `uv run --group test pytest tests/` passes with a clear error message",
+        "Make the test error message clearer",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is False
+    assert any("checklist item" in r for r in result.reasons)
+
+
+def test_no_response_field_counts_as_empty():
+    body = BUG_READY.replace(
+        "### Acceptance Criteria\n\n- [ ] `uv run --group test pytest tests/` "
+        "passes with a clear error message\n",
+        "### Acceptance Criteria\n\n_No response_\n",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is False
+    assert any("Acceptance Criteria" in r for r in result.reasons)
+
+
+def test_no_bug_or_enhancement_label_not_ready():
+    result = evaluate_readiness(ENHANCEMENT_READY, [])
+    assert result.ready is False
+    assert any("bug" in r and "enhancement" in r for r in result.reasons)
diff --git a/tests/test_check_pr_description.py b/tests/test_check_pr_description.py
new file mode 100644
index 00000000..4352c3c5
--- /dev/null
+++ b/tests/test_check_pr_description.py
@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+
+def _load_prod_module():
+    repo_root = Path(__file__).resolve().parents[1]
+    script_path = repo_root / ".github" / "scripts" / "check_pr_description.py"
+    name = "check_pr_description"
+    spec = importlib.util.spec_from_file_location(name, script_path)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_prod = _load_prod_module()
+validate_pr_body = _prod.validate_pr_body
+body_from_event = _prod.body_from_event
+extract_linked_issue_numbers = _prod.extract_linked_issue_numbers
+validate_linked_issue_ready = _prod.validate_linked_issue_ready
+fetch_issue_details = _prod.fetch_issue_details
+
+
+VALID_BODY = """<!-- Keep this PR as draft until it is ready for review. -->
+
+<!-- AI/LLM agents: be concise and specific. Do not check the box below. -->
+
+- [ ] A human has tested these changes.
+
+---
+
+## Why
+
+The repository had no readiness gate for issues or linked PRs.
+
+## Summary
+
+- Add ready-for-dev issue and PR readiness gates.
+
+## Issue Number
+
+Fixes #508
+
+## How to Test
+
+Run `uv run --group test pytest tests/`.
+
+## Video/Screenshots
+
+N/A
+
+## Notes
+
+N/A
+"""
+
+
+def test_valid_pr_body_passes():
+    assert validate_pr_body(VALID_BODY) == []
+
+
+def test_required_template_fields_must_be_present_and_filled():
+    how_to_test = "## How to Test\n\nRun `uv run --group test pytest tests/`."
+    body = VALID_BODY.replace(how_to_test, "## How to Test\n\n<!-- TODO -->")
+    body = body.replace("## Summary", "## Details")
+
+    errors = validate_pr_body(body)
+
+    assert "Fill in the `## How to Test` section of the PR template." in errors
+    assert "Keep the `## Summary` section from the PR template." in errors
+
+
+def test_summary_placeholder_bullet_counts_as_empty():
+    body = VALID_BODY.replace(
+        "- Add ready-for-dev issue and PR readiness gates.", "-"
+    )
+
+    errors = validate_pr_body(body)
+
+    assert "Fill in the `## Summary` section of the PR template." in errors
+
+
+def test_optional_template_sections_may_be_removed():
+    body = VALID_BODY.replace("## Issue Number\n\nFixes #508\n\n", "")
+    body = body.split("## Video/Screenshots", maxsplit=1)[0]
+
+    assert validate_pr_body(body) == []
+
+
+def test_body_from_event_reads_pull_request_body(tmp_path: Path):
+    event_path = tmp_path / "event.json"
+    event_path.write_text(
+        json.dumps(
+            {
+                "pull_request": {"body": VALID_BODY},
+                "repository": {"full_name": "org/repo"},
+            }
+        )
+    )
+
+    body, repo = body_from_event(event_path)
+    assert body == VALID_BODY
+    assert repo == "org/repo"
+
+
+def test_extract_linked_issue_numbers_keyword_and_bare_ref():
+    body = (
+        "Fixes #12\n"
+        "Closes #12 again\n"
+        "resolves #34\n"
+        "## Issue Number\n"
+        "Issue: #56, see also #12\n"
+    )
+    assert extract_linked_issue_numbers(body) == [12, 34, 56]
+
+
+def test_extract_linked_issue_numbers_only_bare_ref_in_issue_section():
+    body = "## Summary\n\nSome work.\n\n## Issue Number\n\n#7\n"
+    assert extract_linked_issue_numbers(body) == [7]
+
+
+def test_extract_linked_issue_numbers_no_bare_ref_outside_issue_section():
+    # A bare `#42` in the Summary must not be treated as a linked issue.
+    body = "## Summary\n\nSee #42 for background.\n\n## Issue Number\n\nN/A\n"
+    assert extract_linked_issue_numbers(body) == []
+
+
+def test_extract_linked_issue_numbers_keyword_inside_word_is_ignored():
+    # "fix"/"clos"/"resolv" must not match inside larger words (e.g. "crucifixes").
+    body = (
+        "## Summary\n\n"
+        "crucifixes #12, encloses #34, transfixes #56.\n\n"
+        "## Issue Number\n\nN/A\n"
+    )
+    assert extract_linked_issue_numbers(body) == []
+
+
+def test_validate_linked_issue_ready_requires_a_number():
+    errors = validate_linked_issue_ready(
+        "## Issue Number\n\nN/A\n", "org/repo", "token"
+    )
+    assert errors and "Link an issue" in errors[0]
+
+
+def test_validate_linked_issue_ready_no_token_skips_network(monkeypatch):
+    def _fail(*args, **kwargs):
+        raise AssertionError("should not call the network without a token")
+
+    monkeypatch.setattr(_prod, "fetch_issue_details", _fail)
+    assert validate_linked_issue_ready("Fixes #12\n", None, None) == []
+
+
+def test_validate_linked_issue_ready_passes_with_ready_label(monkeypatch):
+    monkeypatch.setattr(
+        _prod,
+        "fetch_issue_details",
+        lambda repo, num, token: (["ready-for-dev"], "2026-08-25T00:00:00Z"),
+    )
+    assert validate_linked_issue_ready("Fixes #12\n", "org/repo", "token") == []
+
+
+def test_validate_linked_issue_ready_grandfathers_pre_rollout_issue(monkeypatch):
+    monkeypatch.setattr(
+        _prod,
+        "fetch_issue_details",
+        lambda repo, num, token: (["bug"], "2026-01-15T00:00:00Z"),
+    )
+    assert validate_linked_issue_ready("Fixes #12\n", "org/repo", "token") == []
+
+
+def test_validate_linked_issue_ready_grandfathers_rollout_day_before_deployment(
+    monkeypatch,
+):
+    # Opened on the rollout day (2026-08-24) before the workflow was deployed,
+    # so it was never labeled. It must be exempt.
+    monkeypatch.setattr(
+        _prod,
+        "fetch_issue_details",
+        lambda repo, num, token: (["bug"], "2026-08-24T06:46:00Z"),
+    )
+    assert validate_linked_issue_ready("Fixes #12\n", "org/repo", "token") == []
+
+
+def test_validate_linked_issue_ready_fails_for_new_not_ready_issue(monkeypatch):
+    monkeypatch.setattr(
+        _prod,
+        "fetch_issue_details",
+        lambda repo, num, token: (["bug"], "2026-08-25T00:00:00Z"),
+    )
+    errors = validate_linked_issue_ready("Fixes #12\n", "org/repo", "token")
+    assert errors and "ready-for-dev" in errors[0]
+
+
+def test_validate_linked_issue_ready_new_unready_not_masked_by_ready_sibling(
+    monkeypatch,
+):
+    def _issues(repo, num, token):
+        # #12 carries ready-for-dev; #34 is new and not ready.
+        if num == 34:
+            return ["bug"], "2026-08-25T00:00:00Z"
+        return ["ready-for-dev"], "2026-08-25T00:00:00Z"
+
+    monkeypatch.setattr(_prod, "fetch_issue_details", _issues)
+    body = "Fixes #12 and Closes #34"
+    errors = validate_linked_issue_ready(body, "org/repo", "token")
+    assert "#34" in errors[0]
+    assert "ready-for-dev" in errors[0]
+
+
+def test_validate_linked_issue_ready_returns_error_when_all_issues_not_found(
+    monkeypatch,
+):
+    import urllib.error
+    from http.client import HTTPMessage
+
+    def _missing(repo, num, token):
+        raise urllib.error.HTTPError(
+            "https://api.github.com", 404, "Not Found", HTTPMessage(), None
+        )
+
+    monkeypatch.setattr(_prod, "fetch_issue_details", _missing)
+    errors = validate_linked_issue_ready("Fixes #12\n", "org/repo", "token")
+    assert errors and "could not be found" in errors[0]
diff --git a/tests/test_refresh_linked_pr_checks.py b/tests/test_refresh_linked_pr_checks.py
new file mode 100644
index 00000000..e1143bbe
--- /dev/null
+++ b/tests/test_refresh_linked_pr_checks.py
@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+
+def _load(name: str, script_name: str):
+    script_path = (
+        Path(__file__).resolve().parents[1] / ".github" / "scripts" / script_name
+    )
+    spec = importlib.util.spec_from_file_location(name, script_path)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+# Import check_pr_description first so refresh_linked_pr_checks can resolve its
+# `from check_pr_description import ...` against the module we loaded above.
+_load("check_pr_description", "check_pr_description.py")
+_prod = _load("refresh_linked_pr_checks", "refresh_linked_pr_checks.py")
+
+
+def _event(action="labeled", label="ready-for-dev", number=12):
+    return {
+        "action": action,
+        "issue": {"number": number},
+        "label": {"name": label},
+        "repository": {"full_name": "org/repo"},
+    }
+
+
+def _write_event(monkeypatch, payload, tmp_path):
+    event_path = tmp_path / "event.json"
+    event_path.write_text(json.dumps(payload))
+    monkeypatch.setenv("GITHUB_EVENT_PATH", str(event_path))
+
+
+class _FakeProc:
+    def __init__(self, stdout: str = ""):
+        self.returncode = 0
+        self.stdout = stdout
+        self.stderr = ""
+
+
+def _recording_run(calls):
+    def _call(args):
+        calls.append(args)
+        # Listing runs returns one run; rerun is a no-op success.
+        if any("/actions/runs" in a for a in args):
+            return _FakeProc("8675309 2026-08-25T00:00:00Z\n")
+        return _FakeProc()
+
+    return _call
+
+
+def _fail_on_call(value):
+    def _call(*args, **kwargs):
+        raise AssertionError(value)
+
+    return _call
+
+
+def test_noop_for_unrelated_label(monkeypatch, tmp_path):
+    _write_event(monkeypatch, _event(label="bug"), tmp_path)
+    monkeypatch.setattr(_prod, "_linked_open_prs", _fail_on_call("unexpected"))
+    assert _prod.main() == 0
+
+
+def test_noop_for_unrelated_action(monkeypatch, tmp_path):
+    _write_event(monkeypatch, _event(action="edited"), tmp_path)
+    monkeypatch.setattr(_prod, "_linked_open_prs", _fail_on_call("unexpected"))
+    assert _prod.main() == 0
+
+
+def test_reruns_linked_pr_check_when_readiness_label_changes(monkeypatch, tmp_path):
+    _write_event(monkeypatch, _event(), tmp_path)
+    monkeypatch.setattr(
+        _prod,
+        "_linked_open_prs",
+        lambda repo, num: [{"number": 7, "headRefOid": "abc123"}],
+    )
+    monkeypatch.setattr(_prod, "_run", lambda args: _FakeProc("Fixes #12"))
+    seen = []
+    monkeypatch.setattr(
+        _prod,
+        "_rerun_pr_description_check",
+        lambda repo, sha: (seen.append((repo, sha)) or True),
+    )
+    assert _prod.main() == 0
+    assert seen == [("org/repo", "abc123")]
+
+
+def test_skips_cross_referenced_pr_that_does_not_link_issue(monkeypatch, tmp_path):
+    _write_event(monkeypatch, _event(), tmp_path)
+    monkeypatch.setattr(
+        _prod,
+        "_linked_open_prs",
+        lambda repo, num: [{"number": 7, "headRefOid": "abc123"}],
+    )
+    # Body mentions #99 (the cross-reference) but not the event's issue #12.
+    monkeypatch.setattr(_prod, "_run", lambda args: _FakeProc("Fixes #99"))
+    seen = []
+    monkeypatch.setattr(
+        _prod,
+        "_rerun_pr_description_check",
+        lambda repo, sha: (seen.append((repo, sha)) or True),
+    )
+    assert _prod.main() == 0
+    assert seen == []
+
+
+def test_rerun_pr_description_check_lists_runs_with_get(monkeypatch):
+    calls: list[list[str]] = []
+    monkeypatch.setattr(_prod, "_run", _recording_run(calls))
+    assert _prod._rerun_pr_description_check("org/repo", "abc123") is True
+    # Listing runs must be an explicit GET: `-f` args alone switch `gh api`
+    # to POST, which 404s on the runs collection endpoint (seen in the wild).
+    list_call = next(a for a in calls if "repos/org/repo/actions/runs" in a)
+    assert "-X" in list_call
+    assert list_call[list_call.index("-X") + 1] == "GET"
+    # The selected run is then re-run via an explicit POST.
+    rerun_call = next(a for a in calls if any("/rerun" in arg for arg in a))
+    assert rerun_call[rerun_call.index("api") + 1 : rerun_call.index("api") + 3] == [
+        "-X",
+        "POST",
+    ]