fix: handle YAML files in quality gate json_schema validation (#338)

* fix: handle YAML files in quality gate json_schema validation

validate_json_schemas() used json.loads() unconditionally, failing on
.yml/.yaml files. Now checks file extension and uses yaml.safe_load()
for YAML files, matching the approach already used in deepschema_write.py.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: handle YAML files in quality gate json_schema validation

- Update JOBS-REQ-004.2.2 spec to cover YAML parsing based on file extension
- Update JOBS-REQ-004.2.3 spec wording (JSON parsing -> file parsing)
- Add traceability comments to new YAML tests
- Fix incorrect traceability ref: JOBS-REQ-001.4.8 -> JOBS-REQ-004.2.6
- Update doc/job_yml_guidance.md to reflect YAML support
- Add changelog entry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: use yaml.safe_load unconditionally since YAML is a JSON superset

Simplifies the implementation — no need to branch on file extension.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update changelog entry to reflect unconditional yaml.safe_load approach

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: move yaml import to top-level and narrow exception handling

- Move `import yaml` from loop body to module-level (PyYAML is a runtime dep)
- Narrow `except Exception` to `(yaml.YAMLError, UnicodeDecodeError)`
- Fix doc wording: remove stale "based on file extension" references
- Fix extra blank line flagged by ruff

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: restore required blank line before top-level comment block

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nhorton

CHANGELOG.md

@@ -26,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Quality gate `validate_json_schemas()` now uses `yaml.safe_load` (a JSON superset) instead of `json.loads`, so YAML output files are validated correctly
+
 ### Removed
 ## [0.12.0] - 2026-04-03
 

doc/job_yml_guidance.md

@@ -64,7 +64,7 @@ You define quality criteria once, and they apply everywhere. If three workflows
 
 ### `json_schema`
 
-Only applies to `file_path` arguments. When set, the framework parses each output file as JSON and validates it against the schema **before any reviews run**. If validation fails, `finished_step` returns the error immediately -- reviews are skipped entirely. This is a hard gate, not a soft review. Use for structured outputs where format correctness is non-negotiable.
+Only applies to `file_path` arguments. When set, the framework parses each output file (JSON or YAML -- both are supported since YAML is a JSON superset) and validates it against the schema **before any reviews run**. If validation fails, `finished_step` returns the error immediately -- reviews are skipped entirely. This is a hard gate, not a soft review. Use for structured outputs where format correctness is non-negotiable.
 
 ---
 
@@ -152,7 +152,7 @@ A map of step_argument names to output configuration. When the agent calls `fini
 
 1. **Completeness**: All required outputs must be present. No unknown output names allowed.
 2. **Type validation**: `file_path` values must point to existing files. `string` values must be strings.
-3. **JSON schema**: If the step_argument has `json_schema`, file contents are parsed and validated. Failures are returned immediately; reviews are skipped.
+3. **JSON schema**: If the step_argument has `json_schema`, file contents are parsed (JSON or YAML) and validated. Failures are returned immediately; reviews are skipped.
 4. **Quality reviews**: Dynamic reviews from the output ref and step_argument, plus .deepreview rules.
 
 **Important**: The agent must provide ALL required outputs on every `finished_step` call, even outputs whose files have not changed since a previous attempt. The framework re-validates everything each time.

specs/deepwork/jobs/JOBS-REQ-004-quality-review-system.md

@@ -15,8 +15,8 @@ The quality review system evaluates step outputs against defined quality criteri
 ### JOBS-REQ-004.2: JSON Schema Validation
 
 1. `validate_json_schemas()` MUST check all `file_path` type outputs that have a `json_schema` defined on their `StepArgument`.
-2. For each such output, the file content MUST be parsed as JSON and validated against the schema.
-3. If JSON parsing fails, the error MUST be included in the returned error list.
+2. For each such output, the file content MUST be parsed as YAML (which is a superset of JSON) and validated against the schema.
+3. If file parsing fails, the error MUST be included in the returned error list.
 4. If schema validation fails, the error MUST be included in the returned error list.
 5. Files that do not exist MUST be skipped (not treated as errors by this function).
 6. `run_quality_gate()` MUST run JSON schema validation before building review rules. If schema errors exist, it MUST return an error message listing them without proceeding to reviews.

src/deepwork/jobs/mcp/quality_gate.py

@@ -7,10 +7,11 @@
 
 from __future__ import annotations
 
-import json
 import logging
 from pathlib import Path
 
+import yaml
+
 from deepwork.deepschema.review_bridge import generate_review_rules as gen_schema_rules
 from deepwork.jobs.mcp.schemas import ArgumentValue
 from deepwork.jobs.parser import (
@@ -60,9 +61,9 @@ def validate_json_schemas(
                 continue
             try:
                 content = full_path.read_text(encoding="utf-8")
-                parsed = json.loads(content)
-            except (json.JSONDecodeError, UnicodeDecodeError) as e:
-                errors.append(f"Output '{output_name}' file '{path}': failed to parse as JSON: {e}")
+                parsed = yaml.safe_load(content)
+            except (yaml.YAMLError, UnicodeDecodeError) as e:
+                errors.append(f"Output '{output_name}' file '{path}': failed to parse: {e}")
                 continue
 
             try:

tests/unit/jobs/mcp/test_quality_gate.py

@@ -92,22 +92,22 @@ def test_passes_when_json_schema_validates(self, tmp_path: Path) -> None:
 
     # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-004.2.3).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
-    def test_fails_when_json_is_invalid(self, tmp_path: Path) -> None:
-        """Non-JSON content in the output file produces an error."""
+    def test_fails_when_file_is_unparseable(self, tmp_path: Path) -> None:
+        """Unparseable content in the output file produces an error."""
         schema = {"type": "object"}
         arg = StepArgument(
-            name="data", description="JSON data", type="file_path", json_schema=schema
+            name="data", description="data file", type="file_path", json_schema=schema
         )
         output_ref = StepOutputRef(argument_name="data", required=True)
         step = WorkflowStep(name="generate", outputs={"data": output_ref})
         job, _ = _make_job(tmp_path, [arg], step)
 
-        data_file = tmp_path / "data.json"
-        data_file.write_text("not json {{{")
+        data_file = tmp_path / "data.yml"
+        data_file.write_text(":\n  bad: [yaml\n  unclosed")
 
-        errors = validate_json_schemas({"data": "data.json"}, step, job, tmp_path)
+        errors = validate_json_schemas({"data": "data.yml"}, step, job, tmp_path)
         assert len(errors) == 1
-        assert "failed to parse as JSON" in errors[0]
+        assert "failed to parse" in errors[0]
 
     # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-004.2.4).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
@@ -147,6 +147,51 @@ def test_skips_string_type_arguments(self, tmp_path: Path) -> None:
         errors = validate_json_schemas({"data": "just a string value"}, step, job, tmp_path)
         assert errors == []
 
+    # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-004.2.2).
+    # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
+    def test_passes_when_yaml_file_matches_schema(self, tmp_path: Path) -> None:
+        """YAML files should be parsed with yaml.safe_load, not json.loads."""
+        schema = {
+            "type": "object",
+            "properties": {"title": {"type": "string"}},
+            "required": ["title"],
+        }
+        arg = StepArgument(
+            name="data", description="YAML data", type="file_path", json_schema=schema
+        )
+        output_ref = StepOutputRef(argument_name="data", required=True)
+        step = WorkflowStep(name="generate", outputs={"data": output_ref})
+        job, _ = _make_job(tmp_path, [arg], step)
+
+        data_file = tmp_path / "data.yml"
+        data_file.write_text("title: Hello\n")
+
+        errors = validate_json_schemas({"data": "data.yml"}, step, job, tmp_path)
+        assert errors == []
+
+    # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-004.2.4).
+    # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
+    def test_fails_when_yaml_file_violates_schema(self, tmp_path: Path) -> None:
+        """YAML files that don't match the schema produce errors."""
+        schema = {
+            "type": "object",
+            "properties": {"count": {"type": "integer"}},
+            "required": ["count"],
+        }
+        arg = StepArgument(
+            name="data", description="YAML data", type="file_path", json_schema=schema
+        )
+        output_ref = StepOutputRef(argument_name="data", required=True)
+        step = WorkflowStep(name="generate", outputs={"data": output_ref})
+        job, _ = _make_job(tmp_path, [arg], step)
+
+        data_file = tmp_path / "data.yaml"
+        data_file.write_text("count: not_an_integer\n")
+
+        errors = validate_json_schemas({"data": "data.yaml"}, step, job, tmp_path)
+        assert len(errors) == 1
+        assert "schema validation failed" in errors[0]
+
 
 # ---------------------------------------------------------------------------
 # TestBuildDynamicReviewRules
@@ -440,7 +485,7 @@ def test_returns_none_when_no_review_blocks_defined(self, tmp_path: Path) -> Non
 
         assert result is None
 
-    # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-001.4.8).
+    # THIS TEST VALIDATES A HARD REQUIREMENT (JOBS-REQ-004.2.6).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
     def test_returns_feedback_when_json_schema_fails(self, tmp_path: Path) -> None:
         """Schema validation failure returns an error string without running reviews."""