Add safe output support for PR draft status and completion workflow instructions

AGENTS.md

@@ -731,6 +731,73 @@ make minor-release  # Automated via GitHub Actions
 For investigating and resolving workflow issues:
 - **[Workflow Health Monitoring](.github/aw/runbooks/workflow-health.md)** - Comprehensive runbook for diagnosing missing-tool errors, authentication failures, MCP configuration issues, and safe-input/output problems. Includes step-by-step investigation procedures, resolution examples, and case studies from real incidents.
 
+## PR Completion Workflow
+
+When working on pull requests created by Copilot coding agent, follow this completion workflow:
+
+### Completion Criteria
+
+A PR is ready to be marked "ready for review" when ALL of the following are true:
+
+- ✅ All planned changes are complete
+- ✅ Code compiles successfully (`make build`)
+- ✅ All tests pass (`make test` or `make test-unit`)
+- ✅ Code is formatted and linted (`make fmt` and `make lint`)
+- ✅ Workflows recompiled if needed (`make recompile`)
+- ✅ Code review feedback addressed (if any)
+- ✅ No blocking security issues
+- ✅ Documentation updated (if applicable)
+
+### Marking PR as Ready
+
+**Use safe outputs to mark PRs as ready for review.**
+
+Agents should use the `update_pull_request` safe output tool to change the draft status:
+
+```
+update_pull_request with:
+- draft: false
+- pull_request_number: <PR number from context>
+```
+
+This safe output approach provides:
+- **Security**: Operates through controlled safe output jobs with minimal permissions
+- **Auditability**: All PR status changes are logged and trackable
+- **Validation**: Ensures proper permissions and context before execution
+
+**Example NDJSON output**:
+```json
+{"type": "update_pull_request", "draft": false}
+```
+
+**When to mark ready:**
+1. After completing all work and running `make agent-finish` successfully
+2. After addressing all code review comments that you agree with
+3. When you believe the PR is ready for human review and potential merge
+
+**When NOT to mark ready:**
+- Tests are failing
+- Build is broken
+- There are unresolved TODO comments in your changes
+- You're waiting for feedback on an approach
+- Security vulnerabilities remain unfixed
+
+### Example Workflow
+
+```bash
+# 1. Complete all changes
+git status
+git diff
+
+# 2. Validate everything
+make agent-finish  # Runs build, test, recompile, fmt, lint
+
+# 3. If all validations pass, output safe output to mark PR as ready
+# The agent outputs NDJSON with type: "update_pull_request" and draft: false
+```
+
+**Note**: The PR will remain in draft status until you explicitly mark it ready using the safe output. This is intentional - it prevents premature review requests while work is in progress.
+
 ## Available Skills Reference
 
 Skills provide specialized, detailed knowledge on specific topics. **Use them only when needed** - don't load skills preemptively.

actions/setup/js/safe_outputs_tools.json

@@ -409,7 +409,7 @@
   },
   {
     "name": "update_pull_request",
-    "description": "Update an existing GitHub pull request's title or body. Supports replacing, appending to, or prepending content to the body. Title is always replaced. Only the fields you specify will be updated; other fields remain unchanged.",
+    "description": "Update an existing GitHub pull request's title, body, or draft status. Supports replacing, appending to, or prepending content to the body. Title is always replaced. Only the fields you specify will be updated; other fields remain unchanged.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -426,6 +426,10 @@
           "enum": ["replace", "append", "prepend"],
           "description": "How to update the PR body: 'replace' (default - completely overwrite), 'append' (add to end with separator), or 'prepend' (add to start with separator). Title is always replaced."
         },
+        "draft": {
+          "type": "boolean",
+          "description": "Set PR draft status. Use false to mark a draft PR as ready for review, or true to convert a ready PR back to draft status."
+        },
         "pull_request_number": {
           "type": ["number", "string"],
           "description": "Pull request number to update. This is the numeric ID from the GitHub URL (e.g., 234 in github.com/owner/repo/pull/234). Required when the workflow target is '*' (any PR)."

pkg/workflow/js/safe_outputs_tools.json

@@ -409,7 +409,7 @@
   },
   {
     "name": "update_pull_request",
-    "description": "Update an existing GitHub pull request's title or body. Supports replacing, appending to, or prepending content to the body. Title is always replaced. Only the fields you specify will be updated; other fields remain unchanged.",
+    "description": "Update an existing GitHub pull request's title, body, or draft status. Supports replacing, appending to, or prepending content to the body. Title is always replaced. Only the fields you specify will be updated; other fields remain unchanged.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -426,6 +426,10 @@
           "enum": ["replace", "append", "prepend"],
           "description": "How to update the PR body: 'replace' (default - completely overwrite), 'append' (add to end with separator), or 'prepend' (add to start with separator). Title is always replaced."
         },
+        "draft": {
+          "type": "boolean",
+          "description": "Set PR draft status. Use false to mark a draft PR as ready for review, or true to convert a ready PR back to draft status."
+        },
         "pull_request_number": {
           "type": ["number", "string"],
           "description": "Pull request number to update. This is the numeric ID from the GitHub URL (e.g., 234 in github.com/owner/repo/pull/234). Required when the workflow target is '*' (any PR)."