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

[github-actions]

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 #11121 and Safe-Outputs Comprehensive Audit #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

[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

[pelikhan]

#12439