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

[Copilot]

All 6 recent Copilot agent PRs remain stuck in draft status. Agents lack instructions on when/how to mark PRs ready for review, and the existing safe output mechanism didn't support changing draft status.

Changes

• Enhanced update_pull_request safe output with:

  • Added draft boolean field to schema (supports marking PRs ready or converting back to draft)
  • Updated tool descriptions in both actions/setup/js/ and pkg/workflow/js/
  • Leverages existing github.rest.pulls.update API (no code changes needed)

• Added PR Completion Workflow section to AGENTS.md with:

  • 8-point completion criteria checklist (build, tests, lint, security, docs)
  • Instructions to use update_pull_request safe output with draft: false
  • Explanation of safe output benefits (security, auditability, validation)
  • Clear guidance on when to mark ready vs. keep as draft
  • Example NDJSON output format

Usage

Agents should mark PRs ready when all criteria pass using safe outputs:

{"type": "update_pull_request", "draft": false}

Benefits of safe output approach:

• 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
• Consistency: Uses same mechanism as other GitHub operations

Mark ready after make agent-finish succeeds and feedback is addressed. Keep as draft if tests fail, build broken, or security issues remain.

Context

Recent merged PRs (#8571, #8567, #8565) show agents successfully transition from draft→ready when given proper guidance. This codifies that pattern using the recommended safe outputs mechanism.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>🚨 Agent PR Completion Barrier: 6/6 PRs Stuck in Draft Status</issue_title>
<issue_description>## Problem

All 6 recent Copilot coding agent PRs are stuck in draft status with zero progression to "Ready for Review" or merge state. This represents a 100% stagnation rate and suggests a systematic barrier in the agent workflow completion process.

Affected PRs

PR #	Title	Comments	Created	Status
#8567	Verify YAML dependency migration	0	2026-01-02	Draft
#8566	Add test coverage for CLI completion	0	2026-01-02	Draft
#8565	Add completion descriptions	0	2026-01-02	Draft
#8564	Add --completions flag to init	0	2026-01-02	Draft
#8563	Fix awmg MCP config rewrite	0	2026-01-02	Draft
#8535	Enable MCP gateway	29	2026-01-01	Draft

Impact

Immediate:

• No agent outputs reaching production
• Agent effectiveness cannot be measured accurately
• Potential waste of computational resources

Systemic:

• Suggests gaps in agent workflow design
• May indicate missing "completion signals" in agent instructions
• Could affect user confidence in agent capabilities

Investigation Questions

1. Process Barriers:

   • Are agents waiting for explicit human review signals?
   • Do tests need to pass before draft → ready transition?
   • Is there a missing step in agent completion instructions?

2. Technical Blockers:

   • Are CI checks failing silently?
   • Do agents lack permissions to change PR status?
   • Is there a GitHub Actions workflow step missing?

3. Design Gaps:

   • Do agent prompts define "done" criteria clearly?
   • Should agents automatically transition to ready when criteria met?
   • Is human review always intended, or should some PRs auto-merge?

Recommended Actions

Immediate (Next 24-48 Hours)

1. Review PR Enable MCP gateway (awmg) in smoke-copilot-no-firewall workflow with built-in mode, fix compile timestamp handling, and enhance health check logging #8535 (29 comments, most active):

   • Analyze comment thread for completion signals
   • Identify what's preventing ready transition
   • Use as case study for systematic issue

2. Check Agent Instructions:

   • Review Copilot coding agent prompts
   • Verify if completion criteria are defined
   • Add explicit "mark ready when done" instructions if missing

3. Verify CI/Test Status:

   • Check if tests pass on these PRs
   • Verify CI checks are green
   • Identify any silent failures

Short-term (Next Week)

4. Add Completion Signals to agent prompts:

   • Define "done" criteria explicitly
   • Add instruction to transition draft → ready when criteria met
   • Consider auto-merge for certain PR types

5. Create PR Status Dashboard:

   • Track draft → ready → merged progression
   • Alert on PRs stuck in draft >24 hours
   • Measure agent completion rates

6. Document Best Practices:

   • When should agents create draft PRs?
   • What criteria mark a PR as "ready"?
   • Which PRs should auto-merge vs. require review?

Long-term

7. Implement Automated Health Checks:

   • Daily scan for stale draft PRs
   • Automatic reminders to move to ready
   • Metrics on draft dwell time

8. Agent Workflow Improvements:

   • Add "mark ready" step to agent job template
   • Implement progress checkpoints
   • Create completion validation logic

Success Criteria

• Root cause identified for 100% draft rate
• At least 1 of 6 PRs moves to ready or merged
• Agent instructions updated with completion signals
• Monitoring system in place for future tracking
• Documentation created for PR status workflows

Related

• Discussion: Agent Performance Report (created this run)
• Workflow: Copilot coding agent
• Meta-orchestrator: Agent Performance Analyzer

Priority

High - This affects all agent outputs and ecosystem health measurement.

---

Discovered by Agent Performance Analyzer

AI generated by Agent Performance Analyzer - Meta-Orchestrator

Comments on the Issue (you are @copilot in this section)

• Fixes 🚨 Agent PR Completion Barrier: 6/6 PRs Stuck in Draft Status #8569

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pelikhan]

@copilot use safe outputs

[Copilot]

@copilot use safe outputs

Done! Updated to use safe outputs mechanism:

Changes in commit 0f2452d:

• Added draft field to update_pull_request safe output schema
• Updated AGENTS.md to use safe output instead of direct GitHub MCP call
• Agents now output: {"type": "update_pull_request", "draft": false}

This provides better security (controlled permissions), auditability (logged actions), and validation (proper context checks) compared to direct MCP calls.