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

Author: claude

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to DeepWork will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-01-16
+
+### Added
+- Policy system v2 with frontmatter markdown format in `.deepwork/policies/`
+  - Detection modes: trigger/safety (default), set (bidirectional), pair (directional)
+  - Action types: prompt (show instructions), command (run idempotent commands)
+  - Variable pattern matching with `{path}` (multi-segment) and `{name}` (single-segment)
+  - Queue system in `.deepwork/tmp/policy/queue/` for state tracking and deduplication
+- New core modules:
+  - `pattern_matcher.py`: Variable pattern matching with regex-based capture
+  - `policy_queue.py`: Queue system for policy state persistence
+  - `command_executor.py`: Command action execution with variable substitution
+- Updated `policy_check.py` hook to use v2 system with queue-based deduplication
+
+### Changed
+- Policy parser now supports both v1 (`.deepwork.policy.yml`) and v2 (`.deepwork/policies/*.md`) formats
+- Documentation updated with v2 policy examples and configuration
+
 ## [0.3.0] - 2026-01-16
 
 ### Added
@@ -64,6 +82,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Initial version.
 
+[0.4.0]: https://github.com/anthropics/deepwork/releases/tag/0.4.0
 [0.3.0]: https://github.com/anthropics/deepwork/releases/tag/0.3.0
 [0.1.1]: https://github.com/anthropics/deepwork/releases/tag/0.1.1
 [0.1.0]: https://github.com/anthropics/deepwork/releases/tag/0.1.0

README.md

@@ -178,6 +178,10 @@ DeepWork follows a **Git-native, installation-only** design:
 your-project/
 ├── .deepwork/
 │   ├── config.yml          # Platform configuration
+│   ├── policies/           # Policy definitions (v2 format)
+│   │   └── policy-name.md  # Individual policy files
+│   ├── tmp/                # Temporary state (gitignored)
+│   │   └── policy/queue/   # Policy evaluation queue
 │   └── jobs/               # Job definitions
 │       └── job_name/
 │           ├── job.yml     # Job metadata
@@ -208,11 +212,16 @@ deepwork/
 │   ├── core/             # Core functionality
 │   │   ├── parser.py     # Job definition parsing
 │   │   ├── detector.py   # Platform detection
-│   │   └── generator.py  # Skill file generation
+│   │   ├── generator.py  # Skill file generation
+│   │   ├── policy_parser.py    # Policy parsing (v1 and v2)
+│   │   ├── pattern_matcher.py  # Variable pattern matching
+│   │   ├── policy_queue.py     # Policy state queue
+│   │   └── command_executor.py # Command action execution
 │   ├── hooks/            # Cross-platform hook wrappers
 │   │   ├── wrapper.py    # Input/output normalization
-│   │   ├── claude_hook.sh  # Claude Code adapter
-│   │   └── gemini_hook.sh  # Gemini CLI adapter
+│   │   ├── policy_check.py   # Policy evaluation hook (v2)
+│   │   ├── claude_hook.sh    # Claude Code adapter
+│   │   └── gemini_hook.sh    # Gemini CLI adapter
 │   ├── templates/        # Jinja2 templates
 │   │   ├── claude/       # Claude Code templates
 │   │   └── gemini/       # Gemini CLI templates
@@ -243,15 +252,31 @@ Maintain a clean repository with automatic branch management and isolation.
 ### 🛡️ Automated Policies
 Enforce project standards and best practices without manual oversight. Policies monitor file changes and automatically prompt your AI assistant to follow specific guidelines when relevant code is modified.
 - **Automatic Triggers**: Detect when specific files or directories are changed to fire relevant policies.
+- **File Correspondence**: Define bidirectional (set) or directional (pair) relationships between files.
+- **Command Actions**: Run idempotent commands (formatters, linters) automatically when files change.
 - **Contextual Guidance**: Instructions are injected directly into the AI's workflow at the right moment.
-- **Common Use Cases**: Keep documentation in sync, enforce security reviews, or automate changelog updates.
 
