deepwork 0.1.0__py3-none-any.whl

deepwork/hooks/evaluate_policies.py

@@ -0,0 +1,159 @@
+"""
+Policy evaluation module for DeepWork hooks.
+
+This module is called by the policy_stop_hook.sh script to evaluate which policies
+should fire based on changed files and conversation context.
+
+Usage:
+    python -m deepwork.hooks.evaluate_policies \
+        --policy-file .deepwork.policy.yml \
+        --changed-files "file1.py\nfile2.py"
+
+The conversation context is read from stdin and checked for <promise> tags
+that indicate policies have already been addressed.
+
+Output is JSON suitable for Claude Code Stop hooks:
+    {"decision": "block", "reason": "..."}  # Block stop, policies need attention
+    {}  # No policies fired, allow stop
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from deepwork.core.policy_parser import (
+    PolicyParseError,
+    evaluate_policies,
+    parse_policy_file,
+)
+
+
+def extract_promise_tags(text: str) -> set[str]:
+    """
+    Extract policy names from <promise> tags in text.
+
+    Supported format:
+    - <promise>✓ Policy Name</promise>
+
+    Args:
+        text: Text to search for promise tags
+
+    Returns:
+        Set of policy names that have been promised/addressed
+    """
+    # Match <promise>✓ Policy Name</promise> and extract the policy name
+    pattern = r"<promise>✓\s*([^<]+)</promise>"
+    matches = re.findall(pattern, text, re.IGNORECASE | re.DOTALL)
+    return {m.strip() for m in matches}
+
+
+def format_policy_message(policies: list) -> str:
+    """
+    Format triggered policies into a message for the agent.
+
+    Args:
+        policies: List of Policy objects that fired
+
+    Returns:
+        Formatted message with all policy instructions
+    """
+    lines = ["## DeepWork Policies Triggered", ""]
+    lines.append(
+        "Comply with the following policies. "
+        "To mark a policy as addressed, include `<promise>✓ Policy Name</promise>` "
+        "in your response (replace Policy Name with the actual policy name)."
+    )
+    lines.append("")
+
+    for policy in policies:
+        lines.append(f"### Policy: {policy.name}")
+        lines.append("")
+        lines.append(policy.instructions.strip())
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    """Main entry point for policy evaluation CLI."""
+    parser = argparse.ArgumentParser(
+        description="Evaluate DeepWork policies based on changed files"
+    )
+    parser.add_argument(
+        "--policy-file",
+        type=str,
+        required=True,
+        help="Path to .deepwork.policy.yml file",
+    )
+    parser.add_argument(
+        "--changed-files",
+        type=str,
+        required=True,
+        help="Newline-separated list of changed files",
+    )
+
+    args = parser.parse_args()
+
+    # Parse changed files (newline-separated)
+    changed_files = [f.strip() for f in args.changed_files.split("\n") if f.strip()]
+
+    if not changed_files:
+        # No files changed, nothing to evaluate
+        print("{}")
+        return
+
+    # Check if policy file exists
+    policy_path = Path(args.policy_file)
+    if not policy_path.exists():
+        # No policy file, nothing to evaluate
+        print("{}")
+        return
+
+    # Read conversation context from stdin (if available)
+    conversation_context = ""
+    if not sys.stdin.isatty():
+        try:
+            conversation_context = sys.stdin.read()
+        except Exception:
+            pass
+
+    # Extract promise tags from conversation
+    promised_policies = extract_promise_tags(conversation_context)
+
+    # Parse and evaluate policies
+    try:
+        policies = parse_policy_file(policy_path)
+    except PolicyParseError as e:
+        # Log error to stderr, return empty result
+        print(f"Error parsing policy file: {e}", file=sys.stderr)
+        print("{}")
+        return
+
+    if not policies:
+        # No policies defined
+        print("{}")
+        return
+
+    # Evaluate which policies fire
+    fired_policies = evaluate_policies(policies, changed_files, promised_policies)
+
+    if not fired_policies:
+        # No policies fired
+        print("{}")
+        return
+
+    # Format output for Claude Code Stop hooks
+    # Use "decision": "block" to prevent Claude from stopping
+    message = format_policy_message(fired_policies)
+    result = {
+        "decision": "block",
+        "reason": message,
+    }
+
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

deepwork/schemas/__init__.py

@@ -0,0 +1 @@
+"""Schema definitions and validation."""

deepwork/schemas/job_schema.py

@@ -0,0 +1,212 @@
+"""JSON Schema definition for job definitions."""
+
+from typing import Any
+
+# Supported lifecycle hook events (generic names, mapped to platform-specific by adapters)
+# These values must match CommandLifecycleHook enum in adapters.py
+LIFECYCLE_HOOK_EVENTS = ["after_agent", "before_tool", "before_prompt"]
+
+# Schema definition for a single hook action (prompt, prompt_file, or script)
+HOOK_ACTION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "oneOf": [
+        {
+            "required": ["prompt"],
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Inline prompt for validation/action",
+                },
+            },
+            "additionalProperties": False,
+        },
+        {
+            "required": ["prompt_file"],
+            "properties": {
+                "prompt_file": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Path to prompt file (relative to job directory)",
+                },
+            },
+            "additionalProperties": False,
+        },
+        {
+            "required": ["script"],
+            "properties": {
+                "script": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Path to shell script (relative to job directory)",
+                },
+            },
+            "additionalProperties": False,
+        },
+    ],
+}
+
+# JSON Schema for job.yml files
+JOB_SCHEMA: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["name", "version", "summary", "steps"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "Job name (lowercase letters, numbers, underscores, must start with letter)",
+        },
+        "version": {
+            "type": "string",
+            "pattern": r"^\d+\.\d+\.\d+$",
+            "description": "Semantic version (e.g., 1.0.0)",
+        },
+        "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "description": "Brief one-line summary of what this job accomplishes",
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Detailed multi-line description of the job's purpose, process, and goals",
+        },
+        "changelog": {
+            "type": "array",
+            "description": "Version history and changes to the job",
+            "items": {
+                "type": "object",
+                "required": ["version", "changes"],
+                "properties": {
+                    "version": {
+                        "type": "string",
+                        "pattern": r"^\d+\.\d+\.\d+$",
+                        "description": "Version number for this change",
+                    },
+                    "changes": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Description of changes made in this version",
+                    },
+                },
+                "additionalProperties": False,
+            },
+        },
+        "steps": {
+            "type": "array",
+            "minItems": 1,
+            "description": "List of steps in the job",
+            "items": {
+                "type": "object",
+                "required": ["id", "name", "description", "instructions_file", "outputs"],
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9_]*$",
+                        "description": "Step ID (unique within job)",
+                    },
+                    "name": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Human-readable step name",
+                    },
+                    "description": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Step description",
+                    },
+                    "instructions_file": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Path to instructions file (relative to job directory)",
+                    },
+                    "inputs": {
+                        "type": "array",
+                        "description": "List of inputs (user parameters or files from previous steps)",
+                        "items": {
+                            "type": "object",
+                            "oneOf": [
+                                {
+                                    "required": ["name", "description"],
+                                    "properties": {
+                                        "name": {
+                                            "type": "string",
+                                            "description": "Input parameter name",
+                                        },
+                                        "description": {
+                                            "type": "string",
+                                            "description": "Input parameter description",
+                                        },
+                                    },
+                                    "additionalProperties": False,
+                                },
+                                {
+                                    "required": ["file", "from_step"],
+                                    "properties": {
+                                        "file": {
+                                            "type": "string",
+                                            "description": "File name from previous step",
+                                        },
+                                        "from_step": {
+                                            "type": "string",
+                                            "description": "Step ID that produces this file",
+                                        },
+                                    },
+                                    "additionalProperties": False,
+                                },
+                            ],
+                        },
+                    },
+                    "outputs": {
+                        "type": "array",
+                        "description": "List of output files/directories",
+                        "items": {
+                            "type": "string",
+                            "minLength": 1,
+                        },
+                    },
+                    "dependencies": {
+                        "type": "array",
+                        "description": "List of step IDs this step depends on",
+                        "items": {
+                            "type": "string",
+                        },
+                        "default": [],
+                    },
+                    "hooks": {
+                        "type": "object",
+                        "description": "Lifecycle hooks for this step, keyed by event type",
+                        "properties": {
+                            "after_agent": {
+                                "type": "array",
+                                "description": "Hooks triggered after the agent finishes (quality validation)",
+                                "items": HOOK_ACTION_SCHEMA,
+                            },
+                            "before_tool": {
+                                "type": "array",
+                                "description": "Hooks triggered before a tool is used",
+                                "items": HOOK_ACTION_SCHEMA,
+                            },
+                            "before_prompt": {
+                                "type": "array",
+                                "description": "Hooks triggered when user submits a prompt",
+                                "items": HOOK_ACTION_SCHEMA,
+                            },
+                        },
+                        "additionalProperties": False,
+                    },
+                    # DEPRECATED: Use hooks.after_agent instead
+                    "stop_hooks": {
+                        "type": "array",
+                        "description": "DEPRECATED: Use hooks.after_agent instead. Stop hooks for quality validation loops.",
+                        "items": HOOK_ACTION_SCHEMA,
+                    },
+                },
+                "additionalProperties": False,
+            },
+        },
+    },
+    "additionalProperties": False,
+}

deepwork/schemas/policy_schema.py

@@ -0,0 +1,68 @@
+"""JSON Schema definition for policy definitions."""
+
+from typing import Any
+
+# JSON Schema for .deepwork.policy.yml files
+# Policies are defined as an array of policy objects
+POLICY_SCHEMA: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "array",
+    "description": "List of policies that trigger based on file changes",
+    "items": {
+        "type": "object",
+        "required": ["name", "trigger"],
+        "properties": {
+            "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Friendly name for the policy",
+            },
+            "trigger": {
+                "oneOf": [
+                    {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Glob pattern for files that trigger this policy",
+                    },
+                    {
+                        "type": "array",
+                        "items": {"type": "string", "minLength": 1},
+                        "minItems": 1,
+                        "description": "List of glob patterns for files that trigger this policy",
+                    },
+                ],
+                "description": "Glob pattern(s) for files that, if changed, should trigger this policy",
+            },
+            "safety": {
+                "oneOf": [
+                    {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Glob pattern for safety files",
+                    },
+                    {
+                        "type": "array",
+                        "items": {"type": "string", "minLength": 1},
+                        "description": "List of glob patterns for safety files",
+                    },
+                ],
+                "description": "Glob pattern(s) for files that, if also changed, mean the policy doesn't need to trigger",
+            },
+            "instructions": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Instructions to give the agent when this policy triggers",
+            },
+            "instructions_file": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Path to a file containing instructions (alternative to inline instructions)",
+            },
+        },
+        "oneOf": [
+            {"required": ["instructions"]},
+            {"required": ["instructions_file"]},
+        ],
+        "additionalProperties": False,
+    },
+}

deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -0,0 +1,102 @@
+name: deepwork_jobs
+version: "0.1.0"
+summary: "DeepWork job management commands"
+description: |
+  Core commands for managing DeepWork jobs. These commands help you define new multi-step
+  workflows and refine existing ones.
+
+  The `define` command guides you through an interactive process to create a new job by
+  asking detailed questions about your workflow, understanding each step's inputs and outputs,
+  and generating all necessary files.
+
+  The `refine` command helps you modify existing jobs safely by understanding what you want
+  to change, validating the impact, and ensuring consistency across your workflow.
+
+changelog:
+  - version: "0.1.0"
+    changes: "Initial version"
+
+steps:
+  - id: define
+    name: "Define Job Specification"
+    description: "Create the job.yml specification file by understanding workflow requirements"
+    instructions_file: steps/define.md
+    inputs:
+      - name: job_purpose
+        description: "What complex task or workflow are you trying to accomplish?"
+    outputs:
+      - job.yml
+    dependencies: []
+    hooks:
+      after_agent:
+        - prompt: |
+            Verify the job.yml output meets ALL quality criteria before completing:
+
+            1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
+            2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
+            3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
+            4. **Concise Summary**: Is the summary under 200 characters and descriptive?
+            5. **Rich Description**: Does the description provide enough context for future refinement?
+            6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
+            7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
+
+            If ANY criterion is not met, continue working to address it.
+            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+
+  - id: implement
+    name: "Implement Job Steps"
+    description: "Generate instruction files for each step based on the job.yml specification"
+    instructions_file: steps/implement.md
+    inputs:
+      - file: job.yml
+        from_step: define
+    outputs:
+      - implementation_summary.md
+    dependencies:
+      - define
+    hooks:
+      after_agent:
+        - prompt: |
+            Verify the implementation meets ALL quality criteria before completing:
+
+            1. **Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?
+            2. **Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?
+            3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
+            4. **Output Examples**: Does each instruction file show what good output looks like?
+            5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
+            6. **Sync Complete**: Has `deepwork sync` been run successfully?
+            7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
+            8. **Summary Created**: Has `implementation_summary.md` been created?
+            9. **Policies Considered**: Have you thought about whether policies would benefit this job?
+               - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
+               - Not every job needs policies - only suggest when genuinely helpful.
+
+            If ANY criterion is not met, continue working to address it.
+            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+
+  - id: refine
+    name: "Refine Existing Job"
+    description: "Modify an existing job definition"
+    instructions_file: steps/refine.md
+    inputs:
+      - name: job_name
+        description: "Name of the job to refine"
+    outputs:
+      - job.yml
+    dependencies: []
+    hooks:
+      after_agent:
+        - prompt: |
+            Verify the refinement meets ALL quality criteria before completing:
+
+            1. **Job Consistency**: Do the changes maintain overall job consistency?
+            2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)?
+            3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)?
+            4. **Changelog Updated**: Is the changelog updated with a description of changes?
+            5. **User Understanding**: Does the user understand the impact of the changes?
+            6. **Breaking Changes**: Were any breaking changes clearly communicated?
+            7. **Files Updated**: Are all affected files (job.yml, step files) updated?
+            8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands?
+
+            If ANY criterion is not met, continue working to address it.
+            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.