Commit 6fb1764
Implement rules system v2 with markdown format (#56)
* Add policy system v2 design documentation
Design docs for next-generation policy system with:
- File correspondence matching (sets and pairs)
- Idempotent command execution
- Queue-based state tracking with detector/evaluator pattern
- Folder-based policy storage using frontmatter markdown files
Key changes from current system:
- Policies move from single .deepwork.policy.yml to .deepwork/policies/*.md
- YAML frontmatter for config, markdown body for instructions
- New 'set' syntax for bidirectional file relationships
- New 'pair' syntax for directional file relationships
- New 'action' field for running commands instead of prompts
- Queue system prevents duplicate policy triggers across sessions
* Feedback from review
* Simplify policy system design based on feedback
Key changes:
- Restructure taxonomy: detection modes (trigger/safety, set, pair) + action types (prompt, command)
- Add required `name` field for human-friendly promise tag display (e.g., "✓ Source/Test Pairing")
- Remove priority and defer features (not needed yet)
- Clarify .deepwork/tmp is gitignored, so cleanup is not critical
- Shorten output format - group by policy name, use simple arrow notation for correspondence
- Update all examples to include name field
* Remove idempotency verification and unused output_mode config
- Don't enforce idempotency, just document it as expected behavior
- Give lint formatters (black, ruff, prettier) as good examples
- Remove output_mode from config (not referenced elsewhere)
- Remove idempotency verification test scenarios
* Implement policy system v2 with sets, pairs, and command actions
This implements the redesigned policy system with:
- Detection modes: trigger/safety (default), set (bidirectional), pair (directional)
- Action types: prompt (show instructions), command (run idempotent command)
- Variable pattern matching: {path} for multi-segment, {name} for single-segment
- Queue system in .deepwork/tmp/policy/queue/ for state tracking
- Frontmatter markdown format for policy files in .deepwork/policies/
New core modules:
- pattern_matcher.py: Variable pattern matching with regex
- policy_queue.py: Queue system for policy state persistence
- command_executor.py: Command action execution with substitution
Updates to existing modules:
- policy_parser.py: v2 Policy class with detection modes and action types
- policy_check.py: Uses new v2 system with queue deduplication
- evaluate_policies.py: Updated for v1 backward compatibility
- policy_schema.py: New frontmatter schema for v2 format
Tests updated to work with both v1 and v2 APIs.
* Update documentation and version for policy system v2
- Update README.md with v2 policy examples and directory structure
- Update doc/architecture.md with v2 detection modes, action types, and queue system
- Bump version to 0.4.0 in pyproject.toml
- Add changelog entry for v2 policy system features
* Update policy_stop_hook.sh to support both v1 and v2 policy formats
The hook now:
- Checks for v2 policies in .deepwork/policies/ first
- Falls back to v1 policies in .deepwork.policy.yml if no v2 found
- Passes JSON input directly to policy_check.py for v2 (via wrapper)
- Maintains existing behavior for v1 evaluate_policies.py
* Remove v1 policy format support
Remove all legacy v1 policy format (.deepwork.policy.yml) support:
- Remove evaluate_policies.py hook module
- Remove PolicyV1 class and parse_policy_file from policy_parser.py
- Remove v1 schema (POLICY_SCHEMA_V1) from policy_schema.py
- Remove v1 test fixtures and test_evaluate_policies.py
- Update test fixtures to use v2 frontmatter markdown format
- Update documentation to remove v1 references
- Fix policy_stop_hook.sh to handle exit code 2 (block) correctly
Only v2 frontmatter markdown format (.deepwork/policies/*.md) is now supported.
* Format policy_parser.py with ruff
* Update uv.lock
* Rename policy system to rules system
Rename all policy-related terminology to rules throughout the codebase:
- Rename deepwork_policy job to deepwork_rules
- Rename .deepwork.policy.yml to .deepwork.rules.yml
- Rename policy_parser.py, policy_queue.py, policy_check.py to rules_*
- Rename policy_schema.py to rules_schema.py
- Rename policy_stop_hook.sh to rules_stop_hook.sh
- Update all documentation, tests, and references
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Remove stale deepwork_policy hook entries from settings.json
The previous commit renamed deepwork_policy to deepwork_rules but left
duplicate hook entries in settings.json pointing to the old paths.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add comprehensive test coverage and fix security/linting issues
- Add 134 new tests covering test plan scenarios:
- test_pattern_matcher.py: glob patterns, variable extraction, resolution
- test_command_executor.py: variable substitution, command execution
- test_rules_queue.py: queue entry lifecycle, hash calculation
- test_schema_validation.py: required fields, mutual exclusivity
- Extended test_rules_parser.py with correspondence sets/pairs tests
- Security: Add shlex.quote() to command_executor.py to prevent
command injection via malicious file paths
- Fix ruff linting issues in pattern_matcher.py, rules_queue.py,
and rules_check.py (f-strings, datetime.UTC, open mode)
- Update .gitignore comment from "policy" to "rules"
- Remove doc/test_scenarios.md (all scenarios now covered by tests)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Complete migration from v1 to v2 rules format
- Replace single .deepwork.rules.yml (v1) with individual .md files
in .deepwork/rules/ directory (v2 frontmatter markdown format)
- Update install.py to create rules directory structure with:
- README explaining v2 format
- Example templates (.md.example files)
- Add v2 example templates in standard_jobs/deepwork_rules/rules/:
- readme-documentation.md.example (trigger/safety mode)
- api-documentation-sync.md.example (trigger/safety mode)
- security-review.md.example (trigger-only mode)
- source-test-pairing.md.example (set/bidirectional mode)
- Completely rewrite deepwork_rules.define step for v2 format:
- Detection mode selection (trigger/safety, set, pair)
- Variable pattern syntax ({path}, {name})
- Updated examples and file location guidance
- Migrate this repo's bespoke rules to v2:
- readme-accuracy.md
- architecture-documentation-accuracy.md
- standard-jobs-source-of-truth.md
- version-and-changelog-update.md
- Remove deprecated src/deepwork/templates/default_rules.yml
- Update integration tests for v2 directory structure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix hook exit code to always return 0 with JSON format
Hooks using JSON output format should always exit with code 0.
The blocking behavior is controlled by the "decision" field in the
JSON output, not the exit code.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add critical contract warning comments to hook test files
Add prominent warning comments to test files that verify Claude Code hook
JSON format and exit code contracts. These comments reference the official
documentation and clearly mark tests that should not be modified without
consulting the hook specification.
Files updated:
- tests/shell_script_tests/test_hooks_json_format.py
- tests/shell_script_tests/test_hook_wrappers.py
- tests/unit/test_hook_wrapper.py
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Merge hook test files into single test_hooks.py
Consolidate test_hooks_json_format.py and test_hook_wrappers.py into a
single test_hooks.py file with logical organization:
- TestClaudeHookWrapper / TestGeminiHookWrapper: Platform wrapper scripts
- TestRulesStopHook / TestUserPromptSubmitHook: Rules-specific hooks
- TestHooksWithTranscript: Transcript input handling
- TestHookExitCodes: Exit code contract tests (DO NOT EDIT)
- TestHookWrapperIntegration: Integration tests with Python hooks
- TestRulesCheckModule: Python module tests
Also moved hooks_dir and src_dir fixtures to conftest.py for sharing.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Format code with ruff
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix ruff linting errors (unused imports, import sorting)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Cleanup hooks and wrappers
* Create manual test files for rule styles (#61)
* Add manual test files for testing hook/rule functionality
Creates manual_tests/claude/ directory with test files that exercise
different rule styles:
- Trigger/Safety mode (basic conditional)
- Set mode (bidirectional correspondence)
- Pair mode (directional correspondence)
- Command action (automatic command execution)
- Multi-safety (multiple safety patterns)
Each test file includes documentation explaining what it tests,
how to trigger it, and expected behavior. Corresponding rule
definitions added to .deepwork/rules/.
* Move manual test files from manual_tests/claude/ to manual_tests/
Flatten directory structure as requested. Updated all rule definitions
to reference the new paths.
* Reorganize manual tests into subfolders per test type
Group related files together:
- test_trigger_safety_mode/
- test_set_mode/
- test_pair_mode/
- test_command_action/
- test_multi_safety/
Updated rule definitions and README to match new structure.
* Add compare_to: prompt to manual test rules
This ensures rules evaluate against changes since the last prompt
rather than against the merge-base, allowing them to fire during
the current conversation when files are edited.
* Add sub-agent testing instructions to manual tests README
Explains that the best way to run these tests is as sub-agents
using a fast model (haiku), with example prompts and verification
commands.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update manual test files with both-case test instructions
- Updated README with test matrix showing expected results
- Added TEST CASE sections to each test file documenting both
"should fire" and "should NOT fire" scenarios
- Added test results tracking table to README
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent b6bc46b commit 6fb1764
122 files changed
Lines changed: 8251 additions & 4034 deletions
File tree
- .claude
- commands
- .deepwork
- jobs
- add_platform
- steps
- deepwork_jobs
- steps
- deepwork_policy
- hooks
- steps
- deepwork_rules
- hooks
- rules
- steps
- update
- steps
- rules
- .gemini/commands
- add_platform
- deepwork_jobs
- deepwork_policy
- deepwork_rules
- update
- doc
- platform/gemini
- manual_tests
- test_command_action
- test_multi_safety
- test_pair_mode
- test_set_mode
- test_trigger_safety_mode
- src/deepwork
- cli
- core
- hooks
- schemas
- standard_jobs
- deepwork_jobs
- steps
- deepwork_policy
- hooks
- steps
- deepwork_rules
- hooks
- rules
- steps
- templates
- tests
- fixtures/policies
- instructions
- integration
- shell_script_tests
- unit
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
17 | | - | |
| 17 | + | |
18 | 18 | | |
19 | 19 | | |
20 | 20 | | |
| |||
121 | 121 | | |
122 | 122 | | |
123 | 123 | | |
124 | | - | |
| 124 | + | |
125 | 125 | | |
126 | 126 | | |
127 | 127 | | |
| |||
151 | 151 | | |
152 | 152 | | |
153 | 153 | | |
154 | | - | |
| 154 | + | |
155 | 155 | | |
156 | 156 | | |
157 | 157 | | |
| |||
218 | 218 | | |
219 | 219 | | |
220 | 220 | | |
221 | | - | |
| 221 | + | |
222 | 222 | | |
223 | 223 | | |
224 | 224 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | | - | |
23 | | - | |
24 | | - | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
| |||
200 | 200 | | |
201 | 201 | | |
202 | 202 | | |
203 | | - | |
| 203 | + | |
204 | 204 | | |
205 | | - | |
| 205 | + | |
206 | 206 | | |
207 | | - | |
| 207 | + | |
208 | 208 | | |
209 | | - | |
| 209 | + | |
210 | 210 | | |
211 | 211 | | |
212 | 212 | | |
213 | 213 | | |
214 | 214 | | |
215 | | - | |
| 215 | + | |
216 | 216 | | |
217 | 217 | | |
218 | 218 | | |
219 | 219 | | |
220 | 220 | | |
221 | 221 | | |
222 | 222 | | |
223 | | - | |
| 223 | + | |
224 | 224 | | |
225 | | - | |
226 | | - | |
| 225 | + | |
| 226 | + | |
227 | 227 | | |
228 | 228 | | |
229 | 229 | | |
230 | 230 | | |
231 | 231 | | |
232 | 232 | | |
233 | | - | |
| 233 | + | |
234 | 234 | | |
235 | | - | |
236 | | - | |
| 235 | + | |
| 236 | + | |
237 | 237 | | |
238 | 238 | | |
239 | 239 | | |
240 | 240 | | |
241 | 241 | | |
242 | | - | |
| 242 | + | |
243 | 243 | | |
244 | | - | |
| 244 | + | |
245 | 245 | | |
246 | 246 | | |
247 | 247 | | |
| |||
250 | 250 | | |
251 | 251 | | |
252 | 252 | | |
253 | | - | |
| 253 | + | |
254 | 254 | | |
255 | 255 | | |
256 | 256 | | |
257 | 257 | | |
258 | | - | |
| 258 | + | |
259 | 259 | | |
260 | 260 | | |
261 | | - | |
| 261 | + | |
262 | 262 | | |
263 | 263 | | |
264 | 264 | | |
| |||
292 | 292 | | |
293 | 293 | | |
294 | 294 | | |
295 | | - | |
296 | | - | |
| 295 | + | |
| 296 | + | |
297 | 297 | | |
298 | 298 | | |
299 | 299 | | |
| |||
305 | 305 | | |
306 | 306 | | |
307 | 307 | | |
308 | | - | |
| 308 | + | |
309 | 309 | | |
310 | 310 | | |
311 | 311 | | |
| |||
355 | 355 | | |
356 | 356 | | |
357 | 357 | | |
358 | | - | |
359 | | - | |
360 | | - | |
| 358 | + | |
| 359 | + | |
| 360 | + | |
361 | 361 | | |
362 | 362 | | |
363 | 363 | | |
| |||
0 commit comments