-**Example Policy**:
-```yaml
-# Enforce documentation updates when config changes
-- name: "Update docs on config changes"
-  trigger: "app/config/**/*"
-  instructions: "Configuration files changed. Please update docs/install_guide.md."
+**Example Policy** (`.deepwork/policies/source-test-pairing.md`):
+```markdown
+---
+name: Source/Test Pairing
+set:
+  - src/{path}.py
+  - tests/{path}_test.py
+---
+When source files change, corresponding test files should also change.
+Please create or update tests for the modified source files.
+```
+
+**Example Command Policy** (`.deepwork/policies/format-python.md`):
+```markdown
+---
+name: Format Python
+trigger: "**/*.py"
+action:
+  command: "ruff format {file}"
+  run_for: each_match
+---
 ```
 
 ### 🚀 Multi-Platform Support

doc/architecture.md

@@ -46,8 +46,11 @@ deepwork/                       # DeepWork tool repository
 │       │   ├── detector.py     # AI platform detection
 │       │   ├── generator.py    # Command file generation
 │       │   ├── parser.py       # Job definition parsing
-│       │   ├── policy_parser.py # Policy definition parsing
-│       │   └── hooks_syncer.py # Hook syncing to platforms
+│       │   ├── policy_parser.py    # Policy definition parsing (v1 and v2)
+│       │   ├── pattern_matcher.py  # Variable pattern matching for policies
+│       │   ├── policy_queue.py     # Policy state queue system
+│       │   ├── command_executor.py # Command action execution
+│       │   └── hooks_syncer.py     # Hook syncing to platforms
 │       ├── hooks/              # Hook system and cross-platform wrappers
 │       │   ├── __init__.py
 │       │   ├── wrapper.py           # Cross-platform input/output normalization
@@ -286,7 +289,13 @@ my-project/                     # User's project (target)
 │       └── ...
 ├── .deepwork/                  # DeepWork configuration
 │   ├── config.yml              # Platform config
-│   ├── .gitignore              # Ignores .last_work_tree
+│   ├── .gitignore              # Ignores tmp/ directory
+│   ├── policies/               # Policy definitions (v2 format)
+│   │   ├── source-test-pairing.md
+│   │   ├── format-python.md
+│   │   └── api-docs.md
+│   ├── tmp/                    # Temporary state (gitignored)
+│   │   └── policy/queue/       # Policy evaluation queue
 │   └── jobs/                   # Job definitions
 │       ├── deepwork_jobs/      # Core job for managing jobs
 │       │   ├── job.yml
@@ -305,7 +314,7 @@ my-project/                     # User's project (target)
 │       │   └── steps/
 │       └── ad_campaign/
 │           └── ...
-├── .deepwork.policy.yml        # Policy definitions (project root)
+├── .deepwork.policy.yml        # Legacy policy definitions (v1 format)
 ├── (rest of user's project files)
 └── README.md
 ```
@@ -1000,74 +1009,151 @@ Policies are automated enforcement rules that trigger based on file changes duri
 - Documentation stays in sync with code changes
 - Security reviews happen when sensitive code is modified
 - Team guidelines are followed automatically
+- File correspondences are maintained (e.g., source/test pairing)
 
-### Policy Configuration File
+### Policy System v2 (Frontmatter Markdown)
 
-Policies are defined in `.deepwork.policy.yml` at the project root:
+Policies are defined as individual markdown files in `.deepwork/policies/`:
 
+```
+.deepwork/policies/
+├── source-test-pairing.md
+├── format-python.md
+└── api-docs.md
+```
+
+Each policy file uses YAML frontmatter with a markdown body for instructions:
+
+```markdown
+---
+name: Source/Test Pairing
+set:
+  - src/{path}.py
+  - tests/{path}_test.py
+---
+When source files change, corresponding test files should also change.
+Please create or update tests for the modified source files.
+```
+
+### Detection Modes
+
+Policies support three detection modes:
+
+**1. Trigger/Safety (default)** - Fire when trigger matches but safety doesn't:
 ```yaml
-- name: "Update install guide on config changes"
-  trigger: "app/config/**/*"
-  safety: "docs/install_guide.md"
-  instructions: |
-    Configuration files have been modified. Please review docs/install_guide.md
-    and update it if any installation instructions need to change.
-
-- name: "Security review for auth changes"
-  trigger:
-    - "src/auth/**/*"
-    - "src/security/**/*"
-  safety:
-    - "SECURITY.md"
-    - "docs/security_audit.md"
-  instructions: |
-    Authentication or security code has been changed. Please:
-    1. Check for hardcoded credentials
-    2. Verify input validation
-    3. Review access control logic
+---
+name: Update install guide
+trigger: "app/config/**/*"
+safety: "docs/install_guide.md"
+---
+```
+
+**2. Set (bidirectional)** - Enforce file correspondence in both directions:
+```yaml
+---
+name: Source/Test Pairing
+set:
+  - src/{path}.py
+  - tests/{path}_test.py
+---
+```
+Uses variable patterns like `{path}` (multi-segment) and `{name}` (single-segment) for matching.
+
+**3. Pair (directional)** - Trigger requires corresponding files, but not vice versa:
+```yaml
+---
+name: API Documentation
+pair:
+  trigger: src/api/{name}.py
+  expects: docs/api/{name}.md
+---
+```
+
+### Action Types
+
+**1. Prompt (default)** - Show instructions to the agent:
+```yaml
+---
+name: Security Review
+trigger: "src/auth/**/*"
+---
+Please check for hardcoded credentials and validate input.
+```
+
+**2. Command** - Run an idempotent command:
+```yaml
+---
+name: Format Python
+trigger: "**/*.py"
+action:
+  command: "ruff format {file}"
+  run_for: each_match  # or "all_matches"
+---
 ```
 
 ### Policy Evaluation Flow
 
 1. **Session Start**: When a Claude Code session begins, the baseline git state is captured
 2. **Agent Works**: The AI agent performs tasks, potentially modifying files
-3. **Session Stop**: When the agent finishes:
-   - Changed files are detected by comparing against the baseline
-   - Each policy is evaluated:
-     - If any changed file matches a `trigger` pattern AND
-     - No changed file matches a `safety` pattern AND
-     - The agent hasn't marked it with a `<promise>` tag
-     - → The policy fires
-   - If policies fire, Claude is prompted to address them
+3. **Session Stop**: When the agent finishes (after_agent event):
+   - Changed files are detected based on `compare_to` setting (base, default_tip, or prompt)
+   - Each policy is evaluated based on its detection mode
+   - Queue entries are created in `.deepwork/tmp/policy/queue/` for deduplication
+   - For command actions: commands are executed, results tracked
+   - For prompt actions: if policy fires and not already promised, agent is prompted
 4. **Promise Tags**: Agents can mark policies as addressed by including `<promise>✓ Policy Name</promise>` in their response
 
+### Queue System
+
+Policy state is tracked in `.deepwork/tmp/policy/queue/` with files named `{hash}.{status}.json`:
+- `queued` - Detected, awaiting evaluation
+- `passed` - Policy satisfied (promise found or command succeeded)
+- `failed` - Policy not satisfied
+- `skipped` - Safety pattern matched
+
+This prevents re-prompting for the same policy violation within a session.
+
 ### Hook Integration
 
-Policies are implemented using Claude Code's hooks system. The `deepwork_policy` standard job includes:
+The v2 policy system uses the cross-platform hook wrapper:
 
 ```
-.deepwork/jobs/deepwork_policy/hooks/
-├── global_hooks.yml              # Maps lifecycle events to scripts
-├── user_prompt_submit.sh         # Captures baseline at each prompt
-├── capture_prompt_work_tree.sh   # Creates git state snapshot for compare_to: prompt
-└── policy_stop_hook.sh           # Evaluates policies on stop (calls Python evaluator)
+src/deepwork/hooks/
+├── wrapper.py           # Cross-platform input/output normalization
+├── policy_check.py      # Policy evaluation hook (v2)
+├── claude_hook.sh       # Claude Code shell wrapper
+└── gemini_hook.sh       # Gemini CLI shell wrapper
+```
+
+Hooks are called via the shell wrappers:
+```bash
+claude_hook.sh deepwork.hooks.policy_check
 ```
 
 The hooks are installed to `.claude/settings.json` during `deepwork sync`:
 
 ```json
 {
   "hooks": {
-    "UserPromptSubmit": [
-      {"matcher": "", "hooks": [{"type": "command", "command": ".deepwork/jobs/deepwork_policy/hooks/user_prompt_submit.sh"}]}
-    ],
     "Stop": [
       {"matcher": "", "hooks": [{"type": "command", "command": ".deepwork/jobs/deepwork_policy/hooks/policy_stop_hook.sh"}]}
     ]
   }
 }
 ```
 
+### Legacy v1 Format
+
+The v1 format (`.deepwork.policy.yml`) is still supported for backward compatibility:
+
+```yaml
+- name: "Update install guide"
+  trigger: "app/config/**/*"
+  safety: "docs/install_guide.md"
+  instructions: |
+    Configuration files have been modified. Please review docs/install_guide.md.
+```
+
 ### Cross-Platform Hook Wrapper System
 
 The `hooks/` module provides a wrapper system that allows writing hooks once in Python and running them on multiple platforms. This normalizes the differences between Claude Code and Gemini CLI hook systems.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepwork"
-version = "0.3.0"
+version = "0.4.0"
 description = "Framework for enabling AI agents to perform complex, multi-step work tasks"
 readme = "README.md"
 requires-python = ">=3.11"