Plan and document policy system changes #56
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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
nhorton
commented
Jan 16, 2026
nhorton
commented
Jan 16, 2026
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
- 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
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 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
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 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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Design docs for next-generation policy system with:
Key changes from current system: