deepwork 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

deepwork/hooks/rules_check.py

@@ -6,12 +6,15 @@ It uses the wrapper system for cross-platform compatibility.
 
 Rule files are loaded from .deepwork/rules/ directory as frontmatter markdown files.
 
-Usage (via shell wrapper):
-    claude_hook.sh deepwork.hooks.rules_check
-    gemini_hook.sh deepwork.hooks.rules_check
+Usage (via shell wrapper - recommended):
+    claude_hook.sh rules_check
+    gemini_hook.sh rules_check
 
-Or directly with platform environment variable:
-    DEEPWORK_HOOK_PLATFORM=claude python -m deepwork.hooks.rules_check
+Or directly via deepwork CLI:
+    deepwork hook rules_check
+
+Or with platform environment variable:
+    DEEPWORK_HOOK_PLATFORM=claude deepwork hook rules_check
 """
 
 from __future__ import annotations
@@ -199,7 +202,176 @@ def get_changed_files_default_tip() -> list[str]:
 
 
 def get_changed_files_prompt() -> list[str]:
-    """Get files changed since prompt was submitted."""
+    """Get files changed since prompt was submitted.
+
+    Returns files that changed since the prompt was submitted, including:
+    - Committed changes (compared to captured HEAD ref)
+    - Staged changes (not yet committed)
+    - Untracked files
+
+    This is used by trigger/safety, set, and pair mode rules to detect
+    file modifications during the agent response.
+    """
+    baseline_ref_path = Path(".deepwork/.last_head_ref")
+    changed_files: set[str] = set()
+
+    try:
+        # Stage all changes first
+        subprocess.run(["git", "add", "-A"], capture_output=True, check=False)
+
+        # If we have a captured HEAD ref, compare committed changes against it
+        if baseline_ref_path.exists():
+            baseline_ref = baseline_ref_path.read_text().strip()
+            if baseline_ref:
+                # Get files changed in commits since the baseline
+                result = subprocess.run(
+                    ["git", "diff", "--name-only", baseline_ref, "HEAD"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    committed_files = set(result.stdout.strip().split("\n"))
+                    changed_files.update(f for f in committed_files if f)
+
+        # Also get currently staged changes (in case not everything is committed)
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--cached"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.stdout.strip():
+            staged_files = set(result.stdout.strip().split("\n"))
+            changed_files.update(f for f in staged_files if f)
+
+        # Include untracked files
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.stdout.strip():
+            untracked_files = set(result.stdout.strip().split("\n"))
+            changed_files.update(f for f in untracked_files if f)
+
+        return sorted(changed_files)
+
+    except (subprocess.CalledProcessError, OSError):
+        return []
+
+
+def get_changed_files_for_mode(mode: str) -> list[str]:
+    """Get changed files for a specific compare_to mode."""
+    if mode == "base":
+        return get_changed_files_base()
+    elif mode == "default_tip":
+        return get_changed_files_default_tip()
+    elif mode == "prompt":
+        return get_changed_files_prompt()
+    else:
+        return get_changed_files_base()
+
+
+def get_created_files_base() -> list[str]:
+    """Get files created (added) relative to branch base."""
+    default_branch = get_default_branch()
+
+    try:
+        result = subprocess.run(
+            ["git", "merge-base", "HEAD", f"origin/{default_branch}"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        merge_base = result.stdout.strip()
+
+        subprocess.run(["git", "add", "-A"], capture_output=True, check=False)
+
+        # Get only added files (not modified) using --diff-filter=A
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=A", merge_base, "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        committed_added = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Staged new files that don't exist in merge_base
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=A", "--cached", merge_base],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        staged_added = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Untracked files are by definition "created"
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        untracked_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        all_created = committed_added | staged_added | untracked_files
+        return sorted([f for f in all_created if f])
+
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_created_files_default_tip() -> list[str]:
+    """Get files created compared to default branch tip."""
+    default_branch = get_default_branch()
+
+    try:
+        subprocess.run(["git", "add", "-A"], capture_output=True, check=False)
+
+        # Get only added files using --diff-filter=A
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=A", f"origin/{default_branch}..HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        committed_added = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        result = subprocess.run(
+            [
+                "git",
+                "diff",
+                "--name-only",
+                "--diff-filter=A",
+                "--cached",
+                f"origin/{default_branch}",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        staged_added = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Untracked files are by definition "created"
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        untracked_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        all_created = committed_added | staged_added | untracked_files
+        return sorted([f for f in all_created if f])
+
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_created_files_prompt() -> list[str]:
+    """Get files created since prompt was submitted."""
     baseline_path = Path(".deepwork/.last_work_tree")
 
     try:
@@ -214,28 +386,42 @@ def get_changed_files_prompt() -> list[str]:
         current_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
         current_files = {f for f in current_files if f}
 
+        # Untracked files
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        untracked_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+        untracked_files = {f for f in untracked_files if f}
+
+        all_current = current_files | untracked_files
+
         if baseline_path.exists():
             baseline_files = set(baseline_path.read_text().strip().split("\n"))
             baseline_files = {f for f in baseline_files if f}
-            new_files = current_files - baseline_files
-            return sorted(new_files)
+            # Created files are those that didn't exist at baseline
+            created_files = all_current - baseline_files
+            return sorted(created_files)
         else:
-            return sorted(current_files)
+            # No baseline means all current files are "new" to this prompt
+            return sorted(all_current)
 
     except (subprocess.CalledProcessError, OSError):
         return []
 
 
-def get_changed_files_for_mode(mode: str) -> list[str]:
-    """Get changed files for a specific compare_to mode."""
+def get_created_files_for_mode(mode: str) -> list[str]:
+    """Get created files for a specific compare_to mode."""
     if mode == "base":
-        return get_changed_files_base()
+        return get_created_files_base()
     elif mode == "default_tip":
-        return get_changed_files_default_tip()
+        return get_created_files_default_tip()
     elif mode == "prompt":
-        return get_changed_files_prompt()
+        return get_created_files_prompt()
     else:
-        return get_changed_files_base()
+        return get_created_files_base()
 
 
 def extract_promise_tags(text: str) -> set[str]:
@@ -399,13 +585,16 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
 
     for mode, mode_rules in rules_by_mode.items():
         changed_files = get_changed_files_for_mode(mode)
-        if not changed_files:
+        created_files = get_created_files_for_mode(mode)
+
+        # Skip if no changed or created files
+        if not changed_files and not created_files:
             continue
 
         baseline_ref = get_baseline_ref(mode)
 
         # Evaluate which rules fire
-        results = evaluate_rules(mode_rules, changed_files, promised_rules)
+        results = evaluate_rules(mode_rules, changed_files, promised_rules, created_files)
 
         for result in results:
             rule = result.rule
@@ -425,6 +614,26 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
             ):
                 continue
 
+            # For PROMPT rules, also skip if already QUEUED (already shown to agent).
+            # This prevents infinite loops when transcript is unavailable or promise
+            # tags haven't been written yet. The agent has already seen this rule.
+            if (
+                existing
+                and existing.status == QueueEntryStatus.QUEUED
+                and rule.action_type == ActionType.PROMPT
+            ):
+                continue
+
+            # For COMMAND rules with FAILED status, don't re-run the command.
+            # The agent has already seen the error. If they provide a promise,
+            # the after-loop logic will update the status to SKIPPED.
+            if (
+                existing
+                and existing.status == QueueEntryStatus.FAILED
+                and rule.action_type == ActionType.COMMAND
+            ):
+                continue
+
             # Create queue entry if new
             if not existing:
                 queue.create_entry(
@@ -458,10 +667,10 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
                             ),
                         )
                     else:
-                        # Command failed
-                        error_msg = format_command_errors(cmd_results)
-                        skip_hint = f"To skip, include `<promise>✓ {rule.name}</promise>` in your response.\n"
-                        command_errors.append(f"## {rule.name}\n{error_msg}{skip_hint}")
+                        # Command failed - format detailed error message
+                        error_msg = format_command_errors(cmd_results, rule_name=rule.name)
+                        skip_hint = f"\nTo skip, include `<promise>✓ {rule.name}</promise>` in your response."
+                        command_errors.append(f"{error_msg}{skip_hint}")
                         queue.update_status(
                             trigger_hash,
                             QueueEntryStatus.FAILED,
@@ -476,6 +685,26 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
                 # Collect for prompt output
                 prompt_results.append(result)
 
+    # Handle FAILED queue entries that have been promised
+    # (These rules weren't in results because evaluate_rules skips promised rules,
+    # but we need to update their queue status to SKIPPED)
+    if promised_rules:
+        promised_lower = {name.lower() for name in promised_rules}
+        for entry in queue.get_all_entries():
+            if (
+                entry.status == QueueEntryStatus.FAILED
+                and entry.rule_name.lower() in promised_lower
+            ):
+                queue.update_status(
+                    entry.trigger_hash,
+                    QueueEntryStatus.SKIPPED,
+                    ActionResult(
+                        type="command",
+                        output="Acknowledged via promise tag",
+                        exit_code=None,
+                    ),
+                )
+
     # Build response
     messages: list[str] = []
 
@@ -498,17 +727,33 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
 
 def main() -> None:
     """Entry point for the rules check hook."""
-    # Determine platform from environment
     platform_str = os.environ.get("DEEPWORK_HOOK_PLATFORM", "claude")
     try:
         platform = Platform(platform_str)
     except ValueError:
         platform = Platform.CLAUDE
 
-    # Run the hook with the wrapper
     exit_code = run_hook(rules_check_hook, platform)
     sys.exit(exit_code)
 
 
 if __name__ == "__main__":
-    main()
+    # Wrap entry point to catch early failures (e.g., import errors in wrapper.py)
+    try:
+        main()
+    except Exception as e:
+        # Last resort error handling - output JSON manually since wrapper may be broken
+        import json
+        import traceback
+
+        error_output = {
+            "decision": "block",
+            "reason": (
+                "## Hook Script Error\n\n"
+                f"Error type: {type(e).__name__}\n"
+                f"Error: {e}\n\n"
+                f"Traceback:\n```\n{traceback.format_exc()}\n```"
+            ),
+        }
+        print(json.dumps(error_output))
+        sys.exit(0)

deepwork/hooks/wrapper.py

@@ -321,6 +321,55 @@ def write_stdout(data: str) -> None:
     print(data)
 
 
+def format_hook_error(
+    error: Exception,
+    context: str = "",
+) -> dict[str, Any]:
+    """
+    Format an error into a blocking JSON response with detailed information.
+
+    This is used when the hook script itself fails, to provide useful
+    error information to the user instead of a generic "non-blocking status code" message.
+
+    Args:
+        error: The exception that occurred
+        context: Additional context about where the error occurred
+
+    Returns:
+        Dict with decision="block" and detailed error message
+    """
+    import traceback
+
+    error_type = type(error).__name__
+    error_msg = str(error)
+    tb = traceback.format_exc()
+
+    parts = ["## Hook Script Error", ""]
+    if context:
+        parts.append(f"Context: {context}")
+    parts.append(f"Error type: {error_type}")
+    parts.append(f"Error: {error_msg}")
+    parts.append("")
+    parts.append("Traceback:")
+    parts.append(f"```\n{tb}\n```")
+
+    return {
+        "decision": "block",
+        "reason": "\n".join(parts),
+    }
+
+
+def output_hook_error(error: Exception, context: str = "") -> None:
+    """
+    Output a hook error as JSON to stdout.
+
+    Use this in exception handlers to ensure the hook always outputs
+    valid JSON even when crashing.
+    """
+    error_dict = format_hook_error(error, context)
+    print(json.dumps(error_dict))
+
+
 def run_hook(
     hook_fn: Callable[[HookInput], HookOutput],
     platform: Platform,
@@ -340,24 +389,25 @@ def run_hook(
         platform: The platform calling this hook
 
     Returns:
-        Exit code (0 for success, 2 for blocking)
+        Exit code (0 for success)
     """
-    # Read and normalize input
-    raw_input = read_stdin()
-    hook_input = normalize_input(raw_input, platform)
-
-    # Call the hook
     try:
+        # Read and normalize input
+        raw_input = read_stdin()
+        hook_input = normalize_input(raw_input, platform)
+
+        # Call the hook
         hook_output = hook_fn(hook_input)
-    except Exception as e:
-        # On error, allow the action but log
-        print(f"Hook error: {e}", file=sys.stderr)
-        hook_output = HookOutput()
 
-    # Denormalize and write output
-    output_json = denormalize_output(hook_output, platform, hook_input.event)
-    write_stdout(output_json)
+        # Denormalize and write output
+        output_json = denormalize_output(hook_output, platform, hook_input.event)
+        write_stdout(output_json)
 
-    # Always return 0 when using JSON output format
-    # The decision field in the JSON controls blocking behavior
-    return 0
+        # Always return 0 when using JSON output format
+        # The decision field in the JSON controls blocking behavior
+        return 0
+
+    except Exception as e:
+        # On any error, output a proper JSON error response
+        output_hook_error(e, context=f"Running hook {hook_fn.__name__}")
+        return 0  # Return 0 so Claude Code processes our JSON output

deepwork/schemas/doc_spec_schema.py

@@ -0,0 +1,64 @@
+"""JSON Schema definition for doc specs (document type definitions)."""
+
+from typing import Any
+
+# Schema for a single quality criterion
+QUALITY_CRITERION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["name", "description"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Short name for the quality criterion",
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Detailed description of what this criterion requires",
+        },
+    },
+    "additionalProperties": False,
+}
+
+# Schema for doc spec frontmatter
+DOC_SPEC_FRONTMATTER_SCHEMA: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["name", "description", "quality_criteria"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable name for the document type",
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Description of this document type's purpose",
+        },
+        "path_patterns": {
+            "type": "array",
+            "description": "Glob patterns for where documents of this type should be stored",
+            "items": {
+                "type": "string",
+                "minLength": 1,
+            },
+        },
+        "target_audience": {
+            "type": "string",
+            "description": "Who this document is written for",
+        },
+        "frequency": {
+            "type": "string",
+            "description": "How often this document type is produced (e.g., 'Monthly', 'Per sprint')",
+        },
+        "quality_criteria": {
+            "type": "array",
+            "description": "Quality criteria that documents of this type must meet",
+            "minItems": 1,
+            "items": QUALITY_CRITERION_SCHEMA,
+        },
+    },
+    "additionalProperties": False,
+}

deepwork/schemas/job_schema.py

@@ -161,10 +161,32 @@ JOB_SCHEMA: dict[str, Any] = {
                     },
                     "outputs": {
                         "type": "array",
-                        "description": "List of output files/directories",
+                        "description": "List of output files/directories, optionally with document type references",
                         "items": {
-                            "type": "string",
-                            "minLength": 1,
+                            "oneOf": [
+                                {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "description": "Simple output file path (backward compatible)",
+                                },
+                                {
+                                    "type": "object",
+                                    "required": ["file"],
+                                    "properties": {
+                                        "file": {
+                                            "type": "string",
+                                            "minLength": 1,
+                                            "description": "Output file path",
+                                        },
+                                        "doc_spec": {
+                                            "type": "string",
+                                            "pattern": r"^\.deepwork/doc_specs/[a-z][a-z0-9_-]*\.md$",
+                                            "description": "Path to doc spec file",
+                                        },
+                                    },
+                                    "additionalProperties": False,
+                                },
+                            ],
                         },
                     },
                     "dependencies": {

deepwork/schemas/rules_schema.py

@@ -15,7 +15,7 @@ STRING_OR_ARRAY: dict[str, Any] = {
 RULES_FRONTMATTER_SCHEMA: dict[str, Any] = {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "type": "object",
-    "required": ["name"],
+    "required": ["name", "compare_to"],
     "properties": {
         "name": {
             "type": "string",
@@ -56,6 +56,11 @@ RULES_FRONTMATTER_SCHEMA: dict[str, Any] = {
             "additionalProperties": False,
             "description": "Directional file correspondence (trigger -> expects)",
         },
+        # Detection mode: created (fire when files are created matching patterns)
+        "created": {
+            **STRING_OR_ARRAY,
+            "description": "Glob pattern(s) for newly created files that trigger this rule",
+        },
         # Action type: command (default is prompt using markdown body)
         "action": {
             "type": "object",
@@ -80,24 +85,51 @@ RULES_FRONTMATTER_SCHEMA: dict[str, Any] = {
         "compare_to": {
             "type": "string",
             "enum": ["base", "default_tip", "prompt"],
-            "default": "base",
             "description": "Baseline for detecting file changes",
         },
     },
     "additionalProperties": False,
-    # Detection mode must be exactly one of: trigger, set, or pair
+    # Detection mode must be exactly one of: trigger, set, pair, or created
     "oneOf": [
         {
             "required": ["trigger"],
-            "not": {"anyOf": [{"required": ["set"]}, {"required": ["pair"]}]},
+            "not": {
+                "anyOf": [
+                    {"required": ["set"]},
+                    {"required": ["pair"]},
+                    {"required": ["created"]},
+                ]
+            },
         },
         {
             "required": ["set"],
-            "not": {"anyOf": [{"required": ["trigger"]}, {"required": ["pair"]}]},
+            "not": {
+                "anyOf": [
+                    {"required": ["trigger"]},
+                    {"required": ["pair"]},
+                    {"required": ["created"]},
+                ]
+            },
         },
         {
             "required": ["pair"],
-            "not": {"anyOf": [{"required": ["trigger"]}, {"required": ["set"]}]},
+            "not": {
+                "anyOf": [
+                    {"required": ["trigger"]},
+                    {"required": ["set"]},
+                    {"required": ["created"]},
+                ]
+            },
+        },
+        {
+            "required": ["created"],
+            "not": {
+                "anyOf": [
+                    {"required": ["trigger"]},
+                    {"required": ["set"]},
+                    {"required": ["pair"]},
+                ]
+            },
         },
     ],
 }