feat: teach learn workflow to create deepschemas and deepreview rules (#327)

* feat: inject sorted git diff into broad review rule prompts

Rules with strategy all_changed_files or matches_together and a **/*
matcher now get git diff main..HEAD pre-fetched and injected into the
review instruction file. The diff is sorted by filepath to group files
by directory, reducing reviewer turn count. Diff is scoped to the
rule's source_dir so subdirectory .deepreview files get narrower diffs.

Also streamlines the /review skill to skip the get_configured_reviews
call and go straight to get_review_instructions.

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

* feat: teach learn workflow to create deepschemas and deepreview rules

The learn workflow now evaluates whether deepschemas or deepreview rules
could prevent issues encountered during a session, covering both process
mistakes and the substance of the work. Adds a "Preventable" classification,
a new Step 7 with actionable instructions for creating anonymous/named
deepschemas and deepreview rules, and a process requirement ensuring
prevention opportunities are always evaluated.

Also adds a filesystem-verifiable requirement to the deepschema meta-schema,
ensuring all deepschema requirements can be checked from filesystem assets.

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

* feat: add claude_settings deepschema and enforce JSON-schema-first requirements

- Add .deepwork/schemas/claude_settings/ with deepschema.yml (semantic
  requirements) and vendored SchemaStore JSON Schema for structural validation
- Add no-structural-requirements rule to deepschema standard schema: requirements
  must not restate what json_schema_path already enforces
- Update /deepschema skill with JSON Schema First guidance: maximize structural
  validation, check SchemaStore for existing schemas, vendor local copies

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

* docs: update architecture.md to reflect learn workflow's preventive automation

The learn workflow now evaluates prevention opportunities and creates
DeepSchemas and DeepReview rules. Updated three sections in architecture.md
to document this capability.

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

* refactor: move knowledge-based deepschema requirements to instructions

Requirements about author understanding (sandbox path semantics, automode
defaults replacement, attribution deprecation, sandbox write paths) are not
filesystem-verifiable. Moved them to the instructions section and kept only
requirements that can be checked by examining file contents.

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

* style: fix ruff formatting in review/instructions.py

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

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

@@ -0,0 +1,79 @@
+summary: "Claude Code settings.json and settings.local.json configuration files."
+
+instructions: |
+  Claude Code settings files control permissions, hooks, sandbox, model preferences,
+  and plugin configuration. There are three scopes with distinct purposes:
+
+  - `.claude/settings.json` — shared project settings, committed to git. Team-wide
+    permissions, hooks, and MCP server approvals.
+  - `.claude/settings.local.json` — personal per-project overrides, gitignored.
+    Sensitive credentials, personal MCP configs, local permission tweaks.
+  - `~/.claude/settings.json` — user-global defaults for all projects.
+
+  Precedence (highest to lowest): managed → CLI args → settings.local.json →
+  settings.json → ~/.claude/settings.json → defaults. Deny rules at ANY level
+  cannot be overridden by allow rules at any other level.
+
+  Key sections: permissions (allow/ask/deny tool rules), hooks (lifecycle event
+  handlers), sandbox (OS-level isolation), env (environment variables), and
+  various global config fields (model, attribution, autoMode, etc.).
+
+  Gotchas to keep in mind when editing these files:
+
+  - Sandbox path settings use DIFFERENT prefix semantics than permission rules:
+    `/path` means absolute (not project-relative), `~/` means home, `./` or
+    bare path means project root. Do not confuse these with Read/Edit path rules.
+  - When `autoMode.allow` or `autoMode.soft_deny` arrays are set, they completely
+    replace the built-in defaults rather than merging. Review defaults via
+    `claude auto-mode defaults` before overriding.
+  - When `sandbox.enabled` is true, `sandbox.filesystem.allowWrite` should include
+    the project directory and any tool output directories. An overly restrictive
+    sandbox without necessary write paths will cause tool failures.
+  - The `attribution` object supersedes the deprecated `includeCoAuthoredBy`
+    boolean. Prefer `attribution` for new configurations.
+
+matchers:
+  - ".claude/settings.json"
+  - ".claude/settings.local.json"
+  - "**/.claude/settings.json"
+  - "**/.claude/settings.local.json"
+
+json_schema_path: "claude_settings.schema.json"
+
+requirements:
+  bash-wildcard-word-boundaries: >
+    Bash permission patterns MUST use the `:*` style to enforce word
+    boundaries (e.g., `Bash(npm run:*)`) and only use regular * if it is
+    clearly a situation where the whitespace is not appropriate. Patterns
+    MUST be reviewed for unintended broad matching.
+
+  read-edit-path-prefixes: >
+    Read and Edit permission specifiers MUST use the correct path prefix
+    convention: `./**` or bare paths for project-relative, `~` for home
+    directory, `//` (double slash) for absolute filesystem paths. A single
+    leading `/` is project-relative, NOT absolute — this is a common mistake.
+
+  no-secrets-in-shared-settings: >
+    `.claude/settings.json` (the shared, committed file) MUST NOT contain
+    secrets, API keys, tokens, or credentials. Sensitive values MUST go in
+    `.claude/settings.local.json` (gitignored) or environment variables.
+
+  automode-not-in-shared-settings: >
+    `autoMode` configuration MUST NOT appear in `.claude/settings.json` (shared
+    project settings). Claude Code ignores autoMode from shared project settings
+    to prevent malicious repos from weakening security. Use user-level or
+    managed settings instead.
+
+  mcp-tools-pattern-valid: >
+    MCP tool permission patterns MUST follow the format
+    `mcp__<server_name>__<tool_name>` or use a wildcard `mcp__<server_name>__*`
+    for all tools from a server. The double-underscore separators are required.
+    MCP tool permissions MUST NOT use `:*`.
+
+references:
+  - path: "https://json.schemastore.org/claude-code-settings.json"
+    description: "Community-maintained JSON Schema on SchemaStore — the most comprehensive structural schema available. Consider syncing our local schema with this periodically."
+  - path: "https://docs.anthropic.com/en/docs/claude-code/settings"
+    description: "Official Claude Code settings documentation — complete field reference and precedence rules."
+  - path: "https://docs.anthropic.com/en/docs/claude-code/security"
+    description: "Claude Code security model — permissions, sandboxing, and managed settings."

.deepwork/schemas/claude_settings/deepschema.yml

@@ -483,7 +483,7 @@ DeepWork includes a built-in job called `deepwork_jobs` for managing jobs. It pr
 - **`repair`** workflow: `fix_settings` → `fix_jobs` → `errata`
   - Cleans up and migrates DeepWork configurations from prior versions
 - **`learn`** workflow: `learn`
-  - Analyzes conversation history to improve job instructions and capture learnings
+  - Analyzes conversation history to improve job instructions, capture learnings, and create preventive automation (DeepSchemas and DeepReview rules)
 
 These are auto-discovered at runtime by the MCP server from the Python package.
 
@@ -532,7 +532,7 @@ User: /deepwork new_job
 
 ### The `learn` Workflow
 
-Analyzes conversation history to improve job instructions and capture learnings:
+Analyzes conversation history to improve job instructions, capture learnings, and create preventive automation:
 
 ```
 User: /deepwork_jobs.learn
@@ -551,10 +551,14 @@ Claude: I'll analyze this conversation for DeepWork job executions...
         Bespoke learnings captured:
         ✓ Created AGENTS.md with project-specific notes about this competitive research instance
 
+        Prevention opportunities evaluated:
+        ✓ Created DeepSchema for competitor_profiles/ output format
+        ✓ Added DeepReview rule to enforce source prioritization in research steps
+
         Job instructions updated in place. Changes take effect on next workflow run.
 ```
 
-This standalone skill can be run anytime after executing a job to capture learnings and improve instructions.
+This standalone skill can be run anytime after executing a job to capture learnings, improve instructions, and create preventive automation (DeepSchemas and DeepReview rules).
 
 ### Step Instructions at Runtime
 
@@ -742,6 +746,7 @@ The `/deepwork_jobs.define` command:
 The `/deepwork_jobs.learn` command:
 1. Identifies doc spec-related learnings (quality criteria issues, structure changes)
 2. Updates doc spec files with improvements
+3. Evaluates prevention opportunities and creates DeepSchemas and DeepReview rules
 
 See `doc/doc-specs.md` for complete documentation.
 

doc/architecture.md

@@ -51,11 +51,11 @@ matchers:
   - "src/configs/**/*.json"
 
 requirements:
-  has-version: "Every config file MUST include a version field."
+  # Semantic rules only — structural constraints go in config.schema.json
   documented-fields: "All fields SHOULD have inline comments explaining their purpose."
   no-secrets: "Config files MUST NOT contain secrets or credentials."
 
-# Optional: structural validation
+# Structural validation — enforce types, required fields, enums, etc. here
 json_schema_path: "config.schema.json"
 
 # Optional: custom validation commands (file path passed as $1)
@@ -72,13 +72,53 @@ Place a `.deepschema.<filename>.yml` file next to the target file:
 ```yaml
 requirements:
   api-key-rotated: "The API key MUST be rotated every 90 days."
-  format-valid: "The file MUST be valid YAML."
+  no-plaintext-secrets: "Credentials MUST use environment variable references, not literal values."
 
 # Reference a named schema for shared requirements
 parent_deep_schemas:
   - api_endpoint
 ```
 
+## JSON Schema First: Maximize Structural Validation
+
+**The `json_schema_path` file is the primary enforcement mechanism.** Every constraint that _can_ be expressed structurally MUST go in the JSON Schema, not in requirements. Requirements exist only for semantic rules that JSON Schema cannot express.
+
+Put in the JSON Schema (not requirements):
+- File format validity (valid JSON, valid YAML)
+- Field types (string, number, boolean, array, object)
+- Required fields
+- Allowed property names (`additionalProperties: false`)
+- Enum values and allowed constants
+- Array item types and constraints (`minItems`, `uniqueItems`)
+- Numeric ranges (`minimum`, `maximum`)
+- String patterns (`pattern`, `format`)
+- Conditional field presence (`if`/`then` — e.g., "when type is 'http', url is required")
+- Nested object shapes and their constraints
+
+Put in requirements (not the JSON Schema):
+- Semantic rules about _meaning_ ("secrets MUST NOT appear in shared settings")
+- Cross-file concerns ("this field MUST reference an existing named schema")
+- Behavioral gotchas ("sandbox paths use different prefix semantics than permission paths")
+- Design guidance ("deny rules SHOULD be used for hard security boundaries, not soft preferences")
+- Anything requiring judgment or context a machine validator cannot assess
+
+**Build the JSON Schema to be as strict and comprehensive as possible.** Use `additionalProperties: false` to catch typos. Use enums for closed sets. Use `if/then` for conditional requirements. Use `pattern` for string formats. Use `$defs` and `$ref` for reusable types. Use `anyOf` for discriminated unions. Use `uniqueItems`, `minLength`, `minItems` where appropriate. A good JSON Schema catches errors at write time before a reviewer ever sees the file. Requirements that duplicate what the schema already enforces are noise — they dilute the reviewer's attention and risk contradicting the schema.
+
+### Check SchemaStore for Existing Schemas
+
+Before writing a JSON Schema from scratch, check whether a published schema already exists at [SchemaStore](https://www.schemastore.org/) (`https://json.schemastore.org/<name>.json`). SchemaStore hosts community-maintained schemas for hundreds of config file formats.
+
+If a good schema exists:
+1. **Vendor a local copy** into your schema directory (e.g., `claude_settings.schema.json`)
+2. **Add a `_source` field** at the top of the file with the original URL and sync date:
+   ```json
+   {
+     "_source": "Vendored from https://json.schemastore.org/example.json. To update: fetch the latest version from that URL and replace this file. Last synced: 2026-04-01."
+   }
+   ```
+3. **Point `json_schema_path`** at the local copy — this avoids network dependencies during validation
+4. **Periodically re-fetch** the upstream schema to pick up improvements — the `_source` field tells future maintainers where to look
+
 ## Schema Fields Reference
 
 | Field | Description |

plugins/claude/skills/deepschema/SKILL.md

@@ -19,7 +19,7 @@ After discovering review rules (REVIEW-REQ-002) and changed files (REVIEW-REQ-00
 ### REVIEW-REQ-004.2: Review Task Data Model
 
 1. Each review task MUST be represented as a `ReviewTask` dataclass.
-2. The `ReviewTask` MUST contain: `rule_name` (str), `files_to_review` (list[str] — paths relative to repo root), `instructions` (str), `agent_name` (str | None), `source_location` (str — formatted as `"path:line"`), `additional_files` (list[str] — unchanged matching files, relative to repo root), `all_changed_filenames` (list[str] | None).
+2. The `ReviewTask` MUST contain: `rule_name` (str), `files_to_review` (list[str] — paths relative to repo root), `instructions` (str), `agent_name` (str | None), `source_location` (str — formatted as `"path:line"`), `additional_files` (list[str] — unchanged matching files, relative to repo root), `all_changed_filenames` (list[str] | None), `git_diff_output` (str | None — pre-fetched diff for broad rules, see REVIEW-REQ-004.11).
 3. `files_to_review` MUST always contain at least one file path.
 4. `source_location` MUST be formatted as `"{relative_path}:{line_number}"` where the path is relative to the project root (e.g., `"src/.deepreview:5"`).
 
@@ -71,3 +71,12 @@ After discovering review rules (REVIEW-REQ-002) and changed files (REVIEW-REQ-00
 1. Rules with the same name defined in different `.deepreview` files MUST produce independent `ReviewTask` objects. The system MUST NOT merge or combine matched files across rules from different source directories.
 2. When two `.deepreview` files in different directories define a rule with the same name and the same strategy, and changed files match both rules, the system MUST create separate `ReviewTask` objects — one per directory — each containing only the files that matched within its own `source_dir`.
 3. This isolation is a consequence of REVIEW-REQ-004.1.2 (files outside `source_dir` do not match) but is stated explicitly because `.deepreview` files can be templated or symlinked across directories, making same-name rules a common scenario.
+
+### REVIEW-REQ-004.11: Git Diff Injection for Broad Rules
+
+1. When a rule has strategy `"all_changed_files"` or `"matches_together"` AND its `include` patterns contain `**/*`, the system MUST run `git diff <merge-base>..HEAD` and attach the output to the resulting `ReviewTask` as `git_diff_output`.
+2. The git diff MUST be computed at most once per unique `source_dir` per `match_files_to_rules` invocation, even if multiple rules with the same `source_dir` qualify for injection.
+3. If the git diff command fails or produces empty output, `git_diff_output` MUST be `None`.
+4. Rules with strategy `"individual"` MUST NOT receive `git_diff_output`, regardless of their include patterns.
+5. The `ReviewTask` dataclass MUST include a `git_diff_output: str | None` field defaulting to `None`.
+6. When a rule's `source_dir` is a subdirectory of the project root, the git diff MUST be scoped to that subdirectory (via `-- <relpath>` pathspec). When `source_dir` equals the project root, the diff MUST cover the entire repository.

specs/deepwork/review/REVIEW-REQ-004-rule-matching-and-strategies.md

@@ -16,6 +16,13 @@ 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`).

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

@@ -49,6 +49,7 @@ class ReviewTask:
     source_location: str = ""  # e.g. "src/.deepreview:5"
     additional_files: list[str] = field(default_factory=list)  # Unchanged matching files
     all_changed_filenames: list[str] | None = None
+    git_diff_output: str | None = None  # Pre-fetched git diff for broad rules
 
 
 def parse_deepreview_file(filepath: Path) -> list[ReviewRule]:

src/deepwork/review/config.py

@@ -155,6 +155,16 @@ def build_instruction_file(task: ReviewTask, review_id: str = "") -> str:
             parts.append(f"- @{filepath}")
         parts.append("")
 
+    # Pre-fetched git diff for broad rules
+    if task.git_diff_output:
+        parts.append(
+            "## Output from `git diff main..HEAD` for you to review (sorted by filepath)\n"
+        )
+        parts.append("```diff")
+        parts.append(task.git_diff_output.rstrip())
+        parts.append("```")
+        parts.append("")
+
     # Additional context: all changed filenames
     if task.all_changed_filenames:
         parts.append("## All Changed Files\n")

src/deepwork/review/instructions.py

@@ -192,6 +192,75 @@ def _git_untracked_files(project_root: Path) -> list[str]:
         raise GitDiffError(f"git ls-files failed: {e.stderr.strip()}") from e
 
 
+def _should_inject_diff(rule: ReviewRule) -> bool:
+    """Check if a rule qualifies for git diff injection.
+
+    Rules with ``all_changed_files`` or ``matches_together`` strategy and
+    a ``**/*`` include pattern get the diff injected to reduce reviewer
+    turn count.
+    """
+    if rule.strategy not in ("all_changed_files", "matches_together"):
+        return False
+    return "**/*" in rule.include_patterns
+
+
+def _sort_diff_by_path(diff_text: str) -> str:
+    """Sort a unified diff's file hunks by path.
+
+    Splits on ``diff --git`` boundaries, sorts the chunks
+    alphabetically by file path (which naturally groups by directory),
+    and rejoins them.
+    """
+    if not diff_text.strip():
+        return diff_text
+
+    # Split into per-file chunks.  The first element before the first
+    # "diff --git" marker is usually empty or whitespace — preserve it.
+    parts = re.split(r"(?=^diff --git )", diff_text, flags=re.MULTILINE)
+    chunks: list[tuple[str, str]] = []
+    preamble = ""
+    for part in parts:
+        if part.startswith("diff --git "):
+            # Extract the b-side path: "diff --git a/x b/y" → "y"
+            first_line = part.split("\n", 1)[0]
+            b_path = first_line.rsplit(" b/", 1)[-1] if " b/" in first_line else first_line
+            chunks.append((b_path, part))
+        elif part.strip():
+            preamble += part
+
+    chunks.sort(key=lambda c: c[0])
+    sorted_parts = [c[1] for c in chunks]
+    if preamble:
+        sorted_parts.insert(0, preamble)
+    return "".join(sorted_parts)
+
+
+def _get_git_diff(project_root: Path, scope_dir: Path | None = None) -> str:
+    """Run ``git diff <base>..HEAD`` and return the output, sorted by path.
+
+    Uses the same base-ref detection logic as changed-file detection.
+    When *scope_dir* is provided and differs from *project_root*, the
+    diff is restricted to that subdirectory via ``-- <relpath>``.
+    The output is sorted by file path so that files in the same
+    directory are grouped together.
+    Returns an empty string on failure.
+    """
+    base_ref = _detect_base_ref(project_root)
+    merge_base = _get_merge_base(project_root, base_ref)
+    args = ["diff", f"{merge_base}..HEAD"]
+    if scope_dir is not None and scope_dir != project_root:
+        try:
+            rel = scope_dir.relative_to(project_root)
+            args += ["--", str(rel)]
+        except ValueError:
+            pass
+    try:
+        result = _run_git(project_root, *args)
+        return _sort_diff_by_path(result.stdout)
+    except subprocess.CalledProcessError:
+        return ""
+
+
 def match_files_to_rules(
     changed_files: list[str],
     rules: list[ReviewRule],
@@ -213,6 +282,8 @@ def match_files_to_rules(
         List of ReviewTask objects.
     """
     tasks: list[ReviewTask] = []
+    # Lazy-compute diff per source_dir, shared across qualifying rules
+    _cached_diffs: dict[Path, str] = {}
 
     for rule in rules:
         matched = match_rule(changed_files, rule, project_root)
@@ -223,6 +294,14 @@ def match_files_to_rules(
         all_filenames = changed_files if rule.all_changed_filenames else None
         source_location = format_source_location(rule, project_root)
 
+        # Lazily fetch diff for broad rules to reduce reviewer turn count
+        diff_output: str | None = None
+        if _should_inject_diff(rule):
+            scope = rule.source_dir
+            if scope not in _cached_diffs:
+                _cached_diffs[scope] = _get_git_diff(project_root, scope)
+            diff_output = _cached_diffs[scope] or None
+
         if rule.strategy == "individual":
             for filepath in matched:
                 tasks.append(
@@ -249,6 +328,7 @@ def match_files_to_rules(
                     source_location=source_location,
                     additional_files=additional,
                     all_changed_filenames=all_filenames,
+                    git_diff_output=diff_output,
                 )
             )
 
@@ -261,6 +341,7 @@ def match_files_to_rules(
                     agent_name=agent_name,
                     source_location=source_location,
                     all_changed_filenames=all_filenames,
+                    git_diff_output=diff_output,
                 )
             )