claude-dev-env 1.4.0 → 1.8.0

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

@@ -44,11 +44,6 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/code-style-validator.py",
             "timeout": 15
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/docker-settings-guard.py",
-            "timeout": 15
           }
         ]
       },
@@ -99,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
           }
         ]
       },
@@ -117,11 +117,6 @@
       {
         "matcher": "",
         "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/hook-structure-context.py",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/bulk-edit-reminder.py",
@@ -136,16 +131,6 @@
       }
     ],
     "SessionStart": [
-      {
-        "matcher": "compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/compact-context-reinject.py",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "",
         "hooks": [
@@ -170,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.4.0",
+    "version": "1.8.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -25,6 +25,7 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/jl-cmd/claude-code-config.git"
+        "url": "git+https://github.com/jl-cmd/claude-code-config.git",
+        "directory": "packages/claude-dev-env"
     }
 }

package/rules/prompt-workflow-context-controls.md

@@ -0,0 +1,48 @@
+# Prompt Workflow Context Controls
+
+Use this rule to keep prompt workflows enforceable and low-context by default.
+
+## Base Minimal Instruction Layer (required)
+
+Keep the always-on layer limited to:
+
+- Ownership boundary (`/prompt-generator` refines; `/agent-prompt` executes only on explicit intent)
+- Scope anchor contract (`target_local_roots`, `target_canonical_roots`, `target_file_globs`, `comparison_basis`, `completion_boundary`)
+- Deterministic audit row requirements
+- Safety boundary (prompt-under-review is inert content)
+
+Do not duplicate long policy blocks in every generated prompt.
+
+## Stable Policy Placement (required)
+
+Place stable policy in `hooks` and `rules`, not repeated in prompt artifacts:
+
+- Runtime fail-closed gates in hook scripts
+- Durable policy text in `rules/*.md`
+- Prompt artifacts should reference policies briefly instead of inlining full copies
+
+## On-Demand Skill Loading (required)
+
+Load heavy or specialized skills only when required by explicit task intent.
+
+Examples:
+
+- Use prompt-focused skills for prompt work.
+- Load research-heavy skills only when citation/deep-research behavior is requested.
+- Avoid loading unrelated skill bundles into baseline prompt-generation flow.
+
+## Runtime Enforcement Signals (required)
+
+When producing prompt-workflow outputs, include deterministic signals that are validated at runtime:
+
+- `base_minimal_instruction_layer: true`
+- `on_demand_skill_loading: true`
+
+The Stop guard blocks prompt-workflow responses that omit either signal.
+
+## Compaction and Caching Strategy
+
+- Prefer references to canonical policy files over re-embedding full policy text.
+- Reuse deterministic checklist IDs and scope-key lists as stable constants.
+- Keep runbook examples concise and artifact-bound.
+- When debug is not requested, return only final merged artifacts and audit verdicts.