[Code Quality] Clarify safe-jobs field in schema and documentation

[github-actions]

Description

The safe-jobs field is accessed in compiler code (pkg/workflow/safe_jobs.go, compiler_orchestrator.go, compiler_safe_output_jobs.go) but is NOT defined in main_workflow_schema.json. Additionally, documentation is unclear whether this is user-facing or internal-only.

Background

Identified during the Schema Consistency Analysis on 2026-01-21. Analysis revealed:

• Used in code: 3 files access frontmatter["safe-jobs"]
• Schema status: NOT in main_workflow_schema.json (0 of 38 top-level properties)
• Documentation gap: Mentioned in compilation-process.md but not in frontmatter.md

Code comment from safe_jobs.go:38:

"User workflows should use 'safe-outputs.jobs' syntax; the top-level 'safe-jobs' key is NOT supported."

Contradiction: Code accesses safe-jobs despite comment saying it's not supported.

Impact

• Schema validation cannot catch invalid safe-jobs configurations
• No type checking or structure enforcement
• Developers confused about whether to use safe-jobs or safe-outputs.jobs
• Potential for malformed data causing runtime errors
• Documentation inconsistency

Suggested Changes

Option A: Make it User-Facing (if intentional)

1. Add to schema (pkg/parser/schemas/main_workflow_schema.json):

   {
     "safe-jobs": {
       "type": "object",
       "description": "Custom safe output jobs with specialized logic",
       "additionalProperties": {
         "type": "object",
         "properties": {
           "steps": { "type": "array" },
           "outputs": { "type": "object" }
         }
       }
     }
   }

2. Document in frontmatter reference (docs/src/content/docs/reference/frontmatter.md):

   • Add safe-jobs section
   • Explain difference from safe-outputs.jobs
   • Provide examples

3. Update code comment in safe_jobs.go:38 to reflect support

Option B: Keep it Internal-Only (if intentional)

1. Document as internal: Add clear comment in code explaining this is compiler-internal
2. Remove public mention: Delete reference from compilation-process.md:270
3. Add schema note: Document in schema comments that safe-jobs is reserved for internal use

Option C: Remove if Unused (if deprecated)

1. Remove code access: Delete frontmatter["safe-jobs"] accesses
2. Update schema: Add to deprecated/removed fields list
3. Migration guide: If users have safe-jobs, show how to migrate to safe-outputs.jobs

Files Affected

Code:

• pkg/workflow/safe_jobs.go (line 40)
• pkg/workflow/compiler_orchestrator.go (line 744)
• pkg/workflow/compiler_safe_output_jobs.go (lines 55-60)

Schema:

• pkg/parser/schemas/main_workflow_schema.json (add definition)

Documentation:

• docs/src/content/docs/reference/frontmatter.md (document or clarify)
• docs/src/content/docs/reference/compilation-process.md (line 270, update or remove)

Success Criteria

• Schema either includes safe-jobs with validation OR documents it as internal-only
• Documentation consistent with implementation
• Code comments align with actual usage
• No ambiguity for users about which field to use
• Schema validation catches configuration errors

Priority

MEDIUM - Affects schema validation and developer clarity

Estimated effort: 2-4 hours (depending on chosen option)

Source

Extracted from Schema Consistency Analysis discussion #11121

Analysis quote:

"🔴 Issue #2: safe-jobs Field Missing from Schema
Problem: The safe-jobs top-level field is accessed in compiler code but NOT defined in main_workflow_schema.json.
Impact: Schema validation cannot catch invalid safe-jobs configurations, no type checking or structure enforcement, potential for malformed data causing runtime errors"

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 5, 2026, 12:26 PM 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