Document max parameter limitation for create-pull-request safe-output

[Copilot]

The create-pull-request safe-output type silently ignores the max parameter and always creates exactly 1 PR per workflow run. This is enforced in code but was not documented in the JSON schema, leading to potential user confusion.

Changes

• Updated pkg/parser/schemas/main_workflow_schema.json to document the limitation in the create-pull-request description
• Added rationale: prevents excessive automated PRs and maintains repository integrity

Context

The max=1 enforcement exists in pkg/workflow/create_pull_request.go:

// Note: max parameter is not supported for pull requests (always limited to 1)
// Override any user-specified max value to enforce the limit
pullRequestsConfig.Max = 1

Other safe-output types (create-issue, add-comment, etc.) support configurable max values (1-100). Only create-pull-request and create-agent-task have this restriction, and create-agent-task already documents it via schema constraints (minimum: 1, maximum: 1).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Document safe-outputs parameter limitations in schema</issue_title>
<issue_description>## Objective
Add documentation for safe-outputs configuration parameter limitations, specifically that pull requests don't support the max parameter (always limited to 1).

Context

Code comments indicate the max parameter is not supported for pull requests, but this limitation isn't documented in the schema. Users may try to configure max for PRs without knowing it's not applicable. Part of discussion #4010.

Current State

Code comment: pkg/workflow/safe_outputs.go

// Note: max parameter is not supported for pull requests (always limited to 1)

Schema location: pkg/parser/schemas/main_workflow_schema.json - create-pull-request configuration

Implementation Steps

1. Locate create-pull-request safe-output configuration in schema
2. Add note about max parameter limitation
3. Review if other safe-output types have similar limitations
4. Document all discovered limitations

Proposed Changes

Add to create-pull-request schema description:

"Note: max parameter not applicable for pull requests (always limited to 1 PR per workflow run)"

Files to Modify

• pkg/parser/schemas/main_workflow_schema.json - Update create-pull-request safe-output description

Additional Investigation

Check other safe-output types for similar limitations:

• create-issue
• create-discussion
• add-comment
• create-pull-request-review-comment
• update-issue

Acceptance Criteria

• create-pull-request schema documents max parameter limitation
• Any other safe-output parameter limitations are documented
• Documentation clearly explains why limitation exists
• Schema validation passes with make test

Related Information

• Safe-outputs logic in pkg/workflow/safe_outputs.go
• This is a design decision to prevent workflow runs from creating excessive PRs

AI generated by Plan Command for discussion #4010</issue_description>

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

• Fixes [task] Document safe-outputs parameter limitations in schema #4027

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull Request Overview

This PR documents that the create-pull-request safe-output type does not support the max parameter and is always limited to creating exactly 1 pull request per workflow run. The limitation was enforced in the code but not documented in the JSON schema, which could lead to user confusion.

Key Changes

• Added documentation to the create-pull-request schema description explaining the max=1 limitation
• Included rationale explaining this prevents excessive automated PRs and maintains repository integrity

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.