Document safe-jobs as internal implementation detail distinct from safe-outputs.jobs

[Copilot]

The safe-jobs field access in compiler code caused confusion about whether it was missing from the schema. Reality: safe-outputs.jobs is the user-facing API (fully supported in schema), while safe-jobs is an internal parsing key never exposed to users.

Architecture

# User writes this in frontmatter:
safe-outputs:
  jobs:
    my-job:
      steps: [...]

# Compiler internally transforms to:
safe-jobs:  # Internal only - not in schema
  my-job: {...}

The extractSafeJobsFromFrontmatter() function reads safe-outputs.jobs and temporarily wraps it with a safe-jobs key for parseSafeJobsConfig() to process.

Changes

• Code comments (pkg/workflow/safe_jobs.go): Added package-level architecture overview; clarified parseSafeJobsConfig() and extractSafeJobsFromFrontmatter() as internal implementation details
• Test comments (pkg/workflow/safe_jobs_test.go): Documented internal-only testing approach
• Documentation (docs/src/content/docs/reference/safe-outputs.md): Emphasized user-facing safe-outputs.jobs: syntax
• Documentation (docs/src/content/docs/reference/compilation-process.md): Changed "safe-jobs" reference to correct user-facing "safe-outputs.jobs:"
• Schema (pkg/parser/schemas/main_workflow_schema.json): Added $comment to safe-outputs.jobs property documenting internal transformation

No functional changes. Zero user impact.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Clarify safe-jobs field in schema and documentation</issue_title>
<issue_description>## 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 githubnext/gh-aw#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

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

• Fixes [Code Quality] Clarify safe-jobs field in schema and documentation #11265

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.