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

Add an issue-readiness workflow that manages the ready-for-dev label with
type-specific criteria tailored to the TypeScript client: bug reports need a
reproducible JavaScript/TypeScript command (npm, pnpm, yarn, or npx) in the
Actual Behavior section, and both bugs and enhancements need Acceptance
Criteria checklist items (enhancements also need Desired Behavior).

- check-issue-readiness.mjs always exits 0 in --json mode so not-ready
  results drive label/comment behavior without failing the workflow under
  set -euo pipefail
- post-readiness-comment.mjs upserts a single feedback comment via a hidden
  marker (idempotent)
- pr-description-check.yml gates PRs on linked issues carrying ready-for-dev
  (issues predating the rollout are grandfathered)
- refresh-linked-pr-checks.mjs re-runs the PR gate for open PRs linked to an
  issue whose ready-for-dev label changed
- Issue forms for bug reports and feature requests produce the sections the
  readiness check evaluates
- Jest tests exercise the real CLI code paths via child processes, with a
  local HTTP server standing in for the GitHub API

Fixes #357

Co-authored-by: openhands <openhands@all-hands.dev>
---
 .github/ISSUE_TEMPLATE/bug_report.yml        | 150 ++++++++++
 .github/ISSUE_TEMPLATE/feature_request.yml   |  77 +++++
 .github/scripts/check-issue-readiness.mjs    | 232 +++++++++++++++
 .github/scripts/check-pr-description.mjs     | 203 +++++++++++++
 .github/scripts/post-readiness-comment.mjs   | 193 ++++++++++++
 .github/scripts/refresh-linked-pr-checks.mjs | 185 ++++++++++++
 .github/workflows/issue-readiness-check.yml  | 140 +++++++++
 .github/workflows/pr-description-check.yml   |  41 +++
 src/__tests__/issue-readiness.test.ts        | 243 ++++++++++++++++
 src/__tests__/pr-description-check.test.ts   | 290 +++++++++++++++++++
 10 files changed, 1754 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
 create mode 100644 .github/scripts/check-issue-readiness.mjs
 create mode 100644 .github/scripts/check-pr-description.mjs
 create mode 100644 .github/scripts/post-readiness-comment.mjs
 create mode 100644 .github/scripts/refresh-linked-pr-checks.mjs
 create mode 100644 .github/workflows/issue-readiness-check.yml
 create mode 100644 .github/workflows/pr-description-check.yml
 create mode 100644 src/__tests__/issue-readiness.test.ts
 create mode 100644 src/__tests__/pr-description-check.test.ts

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..d2c8ecf
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,150 @@
+---
+name: Bug
+description: Report a problem with the OpenHands Agent Server TypeScript client
+title: '[Bug]: '
+labels: [bug]
+body:
+    - type: markdown
+      attributes:
+          value: |
+              ## Thank you for reporting a bug! 🐛
+
+              **Please fill out all required fields.** Issues are evaluated for
+              the `ready-for-dev` label automatically: a bug report is ready
+              when the Actual Behavior section includes a reproducible
+              JavaScript/TypeScript command and the Acceptance Criteria section
+              has at least one checklist item.
+
+    - type: checkboxes
+      attributes:
+          label: Is there an existing issue for the same bug?
+          description: Please search existing issues before creating a new one. If found, react or comment on the duplicate issue instead.
+          options:
+              - label: I have searched existing issues and this is not a duplicate.
+                required: true
+
+    - type: textarea
+      id: bug-description
+      attributes:
+          label: Bug Description
+          description: Clearly describe what went wrong. Be specific and concise.
+          placeholder: Example - RemoteConversation.start() rejects with a 404 when the conversation ID contains uppercase characters.
+      validations:
+          required: true
+
+    - type: textarea
+      id: expected-behavior
+      attributes:
+          label: Expected Behavior
+          description: What did you expect to happen?
+          placeholder: Example - The conversation should start regardless of ID casing.
+      validations:
+          required: false
+
+    - type: textarea
+      id: actual-behavior
+      attributes:
+          label: Actual Behavior
+          description: |
+              What actually happened? Include the reproducible command(s) you
+              ran (e.g. `npm test`, `npx tsx repro.ts`, `pnpm vitest run`) and
+              the observed output.
+          placeholder: |
+              Example - Running `npx tsx repro.ts` against @openhands/typescript-client 1.38.1 fails with:
+              ```
+              Error: request failed with status 404
+              ```
+      validations:
+          required: true
+
+    - type: textarea
+      id: reproduction-steps
+      attributes:
+          label: Steps to Reproduce
+          description: Provide clear, step-by-step instructions to reproduce the bug.
+          placeholder: |
+              1. Install the client with `npm install @openhands/typescript-client`
+              2. Create a RemoteConversation with an uppercase ID
+              3. Call `await conversation.start()`
+              4. Error appears
+      validations:
+          required: false
+
+    - type: textarea
+      id: acceptance-criteria
+      attributes:
+          label: Acceptance Criteria
+          description: List the testable checklist item(s) that would prove this bug is fixed.
+          placeholder: |
+              - [ ] The reported error no longer occurs
+              - [ ] A regression test covers the reported scenario
+      validations:
+          required: true
+
+    - type: input
+      id: client-version
+      attributes:
+          label: Client Version
+          description: What version of @openhands/typescript-client are you using?
+          placeholder: ex. 1.38.1, main branch, commit hash
+      validations:
+          required: false
+
+    - type: input
+      id: runtime-version
+      attributes:
+          label: Runtime and Package Manager
+          description: Which runtime and package manager are you using?
+          placeholder: ex. Node 22.12 + npm 10, Node 24 + pnpm 9, browser (Vite)
+      validations:
+          required: false
+
+    - type: input
+      id: agent-server-version
+      attributes:
+          label: Agent Server Version (if applicable)
+          description: Which agent-server image/version is the client talking to?
+          placeholder: ex. ghcr.io/openhands/agent-server:1.43.1-python
+      validations:
+          required: false
+
+    - type: dropdown
+      id: os
+      attributes:
+          label: Operating System
+          options:
+              - MacOS
+              - Linux
+              - WSL on Windows
+              - Windows
+              - Other
+      validations:
+          required: false
+
+    - type: textarea
+      id: logs
+      attributes:
+          label: Logs and Error Messages
+          description: Paste relevant logs, error messages, or stack traces. Use code blocks (```) for formatting.
+          placeholder: |
+              ```
+              Paste error logs here
+              ```
+
+    - type: textarea
+      id: code-sample
+      attributes:
+          label: Minimal Code Sample
+          description: If possible, provide a minimal code sample that reproduces the issue.
+          placeholder: |
+              ```ts
+              import { RemoteConversation } from '@openhands/typescript-client';
+
+              // Your minimal reproducible code here
+              ```
+
+    - type: textarea
+      id: additional-context
+      attributes:
+          label: Screenshots and Additional Context
+          description: Add screenshots, environment details, dependency versions, or other context that helps explain the issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..9e06bd8
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,77 @@
+---
+name: Feature Request or Enhancement
+description: Suggest a new feature or improvement for the OpenHands Agent Server TypeScript client
+title: '[Feature]: '
+labels: [enhancement]
+body:
+    - type: markdown
+      attributes:
+          value: |
+              ## Thank you for suggesting a feature! 💡
+
+              Issues are evaluated for the `ready-for-dev` label automatically:
+              an enhancement is ready when it has a Desired Behavior section and
+              an Acceptance Criteria section with at least one checklist item.
+
+    - type: checkboxes
+      attributes:
+          label: Is there an existing feature request for this?
+          description: Please search existing issues and feature requests before creating a new one. If found, react or comment on the duplicate issue instead.
+          options:
+              - label: I have searched existing issues and feature requests, and this is not a duplicate.
+                required: true
+
+    - type: textarea
+      id: problem-statement
+      attributes:
+          label: Problem or Use Case
+          description: What problem are you trying to solve? What use case would this feature enable?
+          placeholder: Example - As a developer building a web UI on the agent-server API, I need typed access to conversation cost metrics so I can display usage to end users.
+      validations:
+          required: true
+
+    - type: textarea
+      id: desired-behavior
+      attributes:
+          label: Desired Behavior
+          description: Describe your ideal solution. What should this feature do? How should it work?
+          placeholder: Example - Expose a `conversation.getCostMetrics()` method returning a typed `CostMetrics` object mirroring the agent-server response.
+      validations:
+          required: true
+
+    - type: textarea
+      id: acceptance-criteria
+      attributes:
+          label: Acceptance Criteria
+          description: List the testable checklist item(s) that would prove this feature is complete.
+          placeholder: |
+              - [ ] The new method returns typed cost metrics from the agent-server
+              - [ ] Unit tests cover the new behavior
+      validations:
+          required: true
+
+    - type: textarea
+      id: alternatives
+      attributes:
+          label: Alternatives Considered
+          description: Have you considered any alternative solutions or workarounds? What are their limitations?
+          placeholder: Example - Calling the REST endpoint directly with fetch, but that loses the client's type safety and error handling.
+
+    - type: textarea
+      id: technical-details
+      attributes:
+          label: Technical Implementation Ideas (Optional)
+          description: If you have technical expertise, share implementation ideas, API suggestions, or relevant technical details.
+          placeholder: |
+              Example - Mirror the Python SDK's RemoteConversation cost API; the endpoint already exists in the OpenAPI spec at src/generated/agent-server-schema.ts.
+
+    - type: textarea
+      id: additional-context
+      attributes:
+          label: Additional Context
+          description: Add any other context, code examples, API mockups, or references that help illustrate this feature request.
+          placeholder: |
+              ```ts
+              const metrics = await conversation.getCostMetrics();
+              console.log(metrics.totalCostUsd);
+              ```
diff --git a/.github/scripts/check-issue-readiness.mjs b/.github/scripts/check-issue-readiness.mjs
new file mode 100644
index 0000000..5d2b351
--- /dev/null
+++ b/.github/scripts/check-issue-readiness.mjs
@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+/**
+ * Determine whether an issue meets the `ready-for-dev` readiness criteria.
+ *
+ * The criteria are type-specific:
+ *
+ * - Bug reports (labeled `bug`): the Actual Behavior section must describe a
+ *   reproducible run of the TypeScript client and include a supported command
+ *   (`npm`, `pnpm`, `yarn`, or `npx`), 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.
+ *
+ * In --json mode the process always exits 0: the JSON result on stdout drives
+ * label and comment behavior, so a not-ready issue must not fail the workflow
+ * step under `set -euo pipefail`.
+ *
+ * Local usage:
+ *
+ *   node .github/scripts/check-issue-readiness.mjs --body-file /tmp/issue.md --labels bug
+ *   node .github/scripts/check-issue-readiness.mjs --event-path "$GITHUB_EVENT_PATH" --json
+ */
+
+import { readFileSync } from 'node:fs';
+
+const BUG_LABEL = 'bug';
+const ENHANCEMENT_LABEL = 'enhancement';
+
+// Issue-form fields render as `### Label` h3 headings. `^###\s+` is specific
+// enough because h1/h2 are not produced by issue forms.
+const HEADING_RE = /^###\s+(.+?)\s*$/gm;
+
+// `_No response_` is what GitHub writes for an empty optional form field.
+const NO_RESPONSE = '_No response_';
+
+// A reproducible JavaScript/TypeScript package-manager command must appear in
+// the Actual Behavior section.
+const RUN_METHOD_PATTERNS = [/\bnpm\b/i, /\bpnpm\b/i, /\byarn\b/i, /\bnpx\b/i, /\bbunx?\b/i];
+
+// An Acceptance Criteria item is a markdown checklist bullet (`- [ ]` or
+// `- [x]`). We require at least one so the section is verifiable.
+const CHECKLIST_ITEM_RE = /^\s*[-*]\s*\[[ xX]\]/m;
+
+export function visibleText(text) {
+  const cleaned = text.replace(/<!--[\s\S]*?-->/g, '').trim();
+  return cleaned === NO_RESPONSE ? '' : cleaned;
+}
+
+export function extractSections(body) {
+  // Split the body into a {heading: text} map using `### <heading>`
+  // boundaries. Free-form issues may still use `###` headings; if they don't,
+  // the map is empty and every section lookup misses.
+  const matches = [...body.matchAll(HEADING_RE)];
+  const sections = {};
+  for (let index = 0; index < matches.length; index += 1) {
+    const start = matches[index].index + matches[index][0].length;
+    const end = index + 1 < matches.length ? matches[index + 1].index : body.length;
+    sections[matches[index][1].trim().toLowerCase()] = body.slice(start, end);
+  }
+  return sections;
+}
+
+function findSection(sections, ...labels) {
+  for (const label of labels) {
+    if (label in sections) return sections[label];
+  }
+  return '';
+}
+
+function referencesRunMethod(text) {
+  return RUN_METHOD_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+function hasChecklistItem(text) {
+  return CHECKLIST_ITEM_RE.test(text);
+}
+
+function checkBug(sections) {
+  const reasons = [];
+
+  const actual = visibleText(findSection(sections, 'actual behavior', 'actual'));
+  if (!actual) {
+    reasons.push(
+      'Fill in the `### Actual Behavior` section with reproducible steps and the observed result.'
+    );
+  } else if (!referencesRunMethod(actual)) {
+    reasons.push(
+      'The Actual Behavior section must include a reproducible JavaScript/TypeScript ' +
+        'command such as `npm`, `pnpm`, `yarn`, or `npx`.'
+    );
+  }
+
+  const acceptance = visibleText(findSection(sections, 'acceptance criteria', 'acceptance'));
+  if (!acceptance) {
+    reasons.push('Add an `### Acceptance Criteria` section with testable checklist items.');
+  } else if (!hasChecklistItem(acceptance)) {
+    reasons.push(
+      'The Acceptance Criteria section must contain at least one checklist item (`- [ ] …`).'
+    );
+  }
+
+  return { ready: reasons.length === 0, reasons };
+}
+
+function checkEnhancement(sections) {
+  const reasons = [];
+
+  const desired = visibleText(findSection(sections, 'desired behavior', 'desired'));
+  if (!desired) {
+    reasons.push('Add a `### Desired Behavior` section describing the behavior you want.');
+  }
+
+  const acceptance = visibleText(findSection(sections, 'acceptance criteria', 'acceptance'));
+  if (!acceptance) {
+    reasons.push('Add an `### Acceptance Criteria` section with testable checklist items.');
+  } else if (!hasChecklistItem(acceptance)) {
+    reasons.push(
+      'The Acceptance Criteria section must contain at least one checklist item (`- [ ] …`).'
+    );
+  }
+
+  return { ready: reasons.length === 0, reasons };
+}
+
+export function evaluateReadiness(body, labels) {
+  // An issue is only a candidate when it carries the `bug` or `enhancement`
+  // label. If it has neither, it is not-ready-for-dev: the gate does not apply
+  // a label it cannot validate.
+  const labelSet = new Set(labels.map((label) => label.toLowerCase()));
+  const sections = extractSections(body ?? '');
+
+  if (labelSet.has(BUG_LABEL)) return checkBug(sections);
+  if (labelSet.has(ENHANCEMENT_LABEL)) return checkEnhancement(sections);
+
+  return {
+    ready: false,
+    reasons: [
+      'The issue has neither the `bug` nor `enhancement` label, so its readiness ' +
+        'criteria cannot be evaluated. Add the appropriate label.',
+    ],
+  };
+}
+
+export function bodyAndLabelsFromEvent(eventPath) {
+  const payload = JSON.parse(readFileSync(eventPath, 'utf8'));
+  const issue = payload.issue ?? payload.pull_request;
+  if (!issue || typeof issue !== 'object') {
+    throw new Error('GitHub event payload does not contain an issue object');
+  }
+  const body = typeof issue.body === 'string' ? issue.body : '';
+  const labels = (Array.isArray(issue.labels) ? issue.labels : [])
+    .filter((label) => label && typeof label === 'object')
+    .map((label) => label.name);
+  return { body, labels };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const eqIndex = arg.indexOf('=');
+    const rawKey = (eqIndex === -1 ? arg.slice(2) : arg.slice(2, eqIndex)).replaceAll('-', '_');
+    if (eqIndex !== -1) {
+      args[rawKey] = arg.slice(eqIndex + 1);
+    } else if (argv[i + 1] && !argv[i + 1].startsWith('--')) {
+      args[rawKey] = argv[i + 1];
+      i += 1;
+    } else {
+      args[rawKey] = '';
+    }
+  }
+  return args;
+}
+
+export function main(argv = process.argv.slice(2), env = process.env) {
+  const args = parseArgs(argv);
+
+  let body;
+  let labels;
+  if (args.body_file) {
+    body = readFileSync(args.body_file, 'utf8');
+    labels = (args.labels ?? '')
+      .split(',')
+      .map((label) => label.trim())
+      .filter(Boolean);
+  } else {
+    const eventPath = args.event_path ?? env.GITHUB_EVENT_PATH;
+    if (!eventPath) {
+      throw new Error('Pass --body-file or set GITHUB_EVENT_PATH.');
+    }
+    ({ body, labels } = bodyAndLabelsFromEvent(eventPath));
+  }
+
+  const result = evaluateReadiness(body, labels);
+
+  if ('json' in args) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    // 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) {
+    process.stdout.write('Issue meets ready-for-dev criteria.\n');
+  } else {
+    process.stdout.write('Issue does not meet ready-for-dev criteria:\n');
+    for (const reason of result.reasons) {
+      process.stdout.write(`  - ${reason}\n`);
+    }
+  }
+  return result.ready ? 0 : 1;
+}
+
+// Only run as a CLI when executed directly (not when imported by tests).
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  try {
+    process.exit(main());
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+  }
+}
diff --git a/.github/scripts/check-pr-description.mjs b/.github/scripts/check-pr-description.mjs
new file mode 100644
index 0000000..6d6c2e1
--- /dev/null
+++ b/.github/scripts/check-pr-description.mjs
@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/**
+ * Validate that a PR links at least one issue and that every linked issue is
+ * allowed to receive PRs: it must exist in this repository and either carry
+ * the `ready-for-dev` label or predate the readiness-gate rollout (existing
+ * issues were never evaluated by the issue-readiness workflow, so requiring
+ * the label retroactively would block PRs against long-open issues).
+ *
+ * Linked issues are detected via GitHub auto-link keywords (`Fixes #123`,
+ * `Closes #123`, `Resolves #123`, …) anywhere in the body, plus bare `#123`
+ * references inside the `## Issue Number` template section.
+ *
+ * The API lookup runs when a repository and GITHUB_TOKEN are available (CI).
+ * In local `--body-file` mode without a token, only the presence of a linked
+ * issue is checked.
+ *
+ * Unlike the issue-readiness check, this script is a gate: it exits 1 when
+ * validation fails so the PR check stays red until the linked issue is ready.
+ *
+ * Local usage:
+ *
+ *   node .github/scripts/check-pr-description.mjs --body-file /tmp/pr-body.md
+ *   node .github/scripts/check-pr-description.mjs --event-path "$GITHUB_EVENT_PATH"
+ */
+
+import { readFileSync } from 'node:fs';
+
+const HEADING_RE = /^##\s+(.+?)\s*$/gm;
+const ISSUE_REF_RE = /\b(?:fix|clos|resolv)(?:e?(?:s|d)?|ing)?\s+#(\d+)/gi;
+const BARE_ISSUE_REF_RE = /(?<!\w)#(\d+)/g;
+const 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. 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.
+const READY_FOR_DEV_ROLLOUT_ISO = '2026-08-25';
+
+const API_ROOT = process.env.GITHUB_API_URL ?? 'https://api.github.com';
+
+export function extractSections(body) {
+  const matches = [...body.matchAll(HEADING_RE)];
+  const sections = {};
+  for (let index = 0; index < matches.length; index += 1) {
+    const start = matches[index].index + matches[index][0].length;
+    const end = index + 1 < matches.length ? matches[index + 1].index : body.length;
+    sections[matches[index][1].trim()] = body.slice(start, end);
+  }
+  return sections;
+}
+
+export function extractLinkedIssueNumbers(body) {
+  const numbers = [];
+  const seen = new Set();
+  for (const match of body.matchAll(ISSUE_REF_RE)) {
+    const number = Number.parseInt(match[1], 10);
+    if (!seen.has(number)) {
+      numbers.push(number);
+      seen.add(number);
+    }
+  }
+
+  const issueSection = extractSections(body)['Issue Number'] ?? '';
+  for (const match of issueSection.matchAll(BARE_ISSUE_REF_RE)) {
+    const number = Number.parseInt(match[1], 10);
+    if (!seen.has(number)) {
+      numbers.push(number);
+      seen.add(number);
+    }
+  }
+  return numbers;
+}
+
+export async function fetchIssueDetails(repo, issueNumber, token) {
+  const resp = await fetch(`${API_ROOT}/repos/${repo}/issues/${issueNumber}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+  if (resp.status === 404) return null;
+  if (!resp.ok) {
+    throw new Error(`Failed to fetch issue #${issueNumber}: ${resp.status} ${await resp.text()}`);
+  }
+  const issue = await resp.json();
+  const labels = (Array.isArray(issue.labels) ? issue.labels : [])
+    .filter((label) => label && typeof label === 'object')
+    .map((label) => label.name);
+  return { labels, createdAt: typeof issue.created_at === 'string' ? issue.created_at : '' };
+}
+
+export async function validateLinkedIssueReady(body, repo, token) {
+  const numbers = extractLinkedIssueNumbers(body);
+  if (numbers.length === 0) {
+    return [
+      'Link an issue in the `## Issue Number` section (e.g. `Fixes #123`). ' +
+        'Newly opened issues must carry the `ready-for-dev` label.',
+    ];
+  }
+  if (!repo || !token) return [];
+
+  const checked = [];
+  const notReadyNew = [];
+  for (const number of numbers) {
+    const details = await fetchIssueDetails(repo, number, token);
+    if (details === null) continue;
+    checked.push(number);
+    if (details.labels.some((label) => label.toLowerCase() === READY_FOR_DEV_LABEL)) {
+      continue;
+    }
+    if (details.createdAt.slice(0, 10) < READY_FOR_DEV_ROLLOUT_ISO) {
+      // Predates the rollout; grandfathered to avoid retroactive blocking.
+      continue;
+    }
+    notReadyNew.push(number);
+  }
+
+  if (checked.length === 0) {
+    const refs = numbers.map((number) => `#${number}`).join(', ');
+    return [`Referenced issue(s) ${refs} could not be found in this repository.`];
+  }
+  if (notReadyNew.length > 0) {
+    const refs = notReadyNew.map((number) => `#${number}`).join(', ');
+    return [
+      `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 [];
+}
+
+function bodyAndRepoFromEvent(eventPath) {
+  const payload = JSON.parse(readFileSync(eventPath, 'utf8'));
+  const pullRequest = payload.pull_request;
+  if (!pullRequest || typeof pullRequest !== 'object') {
+    throw new Error('GitHub event payload does not contain a pull_request object');
+  }
+  const body = typeof pullRequest.body === 'string' ? pullRequest.body : '';
+  const repo = payload.repository?.full_name;
+  return { body, repo: typeof repo === 'string' ? repo : null };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const eqIndex = arg.indexOf('=');
+    const rawKey = (eqIndex === -1 ? arg.slice(2) : arg.slice(2, eqIndex)).replaceAll('-', '_');
+    if (eqIndex !== -1) {
+      args[rawKey] = arg.slice(eqIndex + 1);
+    } else if (argv[i + 1] && !argv[i + 1].startsWith('--')) {
+      args[rawKey] = argv[i + 1];
+      i += 1;
+    } else {
+      args[rawKey] = '';
+    }
+  }
+  return args;
+}
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const args = parseArgs(argv);
+
+  let body;
+  let repo;
+  if (args.body_file) {
+    body = readFileSync(args.body_file, 'utf8');
+    repo = args.repo ?? null;
+  } else {
+    const eventPath = args.event_path ?? env.GITHUB_EVENT_PATH;
+    if (!eventPath) {
+      throw new Error('Pass --body-file or set GITHUB_EVENT_PATH.');
+    }
+    ({ body, repo } = bodyAndRepoFromEvent(eventPath));
+  }
+
+  const errors = await validateLinkedIssueReady(body, repo, env.GITHUB_TOKEN);
+
+  for (const error of errors) {
+    process.stdout.write(`::error::${error}\n`);
+  }
+  if (errors.length > 0) {
+    process.stdout.write(`PR description validation failed with ${errors.length} error(s).\n`);
+    return 1;
+  }
+  process.stdout.write('PR description validation passed.\n');
+  return 0;
+}
+
+// Only run as a CLI when executed directly (not when imported by tests).
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(error instanceof Error ? error.message : error);
+      process.exit(2);
+    });
+}
diff --git a/.github/scripts/post-readiness-comment.mjs b/.github/scripts/post-readiness-comment.mjs
new file mode 100644
index 0000000..da5a28b
--- /dev/null
+++ b/.github/scripts/post-readiness-comment.mjs
@@ -0,0 +1,193 @@
+#!/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/typescript-client \
+ *     --reasons-file /tmp/reasons.txt \
+ *     --ready           # optional: post a "ready" message instead of "not ready"
+ *     --dry-run         # optional: print the comment body without API calls
+ */
+
+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 eqIndex = arg.indexOf('=');
+    const rawKey = (eqIndex === -1 ? arg.slice(2) : arg.slice(2, eqIndex)).replaceAll('-', '_');
+    if (eqIndex !== -1) {
+      args[rawKey] = arg.slice(eqIndex + 1);
+    } else if (argv[i + 1] && !argv[i + 1].startsWith('--')) {
+      args[rawKey] = argv[i + 1];
+      i += 1;
+    } else {
+      args[rawKey] = '';
+    }
+  }
+  return args;
+}
+
+function requireValue(name, value) {
+  if (!value) throw new Error(`Missing required value: ${name}`);
+  return value;
+}
+
+export function buildCommentBody({ ready, reasons }) {
+  const reasonList = reasons.length
+    ? reasons.map((reason) => `- ${reason}`).join('\n')
+    : '- The issue does not meet the ready-for-dev criteria.';
+
+  return ready
+    ? [
+        MARKER,
+        '### ✅ `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._',
+      ].join('\n')
+    : [
+        MARKER,
+        '### ⚠️ 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 include a reproducible',
+        '  JavaScript/TypeScript command such as `npm`, `pnpm`, `yarn`, or `npx`.',
+        '- 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._',
+      ].join('\n');
+}
+
+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 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 body = buildCommentBody({ ready: isReady, reasons });
+
+  if ('dry_run' in args) {
+    process.stdout.write(`${body}\n`);
+    return;
+  }
+
+  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 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}`);
+  }
+}
+
+// Only run as a CLI when executed directly (not when imported by tests).
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
diff --git a/.github/scripts/refresh-linked-pr-checks.mjs b/.github/scripts/refresh-linked-pr-checks.mjs
new file mode 100644
index 0000000..9db2220
--- /dev/null
+++ b/.github/scripts/refresh-linked-pr-checks.mjs
@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+/**
+ * Re-run the PR Description Check workflow for every open PR that links an
+ * issue whose `ready-for-dev` label just changed, so the linked-issue gate
+ * does not go stale between PR events.
+ *
+ * Driven by an `issues` (labeled/unlabeled) event payload from
+ * GITHUB_EVENT_PATH. Always exits 0: a refresh failure must not fail the
+ * issue-readiness workflow — it only means a PR gate stays stale until the
+ * next PR event.
+ *
+ * Usage:
+ *   node .github/scripts/refresh-linked-pr-checks.mjs [--event-path "$GITHUB_EVENT_PATH"]
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+import { extractLinkedIssueNumbers } from './check-pr-description.mjs';
+
+const PR_DESCRIPTION_CHECK_WORKFLOW = 'PR Description Check';
+
+function gh(args) {
+  // Returns { ok, stdout, stderr } without throwing so a gh failure degrades
+  // to a warning instead of a workflow failure.
+  try {
+    const stdout = execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { ok: true, stdout, stderr: '' };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: typeof error.stdout === 'string' ? error.stdout : '',
+      stderr: typeof error.stderr === 'string' ? error.stderr : String(error.message ?? error),
+    };
+  }
+}
+
+export function shouldRefresh(payload) {
+  // Only a ready-for-dev label transition on an issue can change the outcome
+  // of the linked-issue gate.
+  if (!payload || typeof payload !== 'object') return false;
+  if (payload.action !== 'labeled' && payload.action !== 'unlabeled') return false;
+  return payload.label?.name === 'ready-for-dev';
+}
+
+function linkedOpenPrs(repo, issueNumber) {
+  const [owner, name] = repo.split('/', 2);
+  const 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 }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+  const result = gh([
+    'api',
+    'graphql',
+    '-f',
+    `query=${query}`,
+    '-F',
+    `owner=${owner}`,
+    '-F',
+    `name=${name}`,
+    '-F',
+    `num=${issueNumber}`,
+    '--jq',
+    '.data.repository.issue.timelineItems.nodes',
+  ]);
+  if (!result.ok) {
+    console.log(`::warning::Could not query linked PRs: ${result.stderr.trim()}`);
+    return [];
+  }
+  let nodes;
+  try {
+    nodes = JSON.parse(result.stdout);
+  } catch (error) {
+    console.log(`::warning::Unexpected linked-PR query output: ${error.message}`);
+    return [];
+  }
+  if (!Array.isArray(nodes)) return [];
+  return nodes
+    .map((node) => node?.source)
+    .filter(
+      (source) =>
+        source &&
+        typeof source === 'object' &&
+        source.__typename === 'PullRequest' &&
+        source.state === 'OPEN'
+    );
+}
+
+function rerunPrDescriptionCheck(repo, headSha) {
+  const runs = gh([
+    'api',
+    '-X',
+    'GET',
+    `repos/${repo}/actions/runs`,
+    '-f',
+    `head_sha=${headSha}`,
+    '-f',
+    'per_page=100',
+    '--jq',
+    `.workflow_runs[] | select(.name=="${PR_DESCRIPTION_CHECK_WORKFLOW}") | ` +
+      'select(.event=="pull_request_target") | "\\(.id) \\(.created_at)"',
+  ]);
+  if (!runs.ok) {
+    console.log(`::warning::Could not list PR checks: ${runs.stderr.trim()}`);
+    return false;
+  }
+  const lines = runs.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.split(/\s+/));
+  if (lines.length === 0) return false;
+  // Created-at is ISO 8601 and therefore sortable; pick the most recent run
+  // for this commit.
+  const latest = lines.sort((a, b) => a.slice(1).join(' ').localeCompare(b.slice(1).join(' ')))[
+    lines.length - 1
+  ][0];
+  const rerun = gh(['api', '-X', 'POST', `repos/${repo}/actions/runs/${latest}/rerun`]);
+  if (!rerun.ok) {
+    console.log(
+      `::warning::Could not re-run PR description check (${latest}): ${rerun.stderr.trim()}`
+    );
+    return false;
+  }
+  console.log(`Re-ran PR description check (run ${latest}) for linked open PR.`);
+  return true;
+}
+
+export function main(argv = process.argv.slice(2), env = process.env) {
+  const eventPathIndex = argv.indexOf('--event-path');
+  const eventPath =
+    eventPathIndex !== -1 && argv[eventPathIndex + 1] ? argv[eventPathIndex + 1] : env.GITHUB_EVENT_PATH;
+  if (!eventPath) {
+    console.log('No event payload available; nothing to refresh.');
+    return 0;
+  }
+
+  const payload = JSON.parse(readFileSync(eventPath, 'utf8'));
+  if (!shouldRefresh(payload)) return 0;
+
+  const repo = payload.repository?.full_name;
+  const issueNumber = payload.issue?.number;
+  if (typeof repo !== 'string' || typeof issueNumber !== 'number') return 0;
+
+  console.log(
+    `ready-for-dev ${payload.action}: refreshing PR gates linked to issue #${issueNumber}.`
+  );
+  let refreshed = 0;
+  for (const pr of linkedOpenPrs(repo, issueNumber)) {
+    const body = gh(['pr', 'view', String(pr.number), '--repo', repo, '--json', 'body', '--jq', '.body']);
+    if (!body.ok) continue;
+    if (!extractLinkedIssueNumbers(body.stdout).includes(issueNumber)) {
+      // Cross-referenced but not treated as a linked issue by the gate;
+      // nothing to refresh.
+      continue;
+    }
+    if (rerunPrDescriptionCheck(repo, pr.headRefOid)) refreshed += 1;
+  }
+  console.log(`Refreshed PR gates for ${refreshed} linked PR(s).`);
+  return 0;
+}
+
+// Only run as a CLI when executed directly (not when imported by tests).
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  try {
+    process.exit(main());
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
diff --git a/.github/workflows/issue-readiness-check.yml b/.github/workflows/issue-readiness-check.yml
new file mode 100644
index 0000000..212cd10
--- /dev/null
+++ b/.github/workflows/issue-readiness-check.yml
@@ -0,0 +1,140 @@
+---
+name: Issue Readiness Check
+
+# Manages the `ready-for-dev` label based on type-specific readiness criteria.
+#
+# Bug reports (label `bug`): the Actual Behavior section must reference a
+# reproducible JavaScript/TypeScript command (`npm`, `pnpm`, `yarn`, or `npx`),
+# 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.
+
+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-24.04
+        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
+                  # --json mode always exits 0, so a not-ready issue does not
+                  # fail this step under pipefail; the JSON drives the label
+                  # and comment steps below.
+                  node .github/scripts/check-issue-readiness.mjs --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-24.04
+        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: node .github/scripts/refresh-linked-pr-checks.mjs
diff --git a/.github/workflows/pr-description-check.yml b/.github/workflows/pr-description-check.yml
new file mode 100644
index 0000000..37c4ea7
--- /dev/null
+++ b/.github/workflows/pr-description-check.yml
@@ -0,0 +1,41 @@
+---
+name: PR Description Check
+
+# Gates PRs on a linked issue that is ready for development: every issue the
+# PR links (`Fixes #123`, or a bare `#123` in the `## Issue Number` section)
+# must exist in this repository and carry the `ready-for-dev` label, unless it
+# predates the readiness-gate rollout.
+#
+# Use pull_request_target so fork PR descriptions can be checked, but only run
+# trusted validation code from the base branch checkout below. The
+# ready-for-dev label is managed by the Issue Readiness Check workflow, which
+# re-runs this check for linked PRs when the label changes.
+
+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
+        # Run on drafts too so contributors can iterate on a passing description
+        # before requesting review. Bots (dependabot, release-please) write their
+        # own bodies and cannot follow the linked-issue convention, so exempt them
+        # rather than failing every such PR.
+        if: github.event.pull_request.user.type != 'Bot'
+        runs-on: ubuntu-24.04
+        steps:
+            - name: Checkout trusted workflow scripts
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.base.sha }}
+
+            - name: Validate linked-issue readiness
+              env:
+                  GITHUB_TOKEN: ${{ github.token }}
+              run: node .github/scripts/check-pr-description.mjs
diff --git a/src/__tests__/issue-readiness.test.ts b/src/__tests__/issue-readiness.test.ts
new file mode 100644
index 0000000..3b8f2b8
--- /dev/null
+++ b/src/__tests__/issue-readiness.test.ts
@@ -0,0 +1,243 @@
+/**
+ * Unit tests for .github/scripts/check-issue-readiness.mjs
+ *
+ * The script is exercised through its real CLI (a node child process) so the
+ * tests cover the same code path the Issue Readiness Check workflow runs,
+ * including the --json exit-code contract that keeps not-ready results safe
+ * under `set -euo pipefail`.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const REPO_ROOT = resolve(__dirname, '../..');
+const SCRIPT = join(REPO_ROOT, '.github/scripts/check-issue-readiness.mjs');
+
+interface RunResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+function runScript(args: string[], env: NodeJS.ProcessEnv = {}): RunResult {
+  const result = spawnSync(process.execPath, [SCRIPT, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+const READY_BUG_BODY = [
+  '### Bug Description',
+  'start() rejects with a 404.',
+  '',
+  '### Actual Behavior',
+  'Running `npm test` fails with `Error: request failed with status 404`.',
+  '',
+  '### Acceptance Criteria',
+  '- [ ] The error no longer occurs',
+].join('\n');
+
+const READY_ENHANCEMENT_BODY = [
+  '### Problem or Use Case',
+  'Need typed cost metrics.',
+  '',
+  '### Desired Behavior',
+  'Expose conversation.getCostMetrics().',
+  '',
+  '### Acceptance Criteria',
+  '- [ ] The method returns typed cost metrics',
+].join('\n');
+
+describe('check-issue-readiness', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'issue-readiness-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function writeBody(body: string): string {
+    const file = join(dir, 'body.md');
+    writeFileSync(file, body);
+    return file;
+  }
+
+  describe('bug criteria', () => {
+    it('is ready when actual behavior has a reproducible command and acceptance criteria', () => {
+      const result = runScript([
+        '--body-file',
+        writeBody(READY_BUG_BODY),
+        '--labels',
+        'bug',
+        '--json',
+      ]);
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout)).toEqual({ ready: true, reasons: [] });
+    });
+
+    it.each(['npm test', 'pnpm vitest run', 'yarn test', 'npx tsx repro.ts', 'bun test'])(
+      'accepts `%s` as a reproducible command',
+      (command) => {
+        const body = READY_BUG_BODY.replace('npm test', command);
+        const result = runScript(['--body-file', writeBody(body), '--labels', 'bug', '--json']);
+        expect(result.status).toBe(0);
+        expect(JSON.parse(result.stdout).ready).toBe(true);
+      }
+    );
+
+    it('is not ready when actual behavior lacks a reproducible command', () => {
+      const body = READY_BUG_BODY.replace('Running `npm test` fails', 'It fails');
+      const result = runScript(['--body-file', writeBody(body), '--labels', 'bug', '--json']);
+      expect(result.status).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.ready).toBe(false);
+      expect(parsed.reasons.join('\n')).toMatch(/reproducible JavaScript\/TypeScript/);
+    });
+
+    it('is not ready when acceptance criteria has no checklist item', () => {
+      const body = READY_BUG_BODY.replace('- [ ] The error no longer occurs', 'The error is gone.');
+      const result = runScript(['--body-file', writeBody(body), '--labels', 'bug', '--json']);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.ready).toBe(false);
+      expect(parsed.reasons.join('\n')).toMatch(/checklist item/);
+    });
+
+    it('treats `_No response_` form placeholders as empty', () => {
+      const body = READY_BUG_BODY.replace(
+        'Running `npm test` fails with `Error: request failed with status 404`.',
+        '_No response_'
+      );
+      const result = runScript(['--body-file', writeBody(body), '--labels', 'bug', '--json']);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.ready).toBe(false);
+      expect(parsed.reasons.join('\n')).toMatch(/Actual Behavior/);
+    });
+
+    it('ignores section content inside HTML comments', () => {
+      const body = READY_BUG_BODY.replace(
+        'Running `npm test` fails with `Error: request failed with status 404`.',
+        '<!-- mention npm here to sneak past the check -->'
+      );
+      const result = runScript(['--body-file', writeBody(body), '--labels', 'bug', '--json']);
+      expect(JSON.parse(result.stdout).ready).toBe(false);
+    });
+  });
+
+  describe('enhancement criteria', () => {
+    it('is ready with desired behavior and checklist acceptance criteria', () => {
+      const result = runScript([
+        '--body-file',
+        writeBody(READY_ENHANCEMENT_BODY),
+        '--labels',
+        'enhancement',
+        '--json',
+      ]);
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout)).toEqual({ ready: true, reasons: [] });
+    });
+
+    it('is not ready without a desired behavior section', () => {
+      const body = READY_ENHANCEMENT_BODY.replace('### Desired Behavior', '### Something Else');
+      const result = runScript([
+        '--body-file',
+        writeBody(body),
+        '--labels',
+        'enhancement',
+        '--json',
+      ]);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.ready).toBe(false);
+      expect(parsed.reasons.join('\n')).toMatch(/Desired Behavior/);
+    });
+  });
+
+  describe('label gating', () => {
+    it('is not ready without a bug or enhancement label', () => {
+      const result = runScript([
+        '--body-file',
+        writeBody(READY_BUG_BODY),
+        '--labels',
+        '',
+        '--json',
+      ]);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.ready).toBe(false);
+      expect(parsed.reasons.join('\n')).toMatch(/neither the `bug` nor `enhancement` label/);
+    });
+
+    it('matches labels case-insensitively', () => {
+      const result = runScript([
+        '--body-file',
+        writeBody(READY_BUG_BODY),
+        '--labels',
+        'Bug',
+        '--json',
+      ]);
+      expect(JSON.parse(result.stdout).ready).toBe(true);
+    });
+  });
+
+  describe('CLI contract', () => {
+    it('exits 0 in --json mode even when the issue is not ready (pipefail-safe)', () => {
+      const result = runScript([
+        '--body-file',
+        writeBody('no sections here'),
+        '--labels',
+        'bug',
+        '--json',
+      ]);
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout).ready).toBe(false);
+    });
+
+    it('exits 1 in human-readable mode when the issue is not ready', () => {
+      const result = runScript(['--body-file', writeBody('no sections here'), '--labels', 'bug']);
+      expect(result.status).toBe(1);
+      expect(result.stdout).toMatch(/does not meet ready-for-dev criteria/);
+    });
+
+    it('exits 0 in human-readable mode when the issue is ready', () => {
+      const result = runScript(['--body-file', writeBody(READY_BUG_BODY), '--labels', 'bug']);
+      expect(result.status).toBe(0);
+      expect(result.stdout).toMatch(/meets ready-for-dev criteria/);
+    });
+
+    it('reads body and labels from a GitHub event payload', () => {
+      const eventPath = join(dir, 'event.json');
+      writeFileSync(
+        eventPath,
+        JSON.stringify({
+          issue: { body: READY_BUG_BODY, labels: [{ name: 'bug' }] },
+        })
+      );
+      const result = runScript(['--event-path', eventPath, '--json']);
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout).ready).toBe(true);
+    });
+
+    it('falls back to GITHUB_EVENT_PATH when --event-path is not passed', () => {
+      const eventPath = join(dir, 'event.json');
+      writeFileSync(
+        eventPath,
+        JSON.stringify({
+          issue: { body: 'empty', labels: [] },
+        })
+      );
+      const envWithoutEventPath = Object.fromEntries(
+        Object.entries(process.env).filter(([key]) => key !== 'GITHUB_EVENT_PATH')
+      );
+      const result = spawnSync(process.execPath, [SCRIPT, '--json'], {
+        encoding: 'utf8',
+        env: { ...envWithoutEventPath, GITHUB_EVENT_PATH: eventPath },
+      });
+      expect(result.status).toBe(0);
+      expect(JSON.parse(result.stdout).ready).toBe(false);
+    });
+  });
+});
diff --git a/src/__tests__/pr-description-check.test.ts b/src/__tests__/pr-description-check.test.ts
new file mode 100644
index 0000000..9b1fd36
--- /dev/null
+++ b/src/__tests__/pr-description-check.test.ts
@@ -0,0 +1,290 @@
+/**
+ * Unit tests for .github/scripts/check-pr-description.mjs and the companion
+ * refresh/post-comment scripts.
+ *
+ * The PR gate is exercised through its real CLI against a real local HTTP
+ * server standing in for the GitHub API (via GITHUB_API_URL), so the tests
+ * cover link extraction, the ready-for-dev label requirement, and the
+ * pre-rollout grandfathering without mocking the script's own logic.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer, IncomingMessage, Server, ServerResponse } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { AddressInfo } from 'node:net';
+
+const REPO_ROOT = resolve(__dirname, '../..');
+const PR_CHECK_SCRIPT = join(REPO_ROOT, '.github/scripts/check-pr-description.mjs');
+const COMMENT_SCRIPT = join(REPO_ROOT, '.github/scripts/post-readiness-comment.mjs');
+const REFRESH_SCRIPT = join(REPO_ROOT, '.github/scripts/refresh-linked-pr-checks.mjs');
+
+interface RunResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+// Async spawn, not spawnSync: the fake GitHub API server lives in this same
+// process, so a synchronous spawn would block the event loop and deadlock
+// against the child's fetch.
+function runScript(
+  script: string,
+  args: string[],
+  env: NodeJS.ProcessEnv = {}
+): Promise<RunResult> {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      env: { ...process.env, ...env },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', rejectPromise);
+    child.on('close', (status) => resolvePromise({ status, stdout, stderr }));
+  });
+}
+
+describe('check-pr-description', () => {
+  let dir: string;
+  let server: Server;
+  let apiRoot: string;
+  // issue number -> labels + creation date served by the fake API
+  let issues: Record<string, { labels: string[]; created_at: string }>;
+
+  beforeAll(async () => {
+    server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      const match = /^\/repos\/[^/]+\/[^/]+\/issues\/(\d+)$/.exec(req.url ?? '');
+      const issue = match ? issues[match[1]] : undefined;
+      if (issue) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            labels: issue.labels.map((name) => ({ name })),
+            created_at: issue.created_at,
+          })
+        );
+      } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ message: 'Not Found' }));
+      }
+    });
+    await new Promise<void>((resolvePromise) => server.listen(0, '127.0.0.1', resolvePromise));
+    apiRoot = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  });
+
+  afterAll(async () => {
+    // close() alone waits for idle keep-alive connections held by the
+    // script's fetch client; destroy them so the close callback fires.
+    server.closeIdleConnections();
+    await new Promise<void>((resolvePromise, rejectPromise) =>
+      server.close((error) => (error ? rejectPromise(error) : resolvePromise()))
+    );
+  });
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'pr-description-'));
+    issues = {};
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function writeBody(body: string): string {
+    const file = join(dir, 'pr-body.md');
+    writeFileSync(file, body);
+    return file;
+  }
+
+  function runGate(body: string, withApi = false): Promise<RunResult> {
+    const args = ['--body-file', writeBody(body)];
+    const env: NodeJS.ProcessEnv = {};
+    if (withApi) {
+      args.push('--repo', 'OpenHands/typescript-client');
+      env.GITHUB_API_URL = apiRoot;
+      env.GITHUB_TOKEN = 'test-token';
+    }
+    return runScript(PR_CHECK_SCRIPT, args, env);
+  }
+
+  describe('link extraction (local mode, no token)', () => {
+    it('passes when the body links an issue with a keyword', async () => {
+      const result = await runGate('## Summary\n\nFixes #357\n');
+      expect(result.status).toBe(0);
+    });
+
+    it('accepts a bare #123 reference inside the Issue Number section', async () => {
+      const result = await runGate('## Summary\n\nStuff.\n\n## Issue Number\n\n#357\n');
+      expect(result.status).toBe(0);
+    });
+
+    it('ignores a bare #123 reference outside the Issue Number section', async () => {
+      const result = await runGate('## Summary\n\nSee #357 for context.\n');
+      expect(result.status).toBe(1);
+      expect(result.stdout).toMatch(/Link an issue/);
+    });
+
+    it('fails when no issue is linked', async () => {
+      const result = await runGate('## Summary\n\nNo links here.\n');
+      expect(result.status).toBe(1);
+      expect(result.stdout).toMatch(/::error::/);
+    });
+  });
+
+  describe('linked-issue readiness (API mode)', () => {
+    it('passes when the linked issue carries ready-for-dev', async () => {
+      issues['357'] = { labels: ['ready-for-dev'], created_at: '2026-08-24T01:00:00Z' };
+      const result = await runGate('Fixes #357', true);
+      expect(result.status).toBe(0);
+    });
+
+    it('blocks when a newly created linked issue lacks ready-for-dev', async () => {
+      issues['357'] = { labels: ['enhancement'], created_at: '2026-08-26T01:00:00Z' };
+      const result = await runGate('Fixes #357', true);
+      expect(result.status).toBe(1);
+      expect(result.stdout).toMatch(/#357/);
+      expect(result.stdout).toMatch(/ready-for-dev/);
+    });
+
+    it('grandfathers issues created before the readiness rollout', async () => {
+      issues['357'] = { labels: ['enhancement'], created_at: '2026-08-24T01:00:00Z' };
+      const result = await runGate('Fixes #357', true);
+      expect(result.status).toBe(0);
+    });
+
+    it('fails when every referenced issue 404s', async () => {
+      const result = await runGate('Fixes #99999', true);
+      expect(result.status).toBe(1);
+      expect(result.stdout).toMatch(/could not be found/);
+    });
+
+    it('passes when at least checking proceeds past a 404 among ready issues', async () => {
+      issues['357'] = { labels: ['ready-for-dev'], created_at: '2026-08-26T01:00:00Z' };
+      const result = await runGate('Fixes #357 and closes #99999', true);
+      expect(result.status).toBe(0);
+    });
+  });
+
+  describe('event payload mode', () => {
+    it('reads the PR body and repo from GITHUB_EVENT_PATH', async () => {
+      issues['357'] = { labels: ['ready-for-dev'], created_at: '2026-08-26T01:00:00Z' };
+      const eventPath = join(dir, 'event.json');
+      writeFileSync(
+        eventPath,
+        JSON.stringify({
+          pull_request: { body: 'Fixes #357' },
+          repository: { full_name: 'OpenHands/typescript-client' },
+        })
+      );
+      const result = await runScript(PR_CHECK_SCRIPT, ['--event-path', eventPath], {
+        GITHUB_API_URL: apiRoot,
+        GITHUB_TOKEN: 'test-token',
+      });
+      expect(result.status).toBe(0);
+    });
+  });
+});
+
+describe('post-readiness-comment', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'readiness-comment-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('prints a ready comment with the idempotency marker in --dry-run mode', async () => {
+    const result = await runScript(COMMENT_SCRIPT, ['--dry-run', '--ready']);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('<!-- issue-readiness-check -->');
+    expect(result.stdout).toContain('`ready-for-dev` label applied');
+  });
+
+  it('prints not-ready reasons from a reasons file in --dry-run mode', async () => {
+    const reasonsFile = join(dir, 'reasons.txt');
+    writeFileSync(reasonsFile, 'Missing Acceptance Criteria\nMissing npm command\n');
+    const result = await runScript(COMMENT_SCRIPT, ['--dry-run', '--reasons-file', reasonsFile]);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('<!-- issue-readiness-check -->');
+    expect(result.stdout).toContain('- Missing Acceptance Criteria');
+    expect(result.stdout).toContain('- Missing npm command');
+    expect(result.stdout).toContain('`npm`, `pnpm`, `yarn`, or `npx`');
+  });
+});
+
+describe('refresh-linked-pr-checks', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'refresh-pr-checks-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function writeEvent(payload: unknown): string {
+    const file = join(dir, 'event.json');
+    writeFileSync(file, JSON.stringify(payload));
+    return file;
+  }
+
+  it('no-ops for label events other than ready-for-dev', async () => {
+    const eventPath = writeEvent({
+      action: 'labeled',
+      label: { name: 'bug' },
+      issue: { number: 1 },
+      repository: { full_name: 'OpenHands/typescript-client' },
+    });
+    const result = await runScript(REFRESH_SCRIPT, ['--event-path', eventPath]);
+    expect(result.status).toBe(0);
+    expect(result.stdout).not.toMatch(/refreshing PR gates/);
+  });
+
+  it('no-ops for non-label actions', async () => {
+    const eventPath = writeEvent({
+      action: 'opened',
+      issue: { number: 1 },
+      repository: { full_name: 'OpenHands/typescript-client' },
+    });
+    const result = await runScript(REFRESH_SCRIPT, ['--event-path', eventPath]);
+    expect(result.status).toBe(0);
+  });
+
+  it('no-ops when the event payload lacks repository or issue', async () => {
+    const eventPath = writeEvent({ action: 'labeled', label: { name: 'ready-for-dev' } });
+    const result = await runScript(REFRESH_SCRIPT, ['--event-path', eventPath]);
+    expect(result.status).toBe(0);
+  });
+
+  it('exits 0 without an event payload', async () => {
+    const envWithoutEventPath = Object.fromEntries(
+      Object.entries(process.env).filter(([key]) => key !== 'GITHUB_EVENT_PATH')
+    );
+    const result = await new Promise<RunResult>((resolvePromise, rejectPromise) => {
+      const child = spawn(process.execPath, [REFRESH_SCRIPT], { env: envWithoutEventPath });
+      let stdout = '';
+      let stderr = '';
+      child.stdout.on('data', (chunk) => {
+        stdout += chunk;
+      });
+      child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+      });
+      child.on('error', rejectPromise);
+      child.on('close', (status) => resolvePromise({ status, stdout, stderr }));
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout).toMatch(/nothing to refresh/);
+  });
+});