feat(review): inline reference files into review instructions + wire DeepSchema refs through

[nhorton]

Problem

DeepSchema-generated reviews only pointed reviewers at their examples, references, and json_schema_path by path. Running just the job_yml DeepSchema Compliance review for a single job.yml forced the reviewer to Read job.schema.json, several templates, and doc/job_yml_guidance.md at runtime — the main source of tool-call overhead.

Approach

Make reference-file inlining a generic feature of the review pipeline rather than a DeepSchema-only fix.

• ReviewRule and ReviewTask now carry reference_files: list[ReferenceFile].
• .deepreview rules get an optional review.reference_files field (schema + parser).
• build_instruction_file emits a new ## Reference Materials section with fenced contents, honoring MAX_INLINE_FILES = 20 and MAX_INLINE_TOTAL_BYTES = 256 * 1024, with graceful markers for missing files.
• The matcher propagates reference_files from rules to tasks across all strategies.
• The DeepSchema bridge populates reference_files from examples, references, and json_schema_path, resolved relative to the schema file's directory. URL-style entries are skipped. Missing files surface via the existing errors channel from generate_review_rules.

Also fixes a pre-existing broken relative path in src/deepwork/standard_schemas/job_yml/deepschema.yml that the new error-surfacing flagged.

Before / After

Generated instruction file for job_yml DeepSchema Compliance on src/deepwork/standard_jobs/deepwork_jobs/job.yml:

• Before: ## Review Instructions (summary + requirements) + ## Files to Review. Reviewer had to Read job.schema.json, templates/job.yml.example, templates/job.yml.template, templates/step_instruction.md.template, research_report_job_best_practices.md, and doc/job_yml_guidance.md.
• After: Same plus a new ## Reference Materials section containing all of those files inlined. Reviewer makes zero extra Read calls for the schema's referenced material.

Verification

• uv run pytest — 1263 passed, 1 skipped, 1 xfailed.
• uv run ruff check src tests — clean.
• uv run mypy src/deepwork/review/instructions.py src/deepwork/review/config.py src/deepwork/deepschema/review_bridge.py — clean.
• End-to-end: re-generated the job_yml DeepSchema Compliance instruction file and confirmed the new section contains the six reference files.

New tests cover: inlining with description + fenced blocks, count cap, byte cap, missing file, empty list, .deepreview parsing, and DeepSchema bridge population + error surfacing.

Files

• src/deepwork/review/config.py — new ReferenceFile; field on ReviewRule/ReviewTask; .deepreview parser.
• src/deepwork/review/instructions.py — caps, _build_reference_files_section, wired into build_instruction_file.
• src/deepwork/review/matcher.py — propagate reference_files to ReviewTask.
• src/deepwork/schemas/deepreview_schema.json — optional reference_files field.
• src/deepwork/deepschema/review_bridge.py — _collect_reference_files helper.
• src/deepwork/standard_schemas/job_yml/deepschema.yml — fix broken ../../../doc/... path.
• tests/unit/review/test_instructions.py, tests/unit/review/test_config.py, tests/unit/deepschema/test_review_bridge.py — new tests.

🤖 Generated with Claude Code