[plan] Add inline $comment documentation to schema files for intentional differences

[github-actions]

Objective

Add $comment fields to schema files explaining why main workflows and included files have different structures for tools, engine, and required fields.

Context

The schema consistency audit found 3 critical areas where schemas intentionally differ for security reasons, but lack documentation explaining the design decision.

Approach

Add $comment fields to pkg/parser/schemas/included_file_schema.json:

1. tools.additionalProperties - Explain simplified MCP configuration:

"$comment": "Simplified MCP configuration for included files. Full MCP configuration (command, args, env, etc.) is only available in main workflow files for security reasons. Included files use mcp references and allowed lists."

2. $defs.engine_config - Explain missing engine.command property:

"$comment": "The engine.command property is restricted in included files for security. Only main workflow files can specify custom engine executables."

3. Top-level required array - Explain no required fields:

"$comment": "Included files use applyTo patterns to determine when they apply, so the 'on' trigger field is not required. Main workflow files must specify 'on' to define trigger conditions."

Files to Modify

• pkg/parser/schemas/included_file_schema.json - Add 3 $comment fields

Acceptance Criteria

• $comment added to tools.additionalProperties explaining MCP restriction
• $comment added to $defs.engine_config explaining command restriction
• $comment added to top level explaining no required fields
• Comments are clear and explain the security rationale
• Schema still validates correctly with added comments
  Related to [plan] Document schema design philosophy and security model differences #10219

AI generated by Plan Command for discussion #10151

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster