feat: add requirements_file standard schema, specs, and review improvements

- Add built-in requirements_file deepschema for RFC 2119 spec files
- Add JOBS-REQ-012 spec for learn workflow prevention automation
- Add DW-REQ-011.10 requirement quality constraints for deepschemas
- Add anonymous deepschemas validating JOBS-REQ-012 and DW-REQ-011.10
- Improve requirements_traceability review to prefer anonymous deepschemas
  for single-file requirements over tests
- Fix multi-keyword requirements in DW-REQ-011 (011.6.3, 011.7.3, 011.8.7)
- Fix REVIEW-REQ-005.7 sequential ordering
- Fix job_schema_instruction_compatibility description accuracy

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

Author: nhorton

.deepreview

@@ -131,13 +131,33 @@ requirements_traceability:
       false confidence (a passing test that doesn't actually verify anything)
       or wastes reviewer judgment on something a machine can check exactly.
 
+      **Use anonymous DeepSchemas** (`.deepschema.<filename>.yml`) when
+      requirements target a specific file — whether structural or semantic:
+      - "This config file MUST include a timeout field" — structural check
+        for one file (use `json_schema_path` or `verification_bash_command`
+        for exact verification)
+      - "The learn workflow MUST accept X and Y step arguments" — the
+        requirement governs a specific YAML file's content
+      - "Skill MUST instruct the agent to do X" — judgment-based check
+        of prose in one specific file
+      - "The error message MUST include a suggestion for how to fix the
+        problem" — governs a specific source file's behavior
+
+      Anonymous DeepSchemas provide both write-time validation and review-time
+      checks, and they keep the requirement co-located with the file it governs.
+      **Prefer them over both tests and `.deepreview` rules whenever the
+      requirement targets a specific file** rather than a class of files.
+      DeepSchemas can enforce structural requirements via `json_schema_path`
+      or `verification_bash_command` just as precisely as a test, while also
+      supporting judgment-based requirements in the same schema.
+
       **Use automated tests** (`tests/`) when the requirement specifies a
-      concrete, machine-verifiable fact:
-      - File exists at a specific path
-      - JSON/YAML field has a specific value
-      - Config contains a specific identifier (e.g., `mcp__deepwork__get_review_instructions`)
+      concrete, machine-verifiable fact that spans multiple files or is not
+      tied to a single file's content:
       - File A is byte-identical to file B
-      - A data structure has a required shape
+      - A Python function returns the correct value for given inputs
+      - A CLI command produces expected output
+      - A data structure assembled from multiple sources has a required shape
 
       Tests reference requirement IDs via docstrings and traceability comments.
 
@@ -150,21 +170,6 @@ requirements_traceability:
       - "Documentation MUST stay in sync with code" — are the descriptions
         still accurate after changes?
 
-      **Use anonymous DeepSchemas** (`.deepschema.<filename>.yml`) when the
-      requirement is specific to a single file's behavior or content:
-      - "The error message in situation X MUST include a suggestion for how
-        to fix the problem" — place the requirement in a `.deepschema` for
-        the file that implements that functionality
-      - "This config file MUST include a timeout field" — a structural
-        requirement for one specific file
-      - "Skill MUST instruct the agent to do X" — does the prose in this
-        specific skill file convey X clearly enough?
-
-      Anonymous DeepSchemas provide both write-time validation and review-time
-      checks, and they keep the requirement co-located with the file it governs.
-      Prefer them over `.deepreview` rules whenever the requirement targets a
-      specific file rather than a class of files.
-
       Both `.deepreview` rules and DeepSchemas reference requirement IDs in
       their `description`, `instructions`, or `requirements` fields.
 
@@ -456,7 +461,7 @@ deepreview_config_quality:
         and a specific recommendation.
 
 job_schema_instruction_compatibility:
-  description: "Verify deepwork_jobs job.yml inline instructions are compatible with the job schema."
+  description: "Verify all standard and library job.yml definitions and templates are compatible with the job schema."
   match:
     include:
       - "src/deepwork/jobs/job.schema.json"

.deepwork/schemas/claude_settings/claude_settings.schema.json

@@ -10,8 +10,8 @@
       "examples": [
         "Bash",
         "Bash(npm run build)",
-        "Bash(git commit *)",
-        "Bash(npm run *)",
+        "Bash(git commit:*)",
+        "Bash(npm run:*)",
         "Bash(ls*)",
         "Bash(git * main)",
         "Edit",
@@ -24,7 +24,8 @@
         "WebFetch",
         "WebFetch(domain:example.com)",
         "mcp__puppeteer",
-        "mcp__github__search_repositories"
+        "mcp__github__search_repositories",
+        "mcp__github__*"
       ]
     },
     "hookCommand": {
@@ -1798,4 +1799,4 @@
     }
   },
   "title": "Claude Code Settings"
-}
+}

specs/deepwork/DW-REQ-011-deepschema.md

@@ -1,5 +1,7 @@
 # DW-REQ-011: DeepSchema System
 
+## Overview
+
 The DeepSchema system provides rich, file-level schemas with automatic validation on writes and synthetic review rule generation.
 
 ## DW-REQ-011.1: Schema Types
@@ -42,13 +44,13 @@ The DeepSchema system provides rich, file-level schemas with automatic validatio
 
 1. A file MUST match a named schema if any of the schema's `matchers` glob patterns match the file's project-relative path.
 2. A file MUST match an anonymous schema if a `.deepschema.<filename>.yml` file exists alongside it.
-3. The `get_schemas_for_file_fast()` function MUST avoid full tree walks — it MUST only scan named schema folders and check for the anonymous schema file at O(1).
+3. The `get_schemas_for_file_fast()` function MUST avoid full tree walks by only scanning named schema folders and checking for the anonymous schema file at O(1).
 
 ## DW-REQ-011.7: Write Hook (PostToolUse)
 
 1. The write hook MUST fire on PostToolUse events for Write and Edit tools.
 2. For each applicable schema, the hook MUST inject a conformance note: "Note: this file must conform to the DeepSchema at `<path>`".
-3. If `json_schema_path` is set, the hook MUST validate the written file against the JSON Schema. YAML files (`.yml`/`.yaml`) MUST be parsed as YAML before validation.
+3. If `json_schema_path` is set, the hook MUST validate the written file against the JSON Schema, parsing YAML files (`.yml`/`.yaml`) as YAML before validation.
 4. If `verification_bash_command` is set, the hook MUST execute each command with the file path as `$1`, with a 30-second timeout.
 5. Validation failures MUST be reported via `hookSpecificOutput.additionalContext` so the agent can act on them.
 6. The hook MUST NOT use `systemMessage` for validation output — that route is user-visible only.
@@ -61,10 +63,17 @@ The DeepSchema system provides rich, file-level schemas with automatic validatio
 4. Anonymous schema reviews MUST include only the requirements.
 5. All generated reviews MUST use the `"individual"` strategy (one file at a time).
 6. Generated reviews MUST be included in both `/review` runs and workflow quality gate checks.
-7. Review instructions MUST specify RFC 2119 severity logic: reviewers MUST fail any violation of a MUST requirement, MUST fail any SHOULD requirement that could easily be followed but is not, SHOULD give feedback without failing on other applicable items, and MUST ignore requirements that are not applicable.
+7. Review instructions MUST specify RFC 2119 severity logic: fail any violation of a MUST requirement, fail any SHOULD requirement that could easily be followed but is not, give feedback without failing on other applicable items, and ignore requirements that are not applicable.
 
 ## DW-REQ-011.9: MCP Tool — get_named_schemas
 
 1. The `get_named_schemas` MCP tool MUST return all discovered named schemas.
 2. Each entry MUST include `name`, `summary`, and `matchers` fields.
 3. Schemas that fail to parse MUST still appear in the results with an error summary instead of a real summary.
+
+## DW-REQ-011.10: Requirement Quality Constraints
+
+1. Each requirement in the `requirements` field MUST be verifiable by examining files on the filesystem.
+2. Requirements about processes, user behavior, or context not present in files SHOULD be placed in the `instructions` section instead.
+3. Requirements MUST NOT restate constraints that are already enforced by the schema's `json_schema_path` or `verification_bash_command`, including syntactic validity (e.g., "must be valid JSON"), field types, allowed enum values, required fields, and structural shape.
+4. Requirements SHOULD focus on semantic rules, behavioral gotchas, and cross-field concerns that JSON Schema cannot express.

specs/deepwork/jobs/JOBS-REQ-012-learn-workflow.md

@@ -0,0 +1,30 @@
+# JOBS-REQ-012: Learn Workflow
+
+## Overview
+
+The `learn` workflow in the `deepwork_jobs` standard job analyzes conversation history to extract learnings from DeepWork job executions. It improves job instructions with generalizable insights, captures run-specific learnings in AGENTS.md files, and creates preventive automation (DeepSchemas and DeepReview rules) to prevent recurring issues.
+
+## Requirements
+
+### JOBS-REQ-012.1: Learning Classification
+
+1. The learn workflow MUST classify each identified learning as either **generalizable** (applicable to future runs of the same job) or **bespoke** (specific to the current run/context).
+2. Generalizable learnings MUST be applied to job instruction files.
+3. Bespoke learnings MUST be captured in an AGENTS.md file in the deepest common folder that would contain all future work on the topic.
+
+### JOBS-REQ-012.2: Prevention Opportunity Evaluation
+
+1. The learn workflow MUST evaluate whether DeepSchemas or DeepReview rules could prevent issues encountered during the session.
+2. If prevention opportunities exist, the workflow SHOULD create the corresponding DeepSchemas or DeepReview rules.
+3. If no prevention opportunities are found, the workflow MUST state why none were identified.
+
+### JOBS-REQ-012.3: Step Arguments
+
+1. The learn workflow MUST accept a `deepschemas` step argument for outputting created DeepSchema files.
+2. The learn workflow MUST accept a `deepreviews` step argument for outputting created DeepReview rule files.
+
+### JOBS-REQ-012.4: Process Requirements
+
+1. The workflow MUST enforce that generalizable learnings are applied to job instructions ("Generalizable Learnings Applied").
+2. The workflow MUST enforce that bespoke learnings are captured in AGENTS.md ("Bespoke Learnings Captured").
+3. The workflow MUST enforce that prevention opportunities are evaluated ("Prevention Opportunities Evaluated").

specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md

@@ -16,13 +16,6 @@ For each `ReviewTask`, the system generates a self-contained markdown instructio
 6. When the task has `additional_files` (unchanged matching files), the file MUST contain an "Unchanged Matching Files" section listing those file paths.
 7. When the task has `all_changed_filenames`, the file MUST contain an "All Changed Files" section listing every changed filename for context.
 
-### REVIEW-REQ-005.7: Git Diff Section
-
-1. When a `ReviewTask` has a non-null `git_diff_output`, the instruction file MUST contain a section headed `## Output from \`git diff main..HEAD\` for you to review (sorted by filepath)`.
-2. The diff output MUST be rendered inside a fenced code block with the `diff` language tag.
-3. This section MUST appear after the "Files to Review" section and before the "All Changed Files" section.
-4. When `git_diff_output` is `None`, this section MUST be omitted.
-
 ### REVIEW-REQ-005.2: File Path Formatting
 
 1. File paths in the "Files to Review" section MUST be prefixed with `@` to trigger Claude Code's file-reading behavior (e.g., `@src/app.py`).
@@ -54,3 +47,10 @@ For each `ReviewTask`, the system generates a self-contained markdown instructio
 2. The traceability line MUST be formatted as: `This review was requested by the policy at \`{source_location}\`.` where `source_location` is the relative file path and line number (e.g., `src/.deepreview:5`).
 3. The traceability line MUST be preceded by a markdown horizontal rule (`---`).
 4. When `source_location` is empty, the traceability section MUST be omitted.
+
+### REVIEW-REQ-005.7: Git Diff Section
+
+1. When a `ReviewTask` has a non-null `git_diff_output`, the instruction file MUST contain a section headed `## Output from \`git diff main..HEAD\` for you to review (sorted by filepath)`.
+2. The diff output MUST be rendered inside a fenced code block with the `diff` language tag.
+3. This section MUST appear after the "Files to Review" section and before the "All Changed Files" section.
+4. When `git_diff_output` is `None`, this section MUST be omitted.

src/deepwork/standard_jobs/deepwork_jobs/.deepschema.job.yml.yml

@@ -0,0 +1,21 @@
+requirements:
+  learn-workflow-step-arguments: >
+    The learn workflow MUST accept `deepschemas` and `deepreviews` step
+    arguments for outputting created DeepSchema and DeepReview rule files.
+    (JOBS-REQ-012.3)
+
+  learn-workflow-classification: >
+    The learn workflow's step instructions MUST describe how to classify
+    each learning as either generalizable (applied to job instructions) or
+    bespoke (captured in AGENTS.md). (JOBS-REQ-012.1)
+
+  learn-workflow-prevention-evaluation: >
+    The learn workflow MUST include instructions for evaluating whether
+    DeepSchemas or DeepReview rules could prevent issues encountered during
+    the session, and MUST require the agent to state why if none are found.
+    (JOBS-REQ-012.2)
+
+  learn-workflow-process-requirements: >
+    The learn workflow's quality review MUST enforce "Generalizable Learnings
+    Applied", "Bespoke Learnings Captured", and "Prevention Opportunities
+    Evaluated" as process requirements. (JOBS-REQ-012.4)

