Update schema documentation for removed included_file_schema and remove deprecated safe-jobs field

.github/workflows/schema-consistency-checker.md

@@ -82,7 +82,6 @@ Strategy database structure:
 
 **Key files to analyze:**
 - `pkg/parser/schemas/main_workflow_schema.json`
-- `pkg/parser/schemas/included_file_schema.json`
 - `pkg/parser/schemas/mcp_config_schema.json`
 - `pkg/parser/frontmatter.go` and `pkg/parser/*.go`
 - `pkg/workflow/compiler.go` - main workflow compiler
@@ -96,7 +95,7 @@ Strategy database structure:
 - `pkg/workflow/engine_firewall_support.go` - firewall support checking
 - `pkg/workflow/strict_mode.go` - strict mode validation
 - `pkg/workflow/stop_after.go` - stop-after processing
-- `pkg/workflow/safe_jobs.go` - safe-jobs configuration
+- `pkg/workflow/safe_jobs.go` - safe-jobs configuration (internal - accessed via safe-outputs.jobs)
 - `pkg/workflow/runtime_setup.go` - runtime overrides
 - `pkg/workflow/github_token.go` - github-token configuration
 - `pkg/workflow/*.go` (all workflow processing files that use frontmatter)

docs/src/content/docs/reference/safe-outputs.md

@@ -79,6 +79,9 @@ The agent requests issue creation; a separate job with `issues: write` creates i
 
 Create custom post-processing jobs registered as Model Context Protocol (MCP) tools. Support standard GitHub Actions properties and auto-access agent output via `$GH_AW_AGENT_OUTPUT`. See [Custom Safe Output Jobs](/gh-aw/guides/custom-safe-outputs/).
 
+> [!NOTE]
+> **Internal Implementation**: Custom safe output jobs are internally referred to as "safe-jobs" in the compiler code (`pkg/workflow/safe_jobs.go`), but they are user-facing only through the `safe-outputs.jobs:` configuration. The top-level `safe-jobs:` key is deprecated and not supported.
+
 ### Issue Creation (`create-issue:`)
 
 Creates GitHub issues based on workflow output.

pkg/workflow/frontmatter_types.go

