feat: add ready-for-dev issue and PR readiness gates

[neubig]

• A human has tested these changes.

---

Why

Issue #357 asks for a ready-for-dev issue workflow with CI enforcement, modeled on the equivalent automation in OpenHands/OpenHands and OpenHands/software-agent-sdk but repo-appropriate for this TypeScript client (Node scripts instead of Python, Jest tests instead of pytest, npm-ecosystem reproduction commands).

Summary

• Issue readiness gate (.github/workflows/issue-readiness-check.yml + .github/scripts/check-issue-readiness.mjs): evaluates bug/enhancement issues against type-specific criteria. Bugs need a reproducible JavaScript/TypeScript command (npm, pnpm, yarn, or npx) in ### Actual Behavior plus an Acceptance Criteria checklist item; enhancements need ### Desired Behavior plus the checklist. Adds/removes the ready-for-dev label idempotently.
• Pipefail-safe not-ready behavior: in --json mode the readiness script always exits 0 and the workflow branches on the JSON, so a not-ready issue never fails the workflow under set -euo pipefail.
• Idempotent feedback comments (.github/scripts/post-readiness-comment.mjs): a single comment upserted by a hidden <!-- issue-readiness-check --> marker, posted on open/reopen and on label transitions only.
• PR gate for linked issues (.github/workflows/pr-description-check.yml + .github/scripts/check-pr-description.mjs): pull_request_target check that fails unless every linked issue (Fixes #N, or bare #N in ## Issue Number) exists and carries ready-for-dev; issues created before the rollout date (2026-08-25) are grandfathered so existing PRs are not retroactively blocked. Bot PRs (dependabot, release-please) are exempt.
• Label transitions refresh linked PR checks (.github/scripts/refresh-linked-pr-checks.mjs): when ready-for-dev is added/removed on an issue, the latest PR Description Check run is re-triggered for every open PR that links it (via cross-reference timeline events), so the gate never goes stale.
• Issue forms (.github/ISSUE_TEMPLATE/bug_report.yml, feature_request.yml) so the sections the checker evaluates actually exist for reporters.
• Tests (src/__tests__/issue-readiness.test.ts, src/__tests__/pr-description-check.test.ts): 35 Jest tests running the real script CLIs in child processes, including the --json exit-0 contract and the linked-issue gate against a local HTTP server standing in for the GitHub API (no mocks).

Issue Number

Fixes #357

How to Test

• npm run lint && npm run build && npm run test:coverage && npm run format:check all pass locally (343 tests, 20 suites).
• The new tests exercise the scripts end-to-end: npx jest src/__tests__/issue-readiness.test.ts src/__tests__/pr-description-check.test.ts.
• After merge: open a test issue via the bug form with/without an npm-style repro command and watch the ready-for-dev label and feedback comment; open a PR linking a non-ready issue and confirm the PR Description Check fails, then passes once the issue becomes ready (label change re-runs the check).

Note: READY_FOR_DEV_ROLLOUT_ISO in check-pr-description.mjs is set to 2026-08-25 (day after authoring). If this PR lands later, bump the constant to the day after merge.

Video/Screenshots

N/A — CI/workflow-only change.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

• The ready-for-dev label already exists in this repo.
• The new pull_request_target workflow only checks out the base branch SHA (trusted code) and never PR code, matching the security pattern used by the existing pr.yml.
• This PR was created by an AI agent (OpenHands) on behalf of the user.

@neubig can click here to continue refining the PR

[github-actions]

Endpoint audit

⚠️ 12 actionable Agent Server contract divergence(s) · report-only

Contract: pinned release artifact

Category	Count
Actionable client-only calls	0
Actionable server-only operations	12
Documented non-divergences	13
Agent Server contract operations	123
Audited handwritten client endpoints	119

Actionable client-only calls (0)

none

Actionable server-only operations (12)

• DELETE /api/llm/provider-connections/{}
• GET /api/conversations/{}/events
• GET /api/file/archive
• GET /api/git/commits
• GET /api/git/commits/{}/changes
• GET /api/init
• GET /api/llm/provider-connections
• PATCH /api/llm/provider-connections/{}
• POST /api/conversations/{}/load_plugin
• POST /api/file/create_directory
• POST /api/init
• POST /api/llm/provider-connections

Documented non-divergences (13)

Client calls intentionally absent from the filtered contract (11)

• GET /
• GET /alive
• GET /health
• GET /ready
• GET /server_info

Reason: Operational Agent Server endpoints intentionally excluded from the filtered public release artifact.
Owner: OpenHands runtime maintainers

• DELETE /api/meta-profiles/{}
• GET /api/meta-profiles
• GET /api/meta-profiles/{}
• POST /api/meta-profiles/{}
• POST /api/meta-profiles/{}/activate

Reason: Client-ahead API stacked on the pending Agent Server meta-profiles implementation.
Owner: OpenHands SDK maintainers
Tracking: OpenHands/software-agent-sdk#3744

• POST /api/profiles/{}/validate

Reason: Client-ahead API stacked on the pending Agent Server pre-flight LLM validation endpoint.
Owner: OpenHands TypeScript client maintainers
Tracking: OpenHands/software-agent-sdk#4422

Server operations covered by an exposed browser URL (2)

• GET /api/conversations/{}/workspace
• GET /api/conversations/{}/workspace/{}

Reason: RemoteWorkspace.startWorkspaceSession exposes these authenticated URLs for browser iframe and file requests; they are not HttpClient method calls.
Owner: OpenHands TypeScript client maintainers