src/deepwork/standard_schemas/deepschema/.deepschema.deepschema.yml.yml

@@ -0,0 +1,10 @@
+requirements:
+  requirements-filesystem-verifiable-present: >
+    The deepschema standard schema MUST include a requirement enforcing that
+    DeepSchema requirements are verifiable by examining files on the
+    filesystem. (DW-REQ-011.10.1)
+
+  no-structural-requirements-present: >
+    The deepschema standard schema MUST include a requirement enforcing that
+    DeepSchema requirements do not restate constraints already enforced by
+    json_schema_path or verification_bash_command. (DW-REQ-011.10.3)

src/deepwork/standard_schemas/requirements_file/deepschema.yml

@@ -0,0 +1,78 @@
+summary: "RFC 2119 requirements specification files."
+
+instructions: |
+  Requirements files define formal specifications using RFC 2119 keywords.
+  They follow the naming convention `REQ-NNN-<topic>.md` where NNN is a
+  zero-padded number.
+
+  Each file has:
+  - A `# REQ-NNN: Title` top-level heading matching the filename prefix.
+  - An `## Overview` section describing the subsystem.
+  - A `## Requirements` section containing one or more `### REQ-NNN.M: Title`
+    subsections, each with a numbered list of requirements.
+
+  Every requirement statement must be specific enough to be verifiable by either
+  an automated test or a DeepReview rule. Vague requirements like "SHOULD be fast"
+  or "MUST be user-friendly" are not acceptable — they must include a concrete,
+  evaluable criterion.
+
+  When adding new requirements:
+  - Assign the next sequential section number (REQ-NNN.M where M is next unused).
+  - Number requirements sequentially within each section (1, 2, 3...).
+  - Each requirement gets exactly one RFC 2119 keyword (MUST, SHOULD, MAY, etc.).
+
+  Requirement ID stability:
+  - Never change or reassign an existing requirement's number.
+  - New requirements always go at the end of their section.
+  - If a requirement is removed, keep its number and replace the body with
+    "REQUIREMENT REMOVED" so external references (tests, review rules) remain valid.
+
+matchers:
+  - "**/*REQ-*.md"
+
+requirements:
+  rfc-2119-keyword: >
+    Every numbered requirement statement MUST contain exactly one RFC 2119
+    keyword (MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED,
+    MAY, OPTIONAL, REQUIRED). A requirement without a keyword is ambiguous and
+    MUST be flagged.
+
+  unique-section-ids: >
+    Each `### REQ-NNN.M:` section heading MUST have a unique ID within the
+    file. The NNN portion MUST match the filename's prefix (e.g., sections in
+    `REQ-001-application-shell.md` MUST all use `REQ-001.X`).
+
+  sequential-numbering: >
+    Requirements within each section MUST be sequentially numbered starting
+    from 1, with no gaps or duplicates. Section sub-IDs (the .M part) MUST
+    also be sequential within the file.
+
+  testability: >
+    Each requirement MUST be specific enough to be verifiable — either by an
+    automated test (for concrete, machine-checkable facts) or by a DeepReview
+    rule (for judgment-based, cross-file concerns). Requirements that cannot
+    be objectively evaluated MUST be rewritten with concrete criteria.
+
+  overview-section: >
+    Requirements files MUST begin with a top-level heading matching the
+    filename prefix, followed by an `## Overview` section that describes the
+    subsystem's purpose and scope.
+
+  no-orphan-requirements: >
+    Every MUST or SHALL requirement MUST have a corresponding test, DeepSchema
+    requirement, or DeepReview rule that validates it. Requirements without any
+    validation mechanism SHOULD be flagged during review.
+
+  requirement-id-stability: >
+    Existing requirement numbers MUST NOT be changed or reassigned. New
+    requirements MUST be appended to the end of their section with the next
+    sequential number. If a requirement is fully removed, its number MUST
+    remain in place with the body replaced by "REQUIREMENT REMOVED" so that
+    all other IDs remain stable and external references do not break.
+
+verification_bash_command:
+  - "grep -nE '^[0-9]+\\.' \"$1\" | grep -vE 'MUST|SHALL|SHOULD|MAY|REQUIRED|RECOMMENDED|OPTIONAL' | { if read -r line; then echo \"FAIL: Requirement without RFC 2119 keyword: $line\"; exit 1; fi; }"
+
+references:
+  - path: "https://www.ietf.org/rfc/rfc2119.txt"
+    description: "RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels."