Doc updates for compare_to

.deepwork/jobs/deepwork_rules/rules/skill-md-validation.md

@@ -1,6 +1,7 @@
 ---
 name: SKILL.md Validation
 trigger: "**/SKILL.md"
+compare_to: base
 ---
 A SKILL.md file has been created or modified. Please validate that it follows the required format:
 

.deepwork/rules/architecture-documentation-accuracy.md

@@ -2,6 +2,7 @@
 name: Architecture Documentation Accuracy
 trigger: src/**/*
 safety: doc/architecture.md
+compare_to: base
 ---
 Source code in src/ has been modified. Please review doc/architecture.md for accuracy:
 1. Verify the documented architecture matches the current implementation

.deepwork/rules/readme-accuracy.md

@@ -2,6 +2,7 @@
 name: README Accuracy
 trigger: src/**/*
 safety: README.md
+compare_to: base
 ---
 Source code in src/ has been modified. Please review README.md for accuracy:
 1. Verify project overview still reflects current functionality

.deepwork/rules/standard-jobs-source-of-truth.md

@@ -6,6 +6,7 @@ trigger:
 safety:
   - src/deepwork/standard_jobs/deepwork_jobs/**/*
   - src/deepwork/standard_jobs/deepwork_rules/**/*
+compare_to: base
 ---
 You modified files in `.deepwork/jobs/deepwork_jobs/` or `.deepwork/jobs/deepwork_rules/`.
 

.deepwork/rules/version-and-changelog-update.md

@@ -4,6 +4,7 @@ trigger: src/**/*
 safety:
   - pyproject.toml
   - CHANGELOG.md
+compare_to: base
 ---
 Source code in src/ has been modified. **You MUST evaluate whether version and changelog updates are needed.**
 

README.md

@@ -262,6 +262,7 @@ name: Source/Test Pairing
 set:
   - src/{path}.py
   - tests/{path}_test.py
+compare_to: base
 ---
 When source files change, corresponding test files should also change.
 Please create or update tests for the modified source files.
@@ -275,6 +276,7 @@ trigger: "**/*.py"
 action:
   command: "ruff format {file}"
   run_for: each_match
+compare_to: prompt
 ---
 ```
 

doc/architecture.md

@@ -1028,6 +1028,7 @@ name: Source/Test Pairing
 set:
   - src/{path}.py
   - tests/{path}_test.py
+compare_to: base
 ---
 When source files change, corresponding test files should also change.
 Please create or update tests for the modified source files.
@@ -1043,6 +1044,7 @@ Rules support three detection modes:
 name: Update install guide
 trigger: "app/config/**/*"
 safety: "docs/install_guide.md"
+compare_to: base
 ---
 ```
 
@@ -1053,6 +1055,7 @@ name: Source/Test Pairing
 set:
   - src/{path}.py
   - tests/{path}_test.py
+compare_to: base
 ---
 ```
 Uses variable patterns like `{path}` (multi-segment) and `{name}` (single-segment) for matching.
@@ -1064,6 +1067,7 @@ name: API Documentation
 pair:
   trigger: src/api/{name}.py
   expects: docs/api/{name}.md
+compare_to: base
 ---
 ```
 
@@ -1074,6 +1078,7 @@ pair:
 ---
 name: Security Review
 trigger: "src/auth/**/*"
+compare_to: base
 ---
 Please check for hardcoded credentials and validate input.
 ```
@@ -1086,6 +1091,7 @@ trigger: "**/*.py"
 action:
   command: "ruff format {file}"
   run_for: each_match  # or "all_matches"
+compare_to: prompt
 ---
 ```
 

doc/rules_syntax.md

@@ -36,6 +36,7 @@ class AuthService:
 name: README Accuracy
 trigger: src/**/*
 safety: README.md
+compare_to: base
 ---
 Source code changed. Please verify README.md is accurate.
 
@@ -54,6 +55,7 @@ name: Source/Test Pairing
 set:
   - src/{path}.py
   - tests/{path}_test.py
+compare_to: base
 ---
 Source and test files should change together.
 
@@ -70,6 +72,7 @@ name: API Documentation
 pair:
   trigger: api/{path}.py
   expects: docs/api/{path}.md
+compare_to: base
 ---
 API changes require documentation updates.
 
@@ -88,6 +91,7 @@ name: Python Formatting
 trigger: "**/*.py"
 action:
   command: ruff format {file}
+compare_to: prompt
 ---
 Automatically formats Python files using ruff.
 
@@ -145,6 +149,7 @@ name: Source/Test Pairing
 set:
   - src/{path}.py
   - tests/{path}_test.py