@@ -69,7 +69,6 @@ type FrontmatterConfig struct {
 	Runtimes         map[string]any     `json:"runtimes,omitempty"`    // Deprecated: use RuntimesTyped
 	Jobs             map[string]any     `json:"jobs,omitempty"`        // Custom workflow jobs (too dynamic to type)
 	SafeOutputs      *SafeOutputsConfig `json:"safe-outputs,omitempty"`
-	SafeJobs         map[string]any     `json:"safe-jobs,omitempty"` // Deprecated, use SafeOutputs.Jobs
 	SafeInputs       *SafeInputsConfig  `json:"safe-inputs,omitempty"`
 	PermissionsTyped *PermissionsConfig `json:"-"` // New typed field (not in JSON to avoid conflict)
 
@@ -435,9 +434,6 @@ func (fc *FrontmatterConfig) ToMap() map[string]any {
 		// Convert SafeOutputsConfig to map - would need a ToMap method
 		result["safe-outputs"] = fc.SafeOutputs
 	}
-	if fc.SafeJobs != nil {
-		result["safe-jobs"] = fc.SafeJobs
-	}
 	if fc.SafeInputs != nil {
 		// Convert SafeInputsConfig to map - would need a ToMap method
 		result["safe-inputs"] = fc.SafeInputs

pkg/workflow/frontmatter_types_test.go

@@ -314,12 +314,14 @@ func TestParseFrontmatterConfig(t *testing.T) {
 
 	t.Run("preserves complex nested structures", func(t *testing.T) {
 		frontmatter := map[string]any{
-			"safe-jobs": map[string]any{
-				"custom-job": map[string]any{
-					"conditions": []any{
-						map[string]any{
-							"field": "status",
-							"value": "success",
+			"safe-outputs": map[string]any{
+				"jobs": map[string]any{
+					"custom-job": map[string]any{
+						"conditions": []any{
+							map[string]any{
+								"field": "status",
+								"value": "success",
+							},
 						},
 					},
 				},
@@ -331,13 +333,17 @@ func TestParseFrontmatterConfig(t *testing.T) {
 			t.Fatalf("unexpected error: %v", err)
 		}
 
-		if config.SafeJobs == nil {
-			t.Fatal("SafeJobs should not be nil")
+		if config.SafeOutputs == nil {
+			t.Fatal("SafeOutputs should not be nil")
+		}
+
+		if config.SafeOutputs.Jobs == nil {
+			t.Fatal("SafeOutputs.Jobs should not be nil")
 		}
 
-		customJob, ok := config.SafeJobs["custom-job"]
+		customJob, ok := config.SafeOutputs.Jobs["custom-job"]
 		if !ok {
-			t.Fatal("custom-job should exist")
+			t.Fatal("custom-job should exist in SafeOutputs.Jobs")
 		}
 
 		if customJob == nil {

skills/developer/SKILL.md

@@ -1091,7 +1091,6 @@ All three JSON schema files enforce strict validation with `"additionalPropertie
 | File | Purpose |
 |------|---------|
 | `pkg/parser/schemas/main_workflow_schema.json` | Validates agentic workflow frontmatter in `.github/workflows/*.md` files |
-| `pkg/parser/schemas/included_file_schema.json` | Validates imported/included workflow files |
 | `pkg/parser/schemas/mcp_config_schema.json` | Validates MCP (Model Context Protocol) server configuration |
 
 ### How It Works

specs/schema-validation.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-All three JSON schema files in this repository enforce strict validation by having `"additionalProperties": false` at the root level, which prevents typos and undefined fields from silently passing validation.
+Both JSON schema files in this repository enforce strict validation by having `"additionalProperties": false` at the root level, which prevents typos and undefined fields from silently passing validation.
 
 ## Schema Files
 
@@ -11,12 +11,7 @@ All three JSON schema files in this repository enforce strict validation by havi
 - **Root property**: `"additionalProperties": false` (line 3002)
 - **Purpose**: Validates agentic workflow frontmatter in `.github/workflows/*.md` files
 
-### 2. Included File Schema
-- **File**: `pkg/parser/schemas/included_file_schema.json`
-- **Root property**: `"additionalProperties": false` (line 426)
-- **Purpose**: Validates imported/included workflow files
-
-### 3. MCP Config Schema
+### 2. MCP Config Schema
 - **File**: `pkg/parser/schemas/mcp_config_schema.json`
 - **Root property**: `"additionalProperties": false` (line 99)
 - **Purpose**: Validates MCP (Model Context Protocol) server configuration
@@ -37,11 +32,10 @@ When `"additionalProperties": false` is set at the root level of a JSON schema,
 
 Comprehensive test coverage is provided in:
 - **File**: `pkg/parser/schema_additional_properties_test.go`
-- **Test cases**: 16 total
-  - 8 tests for common typos in main workflow schema
-  - 3 tests for typos in included file schema
-  - 3 tests for typos in MCP config schema
-  - 2 tests to verify valid properties are still accepted
+- **Test cases**: Tests for common typos and validation
+  - Tests for common typos in main workflow schema
+  - Tests for typos in MCP config schema
+  - Tests to verify valid properties are still accepted
 
 Run tests with:
 ```bash
@@ -88,9 +82,6 @@ The schemas are embedded in the Go binary using `//go:embed` directives in `pkg/
 //go:embed schemas/main_workflow_schema.json
 var mainWorkflowSchema string
 
-//go:embed schemas/included_file_schema.json
-var includedFileSchema string
-
 //go:embed schemas/mcp_config_schema.json
 var mcpConfigSchema string
 ```text