[WIP] Clarify safe-jobs vs safe-outputs.jobs usage and schema definition

[Copilot]

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Clarify safe-jobs vs safe-outputs.jobs usage and schema definition</issue_title>
<issue_description>The safe-jobs top-level frontmatter field is accessed in compiler code but is not defined in the schema, and its relationship to safe-outputs.jobs is unclear, leading to API confusion and potential misuse.

Source

Extracted from Schema Consistency Analysis discussion githubnext/gh-aw#11121 and Safe-Outputs Comprehensive Audit githubnext/gh-aw#12389

Problem

Current State:

• safe-jobs is accessed in pkg/workflow/safe_jobs.go:40 via frontmatter["safe-jobs"]
• NOT defined in main_workflow_schema.json (0 of 38 top-level properties)
• Code comment suggests: "User workflows should use 'safe-outputs.jobs' syntax; the top-level 'safe-jobs' key is NOT supported."
• Yet compiler still accesses frontmatter["safe-jobs"] directly

Confusion:

• Is safe-jobs a valid user-facing field or internal-only?
• What's the relationship between safe-jobs and safe-outputs.jobs?
• Should users use one, the other, or both?

Files Affected

1. pkg/workflow/safe_jobs.go - Contains implementation and comment
2. pkg/parser/schemas/main_workflow_schema.json - Missing schema definition
3. docs/src/content/docs/reference/frontmatter.md - Not documented
4. docs/src/content/docs/reference/compilation-process.md:270 - Mentions but doesn't explain

Suggested Resolution (Choose One)

Option 1: Internal-Only (Recommended)

• Remove frontmatter["safe-jobs"] direct access
• Document that users MUST use safe-outputs.jobs syntax
• Update all examples to show correct usage

Option 2: User-Facing

• Add safe-jobs to schema with proper validation
• Document when to use safe-jobs vs safe-outputs.jobs
• Add examples showing both approaches

Option 3: Alias Pattern

• Keep both but document as aliases
• Add schema validation for consistency
• Show migration path in docs

Investigation Needed

1. Review git history: Why was safe-jobs added? Was it meant to be user-facing?
2. Check test files: Are there tests using top-level safe-jobs?
3. Search workflows: Are any workflows currently using safe-jobs directly?
4. Determine intended behavior: What should happen if both are specified?

Success Criteria

• Clear decision made: internal-only, user-facing, or alias
• Schema updated accordingly
• Documentation reflects correct usage
• Code comments explain the pattern
• No ambiguity about which syntax to use

Priority

Medium - API clarity issue that could lead to misuse, but not blocking current functionality. Important for maintaining clean API surface.

Estimated Effort

3-4 hours - Requires investigation, decision-making, code updates, schema changes, and documentation.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 12, 2026, 1:34 AM UTC

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

• Fixes [Code Quality] Clarify safe-jobs vs safe-outputs.jobs usage and schema definition #12417

---

💡 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.