claude-dev-env 1.7.0 → 1.8.1

package/hooks/blocking/prompt-workflow-stop-guard.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Stop hook gate for prompt-workflow leakage and deterministic audit coverage."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from prompt_workflow_gate_core import (
+    find_ambiguous_scope_terms,
+    has_debug_intent,
+    has_checklist_container,
+    has_internal_object_leak,
+    is_prompt_workflow_response,
+    missing_context_control_signals,
+    missing_checklist_rows,
+    missing_scope_anchors,
+)
+
+
+def _extract_user_context(hook_input: dict) -> str:
+    candidates = (
+        "last_user_message",
+        "user_message",
+        "user_prompt",
+        "prompt",
+        "input",
+    )
+    for key in candidates:
+        value = hook_input.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return ""
+
+
+def _build_block(reason: str) -> dict:
+    return {
+        "decision": "block",
+        "reason": reason,
+    }
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    assistant_message = str(hook_input.get("last_assistant_message", ""))
+    if not assistant_message.strip():
+        sys.exit(0)
+
+    user_context = _extract_user_context(hook_input)
+    debug_requested = has_debug_intent(user_context)
+
+    if has_internal_object_leak(assistant_message) and not debug_requested:
+        print(
+            json.dumps(
+                _build_block(
+                    "PROMPT-WORKFLOW GATE: Raw internal refinement object leakage detected. "
+                    "Return sanitized user-facing output unless explicit debug intent is present."
+                )
+            )
+        )
+        sys.exit(0)
+
+    if is_prompt_workflow_response(assistant_message):
+        if not has_checklist_container(assistant_message):
+            print(
+                json.dumps(
+                    _build_block(
+                        "PROMPT-WORKFLOW GATE: Deterministic checklist container missing. "
+                        "Include `checklist_results` with all required rows."
+                    )
+                )
+            )
+            sys.exit(0)
+
+        missing_rows = missing_checklist_rows(assistant_message)
+        if missing_rows:
+            print(
+                json.dumps(
+                    _build_block(
+                        "PROMPT-WORKFLOW GATE: Deterministic checklist rows missing: "
+                        + ", ".join(missing_rows)
+                    )
+                )
+            )
+            sys.exit(0)
+
+        missing_anchors = missing_scope_anchors(assistant_message)
+        if missing_anchors:
+            print(
+                json.dumps(
+                    _build_block(
+                        "PROMPT-WORKFLOW GATE: Required scope anchors missing: "
+                        + ", ".join(missing_anchors)
+                    )
+                )
+            )
+            sys.exit(0)
+
+        missing_context_signals = missing_context_control_signals(assistant_message)
+        if missing_context_signals:
+            print(
+                json.dumps(
+                    _build_block(
+                        "PROMPT-WORKFLOW GATE: Runtime context-control signals missing: "
+                        + ", ".join(missing_context_signals)
+                    )
+                )
+            )
+            sys.exit(0)
+
+        ambiguous_terms = find_ambiguous_scope_terms(assistant_message)
+        if ambiguous_terms:
+            print(
+                json.dumps(
+                    _build_block(
+                        "PROMPT-WORKFLOW GATE: Ambiguous scope phrasing detected: "
+                        + ", ".join(ambiguous_terms)
+                    )
+                )
+            )
+            sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/prompt_workflow_gate_core.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Shared deterministic checks for prompt workflow hooks."""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+REQUIRED_SCOPE_ANCHORS: tuple[str, ...] = (
+    "target_local_roots",
+    "target_canonical_roots",
+    "target_file_globs",
+    "comparison_basis",
+    "completion_boundary",
+)
+
+REQUIRED_CHECKLIST_ROWS: tuple[str, ...] = (
+    "structured_scoped_instructions",
+    "sequential_steps_present",
+    "positive_framing",
+    "acceptance_criteria_defined",
+    "safety_reversibility_language",
+    "no_destructive_shortcuts_guidance",
+    "concrete_output_contract",
+    "scope_boundary_present",
+    "explicit_scope_anchors_present",
+    "all_instructions_artifact_bound",
+    "no_ambiguous_scope_terms",
+    "completion_boundary_measurable",
+    "citation_grounding_policy_present",
+    "source_priority_rules_present",
+)
+
+REQUIRED_CONTEXT_CONTROL_SIGNALS: tuple[str, ...] = (
+    "base_minimal_instruction_layer: true",
+    "on_demand_skill_loading: true",
+)
+
+AMBIGUOUS_SCOPE_TERMS: tuple[str, ...] = (
+    "this session",
+    "current files",
+    "here",
+    "above",
+    "as needed",
+)
+
+INTERNAL_OBJECT_MARKERS: tuple[str, ...] = (
+    '"pipeline_mode": "internal_section_refinement_with_final_audit"',
+    '"scope_block": {',
+    '"required_sections": [',
+    '"section_output_contract": {',
+    '"merge_output_contract": {',
+    '"audit_output_contract": {',
+)
+
+EXPLICIT_EXECUTION_MARKERS: tuple[str, ...] = (
+    "/agent-prompt",
+    "execution_intent: explicit",
+    "execution_intent_explicit: true",
+    "explicit execution intent",
+    "explicit delegation intent",
+)
+
+PROMPT_WORKFLOW_RESPONSE_MARKERS: tuple[str, ...] = (
+    "checklist_results",
+    "overall_status",
+    "scope anchors",
+    "target_local_roots",
+    "target_canonical_roots",
+    "target_file_globs",
+    "comparison_basis",
+    "completion_boundary",
+)
+
+DEBUG_INTENT_MARKERS: tuple[str, ...] = (
+    "debug",
+    "show internal",
+    "raw internal object",
+    "pipeline object",
+)
+
+
+def _contains_any_marker(text: str, markers: Iterable[str]) -> bool:
+    lower_text = text.lower()
+    return any(marker.lower() in lower_text for marker in markers)
+
+
+def has_explicit_execution_intent(text: str) -> bool:
+    return _contains_any_marker(text, EXPLICIT_EXECUTION_MARKERS)
+
+
+def has_structured_execution_intent(tool_input: object) -> bool:
+    if not isinstance(tool_input, dict):
+        return False
+
+    explicit_flag = tool_input.get("execution_intent_explicit")
+    if isinstance(explicit_flag, bool):
+        return explicit_flag
+
+    intent_value = tool_input.get("execution_intent")
+    if isinstance(intent_value, str):
+        normalized = intent_value.strip().lower()
+        return normalized in {"explicit", "execute", "delegation", "delegate"}
+    if isinstance(intent_value, bool):
+        return intent_value
+
+    metadata = tool_input.get("metadata")
+    if isinstance(metadata, dict):
+        metadata_intent = metadata.get("execution_intent")
+        if isinstance(metadata_intent, str):
+            return metadata_intent.strip().lower() in {"explicit", "execute", "delegate"}
+        if isinstance(metadata_intent, bool):
+            return metadata_intent
+
+    return False
+
+
+def has_debug_intent(text: str) -> bool:
+    return _contains_any_marker(text, DEBUG_INTENT_MARKERS)
+
+
+def has_internal_object_leak(text: str) -> bool:
+    return _contains_any_marker(text, INTERNAL_OBJECT_MARKERS)
+
+
+def missing_scope_anchors(text: str) -> list[str]:
+    return [anchor for anchor in REQUIRED_SCOPE_ANCHORS if anchor not in text]
+
+
+def find_ambiguous_scope_terms(text: str) -> list[str]:
+    if "scope" not in text.lower():
+        return []
+    matches: list[str] = []
+    lower_text = text.lower()
+    for term in AMBIGUOUS_SCOPE_TERMS:
+        if re.search(rf"\b{re.escape(term)}\b", lower_text):
+            matches.append(term)
+    return matches
+
+
+def has_checklist_container(text: str) -> bool:
+    lower_text = text.lower()
+    return "checklist_results" in lower_text or "checklist:" in lower_text
+
+
+def missing_checklist_rows(text: str) -> list[str]:
+    return [row for row in REQUIRED_CHECKLIST_ROWS if row not in text]
+
+
+def is_prompt_workflow_response(text: str) -> bool:
+    lower_text = text.lower()
+    matched_markers = [
+        marker for marker in PROMPT_WORKFLOW_RESPONSE_MARKERS if marker in lower_text
+    ]
+    return len(matched_markers) >= 2
+
+
+def missing_context_control_signals(text: str) -> list[str]:
+    return [
+        signal for signal in REQUIRED_CONTEXT_CONTROL_SIGNALS if signal not in text.lower()
+    ]

package/hooks/blocking/test_agent_execution_intent_gate.py

@@ -0,0 +1,106 @@
+"""Tests for agent-execution-intent-gate hook."""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).parent / "agent-execution-intent-gate.py"
+
+
+def _run_hook(payload: dict) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def test_denies_task_without_explicit_intent_marker() -> None:
+    payload = {
+        "tool_name": "Task",
+        "tool_input": {"prompt": "run the workflow", "description": "delegate"},
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "structured execution intent signal" in response["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_denies_phrase_marker_without_structured_intent_contract() -> None:
+    payload = {
+        "tool_name": "Task",
+        "tool_input": {
+            "prompt": "execution_intent: explicit and delegate now",
+            "description": "explicit delegation intent",
+        },
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "Missing structured execution intent signal" in response["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_denies_when_scope_anchors_missing() -> None:
+    payload = {
+        "tool_name": "Agent",
+        "tool_input": {
+            "execution_intent": "explicit",
+            "prompt": "target_local_roots only",
+            "description": "delegate",
+        },
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "Scope anchors missing" in response["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_allows_when_intent_and_scope_anchors_present() -> None:
+    payload = {
+        "tool_name": "Task",
+        "tool_input": {
+            "execution_intent_explicit": True,
+            "description": "delegate",
+            "prompt": (
+                "target_local_roots\n"
+                "target_canonical_roots\n"
+                "target_file_globs\n"
+                "comparison_basis\n"
+                "completion_boundary\n"
+            ),
+        },
+    }
+    result = _run_hook(payload)
+    assert result.stdout.strip() == ""
+
+
+def test_text_intent_fallback_is_logged_and_allowed_when_enabled() -> None:
+    payload = {
+        "tool_name": "Task",
+        "tool_input": {
+            "description": "delegate now",
+            "prompt": (
+                "execution_intent: explicit\n"
+                "target_local_roots\n"
+                "target_canonical_roots\n"
+                "target_file_globs\n"
+                "comparison_basis\n"
+                "completion_boundary\n"
+            ),
+        },
+    }
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env={**os.environ, "PROMPT_WORKFLOW_ALLOW_TEXT_INTENT_FALLBACK": "1"},
+    )
+    assert result.stdout.strip() == ""
+    assert "compatibility text-intent fallback used" in result.stderr

package/hooks/blocking/test_context_control_policy_files.py

@@ -0,0 +1,27 @@
+"""Validation fixtures for context-control policy artifacts."""
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+RULE_PATH = ROOT / "rules" / "prompt-workflow-context-controls.md"
+HOOK_SPEC_PATH = ROOT / "hooks" / "HOOK_SPECS_PROMPT_WORKFLOW.md"
+
+
+def test_context_control_rule_exists_with_required_sections() -> None:
+    text = RULE_PATH.read_text(encoding="utf-8")
+    assert "Base Minimal Instruction Layer" in text
+    assert "On-Demand Skill Loading" in text
+    assert "Compaction and Caching Strategy" in text
+    assert "Runtime Enforcement Signals" in text
+    assert "base_minimal_instruction_layer: true" in text
+    assert "on_demand_skill_loading: true" in text
+
+
+def test_hook_spec_exists_with_required_gates() -> None:
+    text = HOOK_SPEC_PATH.read_text(encoding="utf-8")
+    assert "Execution Intent (PreToolUse Task/Agent)" in text
+    assert "Leakage + Checklist + Scope (Stop)" in text
+    assert "Required Deterministic Checklist Rows" in text
+    assert "structured execution intent contract" in text
+    assert "Runtime Context-Control Signals" in text

package/hooks/blocking/test_prompt_workflow_gate_core.py

@@ -0,0 +1,68 @@
+"""Unit tests for shared prompt workflow gate logic."""
+
+from prompt_workflow_gate_core import (
+    find_ambiguous_scope_terms,
+    has_checklist_container,
+    has_explicit_execution_intent,
+    has_structured_execution_intent,
+    has_internal_object_leak,
+    is_prompt_workflow_response,
+    missing_context_control_signals,
+    missing_checklist_rows,
+    missing_scope_anchors,
+)
+
+
+def test_execution_intent_marker_detected() -> None:
+    assert has_explicit_execution_intent("execution_intent: explicit")
+
+
+def test_structured_execution_intent_detected_from_contract_field() -> None:
+    assert has_structured_execution_intent({"execution_intent": "explicit"})
+
+
+def test_structured_execution_intent_detected_from_boolean_flag() -> None:
+    assert has_structured_execution_intent({"execution_intent_explicit": True})
+
+
+def test_internal_object_leak_detected() -> None:
+    text = '{"pipeline_mode": "internal_section_refinement_with_final_audit"}'
+    assert has_internal_object_leak(text)
+
+
+def test_missing_scope_anchors_returns_expected_rows() -> None:
+    text = "target_local_roots only."
+    missing = missing_scope_anchors(text)
+    assert "target_canonical_roots" in missing
+    assert "completion_boundary" in missing
+
+
+def test_missing_checklist_rows_detected() -> None:
+    text = "checklist_results: structured_scoped_instructions only"
+    missing = missing_checklist_rows(text)
+    assert "completion_boundary_measurable" in missing
+
+
+def test_checklist_container_detection() -> None:
+    assert has_checklist_container("checklist_results:\n- structured_scoped_instructions")
+
+
+def test_prompt_workflow_response_detection() -> None:
+    message = (
+        "overall_status: pass\n"
+        "target_local_roots: /repo\n"
+        "comparison_basis: current behavior vs deterministic guarantees\n"
+    )
+    assert is_prompt_workflow_response(message)
+
+
+def test_missing_context_control_signals_detected() -> None:
+    missing = missing_context_control_signals("base_minimal_instruction_layer: true")
+    assert "on_demand_skill_loading: true" in missing
+
+
+def test_ambiguous_scope_terms_detected() -> None:
+    text = "Scope applies to this session and current files."
+    terms = find_ambiguous_scope_terms(text)
+    assert "this session" in terms
+    assert "current files" in terms

package/hooks/blocking/test_prompt_workflow_stop_guard.py

@@ -0,0 +1,144 @@
+"""Tests for prompt-workflow-stop-guard hook."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).parent / "prompt-workflow-stop-guard.py"
+
+
+def _run_hook(payload: dict) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def _full_checklist_rows() -> str:
+    return (
+        "checklist_results:\n"
+        "- structured_scoped_instructions\n"
+        "- sequential_steps_present\n"
+        "- positive_framing\n"
+        "- acceptance_criteria_defined\n"
+        "- safety_reversibility_language\n"
+        "- no_destructive_shortcuts_guidance\n"
+        "- concrete_output_contract\n"
+        "- scope_boundary_present\n"
+        "- explicit_scope_anchors_present\n"
+        "- all_instructions_artifact_bound\n"
+        "- no_ambiguous_scope_terms\n"
+        "- completion_boundary_measurable\n"
+        "- citation_grounding_policy_present\n"
+        "- source_priority_rules_present\n"
+    )
+
+
+def test_blocks_internal_object_leak_without_debug_intent() -> None:
+    payload = {
+        "last_assistant_message": '{"pipeline_mode": "internal_section_refinement_with_final_audit"}',
+        "last_user_message": "just return the final prompt",
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+    assert "Raw internal refinement object leakage" in response["reason"]
+
+
+def test_allows_internal_object_with_debug_intent() -> None:
+    payload = {
+        "last_assistant_message": '{"pipeline_mode": "internal_section_refinement_with_final_audit"}',
+        "last_user_message": "debug: show internal pipeline object",
+    }
+    result = _run_hook(payload)
+    assert result.stdout.strip() == ""
+
+
+def test_blocks_missing_checklist_rows() -> None:
+    payload = {
+        "last_assistant_message": "overall_status: pass\nchecklist_results: structured_scoped_instructions",
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+    assert "Deterministic checklist rows missing" in response["reason"]
+
+
+def test_blocks_missing_checklist_container_for_prompt_workflow_output() -> None:
+    payload = {
+        "last_assistant_message": (
+            "overall_status: pass\n"
+            "target_local_roots\n"
+            "target_canonical_roots\n"
+            "target_file_globs\n"
+            "comparison_basis\n"
+            "completion_boundary\n"
+            "base_minimal_instruction_layer: true\n"
+            "on_demand_skill_loading: true\n"
+        ),
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+    assert "Deterministic checklist container missing" in response["reason"]
+
+
+def test_blocks_missing_context_control_signals() -> None:
+    payload = {
+        "last_assistant_message": (
+            "overall_status: pass\n"
+            + _full_checklist_rows()
+            + "target_local_roots\n"
+            + "target_canonical_roots\n"
+            + "target_file_globs\n"
+            + "comparison_basis\n"
+            + "completion_boundary\n"
+            + "base_minimal_instruction_layer: true\n"
+        ),
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+    assert "Runtime context-control signals missing" in response["reason"]
+    assert "on_demand_skill_loading: true" in response["reason"]
+
+
+def test_blocks_ambiguous_scope_phrasing() -> None:
+    payload = {
+        "last_assistant_message": (
+            "overall_status: pass\n"
+            + _full_checklist_rows()
+            + "scope block includes target_local_roots target_canonical_roots "
+            + "target_file_globs comparison_basis completion_boundary "
+            + "base_minimal_instruction_layer: true\n"
+            + "on_demand_skill_loading: true\n"
+            + "and applies to this session."
+        ),
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+    assert "Ambiguous scope phrasing detected" in response["reason"]
+
+
+def test_allows_fully_structured_prompt_workflow_output() -> None:
+    payload = {
+        "last_assistant_message": (
+            "overall_status: pass\n"
+            + _full_checklist_rows()
+            + "target_local_roots\n"
+            + "target_canonical_roots\n"
+            + "target_file_globs\n"
+            + "comparison_basis\n"
+            + "completion_boundary\n"
+            + "base_minimal_instruction_layer: true\n"
+            + "on_demand_skill_loading: true\n"
+        ),
+    }
+    result = _run_hook(payload)
+    assert result.stdout.strip() == ""

package/hooks/hooks.json

@@ -94,6 +94,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/parallel-task-blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/agent-execution-intent-gate.py",
+            "timeout": 10
           }
         ]
       },
@@ -150,6 +155,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/hedging-language-blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/prompt-workflow-stop-guard.py",
+            "timeout": 10
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.7.0",
+    "version": "1.8.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -15,11 +15,6 @@
         "skills/",
         "hooks/"
     ],
-    "dependencies": {
-        "claude-journal": "^1.3.0",
-        "claude-deep-research": "^1.0.0",
-        "claude-prompt-tools": "^1.0.0"
-    },
     "keywords": [
         "claude-code",
         "plugin",