From 16570d73f47b2cf6f4c3e5927308282b093f8161 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 26 Aug 2026 13:26:47 -0500
Subject: [PATCH] ci: add PR validation scripts and workflows to skill branch

The skill/openhands-enterprise-troubleshooting branch predates the PR description and issue readiness validation jobs. As a result, pull_request_target checks out a base SHA that lacks .github/scripts/check_pr_description.py and the job fails with FileNotFoundError. Backport the scripts, workflows, and dependabot config from main so the PR-description and issue-readiness checks can run.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 .github/dependabot.yml                      |  24 ++
 .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 +++
 7 files changed, 1056 insertions(+)
 create mode 100644 .github/dependabot.yml
 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

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000..0586bf0e
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,24 @@
+# Keep dependency update scheduling centralized in this repository configuration.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci(deps)
+
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: chore(deps)
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