Skip to content

Commit 6fb1764

Browse files
nhortonclaude
andauthored
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

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.claude/commands/add_platform.verify.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ hooks:
1414
2. Running `deepwork install --platform <platform>` completes without errors
1515
3. Expected command files are created in the platform's command directory
1616
4. Command file content matches the templates and job definitions
17-
5. Established DeepWork jobs (deepwork_jobs, deepwork_policy) are installed correctly
17+
5. Established DeepWork jobs (deepwork_jobs, deepwork_rules) are installed correctly
1818
6. The platform can be used alongside existing platforms without conflicts
1919
2020
If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.
@@ -121,7 +121,7 @@ Ensure the implementation step is complete:
121121
- `deepwork_jobs.define.md` exists (or equivalent for the platform)
122122
- `deepwork_jobs.implement.md` exists
123123
- `deepwork_jobs.refine.md` exists
124-
- `deepwork_policy.define.md` exists
124+
- `deepwork_rules.define.md` exists
125125
- All expected step commands exist
126126

127127
4. **Validate command file content**
@@ -151,7 +151,7 @@ Ensure the implementation step is complete:
151151
- `deepwork install --platform <platform_name>` completes without errors
152152
- All expected command files are created:
153153
- deepwork_jobs.define, implement, refine
154-
- deepwork_policy.define
154+
- deepwork_rules.define
155155
- Any other standard job commands
156156
- Command file content is correct:
157157
- Matches platform's expected format
@@ -218,7 +218,7 @@ Verify the installation meets ALL criteria:
218218
2. Running `deepwork install --platform <platform>` completes without errors
219219
3. Expected command files are created in the platform's command directory
220220
4. Command file content matches the templates and job definitions
221-
5. Established DeepWork jobs (deepwork_jobs, deepwork_policy) are installed correctly
221+
5. Established DeepWork jobs (deepwork_jobs, deepwork_rules) are installed correctly
222222
6. The platform can be used alongside existing platforms without conflicts
223223

224224
If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.

.claude/commands/deepwork_jobs.implement.md

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ hooks:
1919
6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
2020
7. **Sync Complete**: Has `deepwork sync` been run successfully?
2121
8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
22-
9. **Policies Considered**: Have you thought about whether policies would benefit this job?
23-
- If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
24-
- Not every job needs policies - only suggest when genuinely helpful.
22+
9. **Rules Considered**: Have you thought about whether rules would benefit this job?
23+
- If relevant rules were identified, did you explain them and offer to run `/deepwork_rules.define`?
24+
- Not every job needs rules - only suggest when genuinely helpful.
2525
2626
If ANY criterion is not met, continue working to address it.
2727
If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
@@ -200,48 +200,48 @@ This will:
200200

201201
After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
202202

203-
### Step 7: Consider Policies for the New Job
203+
### Step 7: Consider Rules for the New Job
204204

205-
After implementing the job, consider whether there are **policies** that would help enforce quality or consistency when working with this job's domain.
205+
After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.
206206

207-
**What are policies?**
207+
**What are rules?**
208208

209-
Policies are automated guardrails defined in `.deepwork.policy.yml` that trigger when certain files change during an AI session. They help ensure:
209+
Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure:
210210
- Documentation stays in sync with code
211211
- Team guidelines are followed
212212
- Architectural decisions are respected
213213
- Quality standards are maintained
214214

215-
**When to suggest policies:**
215+
**When to suggest rules:**
216216

217217
Think about the job you just implemented and ask:
218218
- Does this job produce outputs that other files depend on?
219219
- Are there documentation files that should be updated when this job's outputs change?
220220
- Are there quality checks or reviews that should happen when certain files in this domain change?
221221
- Could changes to the job's output files impact other parts of the project?
222222

223-
**Examples of policies that might make sense:**
223+
**Examples of rules that might make sense:**
224224

225-
| Job Type | Potential Policy |
226-
|----------|------------------|
225+
| Job Type | Potential Rule |
226+
|----------|----------------|
227227
| API Design | "Update API docs when endpoint definitions change" |
228228
| Database Schema | "Review migrations when schema files change" |
229229
| Competitive Research | "Update strategy docs when competitor analysis changes" |
230230
| Feature Development | "Update changelog when feature files change" |
231231
| Configuration Management | "Update install guide when config files change" |
232232

233-
**How to offer policy creation:**
233+
**How to offer rule creation:**
234234

235-
If you identify one or more policies that would benefit the user, explain:
236-
1. **What the policy would do** - What triggers it and what action it prompts
235+
If you identify one or more rules that would benefit the user, explain:
236+
1. **What the rule would do** - What triggers it and what action it prompts
237237
2. **Why it would help** - How it prevents common mistakes or keeps things in sync
238238
3. **What files it would watch** - The trigger patterns
239239

240240
Then ask the user:
241241

242-
> "Would you like me to create this policy for you? I can run `/deepwork_policy.define` to set it up."
242+
> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up."
243243

244-
If the user agrees, invoke the `/deepwork_policy.define` command to guide them through creating the policy.
244+
If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule.
245245

246246
**Example dialogue:**
247247

@@ -250,15 +250,15 @@ Based on the competitive_research job you just created, I noticed that when
250250
competitor analysis files change, it would be helpful to remind you to update
251251
your strategy documentation.
252252

253-
I'd suggest a policy like:
253+
I'd suggest a rule like:
254254
- **Name**: "Update strategy when competitor analysis changes"
255255
- **Trigger**: `**/positioning_report.md`
256256
- **Action**: Prompt to review and update `docs/strategy.md`
257257

258-
Would you like me to create this policy? I can run `/deepwork_policy.define` to set it up.
258+
Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up.
259259
```
260260
261-
**Note:** Not every job needs policies. Only suggest them when they would genuinely help maintain consistency or quality. Don't force policies where they don't make sense.
261+
**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense.
262262
263263
## Example Implementation
264264
@@ -292,8 +292,8 @@ Before marking this step complete, ensure:
292292
- [ ] `deepwork sync` executed successfully
293293
- [ ] Commands generated in platform directory
294294
- [ ] User informed to follow reload instructions from `deepwork sync`
295-
- [ ] Considered whether policies would benefit this job (Step 7)
296-
- [ ] If policies suggested, offered to run `/deepwork_policy.define`
295+
- [ ] Considered whether rules would benefit this job (Step 7)
296+
- [ ] If rules suggested, offered to run `/deepwork_rules.define`
297297
298298
## Quality Criteria
299299
@@ -305,7 +305,7 @@ Before marking this step complete, ensure:
305305
- Steps with user inputs explicitly use "ask structured questions" phrasing
306306
- Sync completed successfully
307307
- Commands available for use
308-
- Thoughtfully considered relevant policies for the job domain
308+
- Thoughtfully considered relevant rules for the job domain
309309
310310
311311
## Inputs
@@ -355,9 +355,9 @@ Verify the implementation meets ALL quality criteria before completing:
355355
6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
356356
7. **Sync Complete**: Has `deepwork sync` been run successfully?
357357
8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
358-
9. **Policies Considered**: Have you thought about whether policies would benefit this job?
359-
- If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
360-
- Not every job needs policies - only suggest when genuinely helpful.
358+
9. **Rules Considered**: Have you thought about whether rules would benefit this job?
359+
- If relevant rules were identified, did you explain them and offer to run `/deepwork_rules.define`?
360+
- Not every job needs rules - only suggest when genuinely helpful.
361361

362362
If ANY criterion is not met, continue working to address it.
363363
If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.

0 commit comments

Comments
 (0)