+compare_to: base
 ---
 ```
 
@@ -176,18 +181,21 @@ name: API Documentation
 pair:
   trigger: api/{module}/{name}.py
   expects: docs/api/{module}/{name}.md
+compare_to: base
 ---
 ```
 
 Can specify multiple expected patterns:
 
 ```yaml
 ---
+name: API Documentation
 pair:
   trigger: api/{path}.py
   expects:
     - docs/api/{path}.md
     - schemas/{path}.json
+compare_to: base
 ---
 ```
 
@@ -224,6 +232,7 @@ safety: "*.pyi"
 action:
   command: ruff format {file}
   run_for: each_match
+compare_to: prompt
 ---
 ```
 
@@ -385,19 +394,19 @@ action:
 ---
 ```
 
-### compare_to (optional)
+### compare_to (required)
 
 Determines the baseline for detecting file changes.
 
 | Value | Description |
 |-------|-------------|
-| `base` (default) | Compare to merge-base with default branch |
+| `base` | Compare to merge-base with default branch |
 | `default_tip` | Compare to current tip of default branch |
 | `prompt` | Compare to state at last prompt submission |
 
 ```yaml
 ---
-compare_to: prompt
+compare_to: base
 ---
 ```
 
@@ -412,6 +421,7 @@ name: Test Coverage
 set:
   - src/{path}.py
   - tests/{path}_test.py
+compare_to: base
 ---
 Source code was modified without corresponding test updates.
 
@@ -434,6 +444,7 @@ pair:
   expects:
     - docs/api/{module}/{endpoint}.md
     - openapi/{module}.yaml
+compare_to: base
 ---
 API endpoint changed. Please update:
 - Documentation: {expected_files}
@@ -453,6 +464,7 @@ safety:
 action:
   command: black {file}
   run_for: each_match
+compare_to: prompt
 ---
 Formats Python files using Black.
 
@@ -472,6 +484,7 @@ set:
   - backend/api/{feature}/models.py
   - frontend/src/api/{feature}.ts
   - frontend/src/components/{feature}/**/*
+compare_to: base
 ---
 Feature files should be updated together across the stack.
 
@@ -494,6 +507,7 @@ trigger:
 safety:
   - pyproject.toml
   - CHANGELOG.md
+compare_to: base
 ---
 Code changes detected. Before merging, ensure:
 - Version is bumped in pyproject.toml (if needed)

src/deepwork/core/rules_parser.py

@@ -40,7 +40,6 @@ class ActionType(Enum):
 
 # Valid compare_to values
 COMPARE_TO_VALUES = frozenset({"base", "default_tip", "prompt"})
-DEFAULT_COMPARE_TO = "base"
 
 
 @dataclass
@@ -69,6 +68,11 @@ class Rule:
 
     # Detection mode (exactly one must be set)
     detection_mode: DetectionMode
+
+    # Common options (required)
+    compare_to: str  # Required: "base", "default_tip", or "prompt"
+
+    # Detection mode details (optional, depends on mode)
     triggers: list[str] = field(default_factory=list)  # For TRIGGER_SAFETY mode
     safety: list[str] = field(default_factory=list)  # For TRIGGER_SAFETY mode
     set_patterns: list[str] = field(default_factory=list)  # For SET mode
@@ -79,9 +83,6 @@ class Rule:
     instructions: str = ""  # For PROMPT action (markdown body)
     command_action: CommandAction | None = None  # For COMMAND action
 
-    # Common options
-    compare_to: str = DEFAULT_COMPARE_TO
-
     @classmethod
     def from_frontmatter(
         cls,
@@ -166,8 +167,8 @@ def from_frontmatter(
             if not markdown_body.strip():
                 raise RulesParseError(f"Rule '{name}' with prompt action requires markdown body")
 
-        # Get compare_to
-        compare_to = frontmatter.get("compare_to", DEFAULT_COMPARE_TO)
+        # Get compare_to (required field)
+        compare_to = frontmatter["compare_to"]
 
         return cls(
             name=name,

src/deepwork/schemas/rules_schema.py

@@ -15,7 +15,7 @@
 RULES_FRONTMATTER_SCHEMA: dict[str, Any] = {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "type": "object",
-    "required": ["name"],
+    "required": ["name", "compare_to"],
     "properties": {
         "name": {
             "type": "string",
@@ -80,7 +80,6 @@
         "compare_to": {
             "type": "string",
             "enum": ["base", "default_tip", "prompt"],
-            "default": "base",
             "description": "Baseline for detecting file changes",
         },
     },

src/deepwork/standard_jobs/deepwork_rules/rules/skill-md-validation.md

@@ -1,6 +1,7 @@
 ---
 name: SKILL.md Validation
 trigger: "**/SKILL.md"
+compare_to: base
 ---
 A SKILL.md file has been created or modified. Please validate that it follows the required format: