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>

Author: nhorton

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 (JSON or YAML based on file extension) 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 (JSON or YAML based on extension) 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.

src/deepwork/jobs/mcp/quality_gate.py

@@ -10,6 +10,8 @@
 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 (
@@ -58,11 +60,9 @@ def validate_json_schemas(
             if not full_path.exists():
                 continue
             try:
-                import yaml
-
                 content = full_path.read_text(encoding="utf-8")
                 parsed = yaml.safe_load(content)
-            except Exception as e:
+            except (yaml.YAMLError, UnicodeDecodeError) as e:
                 errors.append(f"Output '{output_name}' file '{path}': failed to parse: {e}")
                 continue
 

tests/unit/jobs/mcp/test_quality_gate.py

@@ -192,8 +192,6 @@ def test_fails_when_yaml_file_violates_schema(self, tmp_path: Path) -> None:
         assert len(errors) == 1
         assert "schema validation failed" in errors[0]
 
-
-
 # ---------------------------------------------------------------------------
 # TestBuildDynamicReviewRules
 # ---------------------------------------------------------------------------