claude-dev-env 1.17.1 → 1.17.5

package/hooks/blocking/test_prompt_workflow_validate.py

@@ -0,0 +1,339 @@
+"""Tests for prompt_workflow_validate module (shared validator + CLI entry point)."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from prompt_workflow_validate import ValidationResult, validate_prompt_workflow
+
+VALIDATOR_MODULE_PATH = Path(__file__).parent / "prompt_workflow_validate.py"
+
+
+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"
+        "- reversible_action_and_safety_check_guidance\n"
+        "- concrete_output_contract\n"
+        "- scope_boundary_present\n"
+        "- explicit_scope_anchors_present\n"
+        "- all_instructions_artifact_bound\n"
+        "- scope_terms_explicit_and_anchored\n"
+        "- completion_boundary_measurable\n"
+        "- citation_grounding_policy_present\n"
+        "- source_priority_rules_present\n"
+        "- artifact_language_confidence\n"
+    )
+
+
+def _wrap_five_section_scaffold(inner_body: str) -> str:
+    has_instructions = "<instructions>" in inner_body
+    has_constraints = "<constraints>" in inner_body
+    instructions_section = (
+        "" if has_instructions else "<instructions>Test instructions sentence one.</instructions>\n"
+    )
+    constraints_section = (
+        "" if has_constraints else "<constraints>Test constraints sentence one.</constraints>\n"
+    )
+    return (
+        "<role>Test role sentence one.</role>\n"
+        "<background>Test background sentence one.</background>\n"
+        f"{instructions_section}"
+        f"{inner_body}\n"
+        f"{constraints_section}"
+        "<output_format>Test output format sentence one.</output_format>\n"
+    )
+
+
+def _build_prompt_workflow_message_with_fenced_xml(fenced_xml_body: str) -> str:
+    return (
+        "Audit: pass 15/15\n"
+        "```xml\n" + fenced_xml_body + "\n```\n"
+        "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"
+    )
+
+
+class TestValidatePromptWorkflowFunction:
+    """Tests that exercise the shared validate_prompt_workflow function directly."""
+
+    def test_allowed_complete_message_with_fenced_xml(self) -> None:
+        fenced_content = _wrap_five_section_scaffold(
+            "<instructions>Ensure all functions have explicit return types.</instructions>"
+        )
+        message = _build_prompt_workflow_message_with_fenced_xml(fenced_content)
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is True
+        assert validation_result.reasons == ()
+
+    def test_blocked_missing_context_control_lines(self) -> None:
+        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"
+        )
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is False
+        assert "missing_context_signals" in validation_result.reason_codes
+        assert any(
+            "context-control" in each_message
+            for each_message in validation_result.reason_messages
+        )
+
+    def test_allowed_empty_message(self) -> None:
+        validation_result = validate_prompt_workflow("")
+        assert validation_result.allowed is True
+
+    def test_allowed_non_workflow_message(self) -> None:
+        validation_result = validate_prompt_workflow("Just a regular response.")
+        assert validation_result.allowed is True
+
+    def test_blocked_internal_object_leak(self) -> None:
+        leak_message = (
+            '{"pipeline_mode": "internal_section_refinement_with_final_audit"}'
+        )
+        validation_result = validate_prompt_workflow(leak_message)
+        assert validation_result.allowed is False
+        assert "internal_object_leak" in validation_result.reason_codes
+
+    def test_allowed_internal_object_with_debug_context(self) -> None:
+        leak_message = (
+            '{"pipeline_mode": "internal_section_refinement_with_final_audit"}'
+        )
+        validation_result = validate_prompt_workflow(
+            leak_message,
+            user_context="debug: show internal pipeline object",
+        )
+        assert validation_result.allowed is True
+
+    def test_blocked_missing_checklist_rows(self) -> None:
+        message = (
+            "overall_status: pass\n"
+            "checklist_results: structured_scoped_instructions\n"
+            "target_local_roots\n"
+            "target_canonical_roots\n"
+            "target_file_globs\n"
+            "comparison_basis\n"
+            "completion_boundary\n"
+        )
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is False
+        assert "missing_checklist_rows" in validation_result.reason_codes
+
+    def test_blocked_negative_keywords_in_fenced_xml(self) -> None:
+        fenced_content = _wrap_five_section_scaffold(
+            "<instructions>Do not leave return types implicit.</instructions>"
+        )
+        message = _build_prompt_workflow_message_with_fenced_xml(fenced_content)
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is False
+        assert "negative_keywords_in_artifact" in validation_result.reason_codes
+
+    def test_blocked_ambiguous_scope(self) -> None:
+        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."
+        )
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is False
+        assert "ambiguous_scope" in validation_result.reason_codes
+
+    def test_reason_messages_property(self) -> None:
+        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"
+        )
+        validation_result = validate_prompt_workflow(message)
+        assert len(validation_result.reason_messages) == 1
+        assert len(validation_result.reason_codes) == 1
+
+    def test_blocked_missing_scope_anchors(self) -> None:
+        message = (
+            "overall_status: pass\n"
+            + _full_checklist_rows()
+            + "base_minimal_instruction_layer: true\n"
+            + "on_demand_skill_loading: true\n"
+        )
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is False
+        assert "missing_scope_anchors" in validation_result.reason_codes
+
+    def test_blocked_missing_xml_sections_in_fenced_artifact(self) -> None:
+        fenced_body = (
+            "<role>Test role sentence one.</role>\n"
+            "<instructions>Test instructions sentence one.</instructions>\n"
+            "<constraints>Test constraints sentence one.</constraints>\n"
+            "<output_format>Test output format sentence one.</output_format>\n"
+        )
+        message = _build_prompt_workflow_message_with_fenced_xml(fenced_body)
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is False
+        assert "missing_xml_sections" in validation_result.reason_codes
+        assert any(
+            "background" in each_message
+            for each_message in validation_result.reason_messages
+        )
+
+    def test_allows_positive_phrasing_inside_fenced_xml(self) -> None:
+        fenced_content = _wrap_five_section_scaffold(
+            "<instructions>Ensure all functions have explicit return types.</instructions>"
+        )
+        message = _build_prompt_workflow_message_with_fenced_xml(fenced_content)
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is True
+
+    def test_permits_negative_keywords_outside_fenced_xml(self) -> None:
+        fenced_inner = _wrap_five_section_scaffold(
+            "<instructions>Ensure all functions have explicit return types.</instructions>"
+        )
+        message = (
+            "Audit: pass 15/15\n"
+            "Do not skip the audit line.\n"
+            "```xml\n" + fenced_inner + "\n```\n"
+            "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"
+        )
+        validation_result = validate_prompt_workflow(message)
+        assert validation_result.allowed is True
+
+
+@pytest.mark.parametrize(
+    ("banned_pattern_name", "fenced_xml_content"),
+    [
+        ("do_not", "<instructions>Do not leave return types implicit.</instructions>"),
+        ("avoid", "<instructions>Avoid missing return types.</instructions>"),
+        ("never", "<constraints>Never store credentials in plain text.</constraints>"),
+        ("without", "<instructions>Deploy without running tests first.</instructions>"),
+        ("prevent", "<constraints>Prevent unauthorized access to the API.</constraints>"),
+        ("reject", "<constraints>Reject all unsigned commits.</constraints>"),
+        ("cannot", "<constraints>The API cannot accept unauthenticated requests.</constraints>"),
+        ("unless", "<constraints>Skip the build step unless the user explicitly approves.</constraints>"),
+        ("must_not", "<constraints>The script must not produce duplicates.</constraints>"),
+        ("must_never", "<constraints>You must never store credentials in environment variables.</constraints>"),
+        ("instead_of", "<instructions>Use explicit types instead of implicit ones.</instructions>"),
+        ("rather_than", "<constraints>Prefer explicit types rather than inferred ones.</constraints>"),
+        ("as_opposed_to", "<instructions>Use Grid as opposed to floats for layout.</instructions>"),
+    ],
+)
+def test_blocks_banned_pattern_inside_fenced_xml(
+    banned_pattern_name: str,
+    fenced_xml_content: str,
+) -> None:
+    message = _build_prompt_workflow_message_with_fenced_xml(
+        _wrap_five_section_scaffold(fenced_xml_content)
+    )
+    validation_result = validate_prompt_workflow(message)
+    assert validation_result.allowed is False
+    assert "negative_keywords_in_artifact" in validation_result.reason_codes
+
+
+class TestValidatorCli:
+    """Tests that exercise the CLI entry point via subprocess."""
+
+    def test_cli_exits_zero_for_valid_content(self, tmp_path: Path) -> None:
+        fenced_content = _wrap_five_section_scaffold(
+            "<instructions>Ensure all functions have explicit return types.</instructions>"
+        )
+        draft_file = tmp_path / "draft.xml"
+        draft_file.write_text(
+            _build_prompt_workflow_message_with_fenced_xml(fenced_content),
+            encoding="utf-8",
+        )
+        completed_process = subprocess.run(
+            [sys.executable, str(VALIDATOR_MODULE_PATH), str(draft_file)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert completed_process.returncode == 0
+        assert completed_process.stderr.strip() == ""
+
+    def test_cli_exits_two_with_bracketed_reason_code_on_stderr(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        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"
+        )
+        draft_file = tmp_path / "draft.xml"
+        draft_file.write_text(message, encoding="utf-8")
+        completed_process = subprocess.run(
+            [sys.executable, str(VALIDATOR_MODULE_PATH), str(draft_file)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert completed_process.returncode == 2
+        assert "[missing_context_signals]" in completed_process.stderr
+
+    def test_cli_stderr_format_uses_reason_code_prefix(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        fenced_content = _wrap_five_section_scaffold(
+            "<instructions>Do not leave return types implicit.</instructions>"
+        )
+        draft_file = tmp_path / "draft.xml"
+        draft_file.write_text(
+            _build_prompt_workflow_message_with_fenced_xml(fenced_content),
+            encoding="utf-8",
+        )
+        completed_process = subprocess.run(
+            [sys.executable, str(VALIDATOR_MODULE_PATH), str(draft_file)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert completed_process.returncode == 2
+        assert "[negative_keywords_in_artifact]" in completed_process.stderr
+        assert "Banned negative keywords" in completed_process.stderr
+
+    def test_cli_reads_from_stdin_when_no_file_argument(self) -> None:
+        fenced_content = _wrap_five_section_scaffold(
+            "<instructions>Ensure all functions have explicit return types.</instructions>"
+        )
+        valid_message = _build_prompt_workflow_message_with_fenced_xml(fenced_content)
+        completed_process = subprocess.run(
+            [sys.executable, str(VALIDATOR_MODULE_PATH)],
+            input=valid_message,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert completed_process.returncode == 0

package/hooks/hooks.json

@@ -150,11 +150,6 @@
             "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.17.1",
+    "version": "1.17.5",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -22,6 +22,9 @@
         "tdd",
         "code-quality"
     ],
+    "dependencies": {
+        "@jl-cmd/prompt-generator": "^1.0.0"
+    },
     "license": "MIT",
     "repository": {
         "type": "git",

package/skills/prompt-generator/ARCHITECTURE.md

@@ -13,5 +13,6 @@ Baseline inventory of files in the prompt-generator skill package.
 | `evals/prompt-generator.json` | Scenario eval rows |
 | `templates/skill-from-ground-up.md` | Net-new skill checkpoint template |
 | `templates/skill-refinement-package.md` | Existing-skill refinement template |
-| `hooks/blocking/prompt-workflow-stop-guard.py` | Stop gate + clipboard |
+| `hooks/blocking/prompt_workflow_validate.py` | Validator CLI (file-based loop) |
 | `hooks/blocking/prompt_workflow_gate_core.py` | Fence extraction, markers |
+| `hooks/blocking/prompt_workflow_clipboard.py` | Clipboard copy for artifacts |

package/skills/prompt-generator/REFERENCE.md

@@ -7,8 +7,8 @@ When authoring or refining prompts, ground decisions in these sources. If guidan
 ### Tier 1: Anthropic (primary authority for Claude)
 
 - https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview -- overview, links to all sub-guides
-- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices -- the single living reference for Claude's latest models. Covers general principles, XML tags, prefill deprecation, tool use, thinking, agentic systems, overeagerness, evidence-grounding and citing sources before strong claims.
-- https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026): 171 internal activation patterns that causally influence behavior. Key prompt-engineering takeaways: clear criteria and escape routes improve output quality, collaborative framing activates engagement, positive task framing correlates with better results, inviting transparency produces more reliable output. Cross-model caveat: studied on Sonnet 4.5; patterns align with best practices independently.
+- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices -- the single living reference for Claude's latest models.
+- https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026). Key takeaways: clear criteria and escape routes, collaborative framing, positive task framing, inviting transparency. Full catalog: `packages/claude-dev-env/docs/emotion-informed-prompt-design.md`.
 - https://www.anthropic.com/research/emotion-concepts-function -- blog summary of the above paper.
 - https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking -- adaptive thinking reference; replaces manual budget_tokens with effort-based control.
 - https://claude.com/blog/harnessing-claudes-intelligence -- harness evolution: primitives Claude already knows, what to stop doing in the harness, deliberate boundaries (context economics, caching, typed tools). Local inventory: `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`.
@@ -37,7 +37,11 @@ When authoring or refining prompts, ground decisions in these sources. If guidan
 
 ### Conflict resolution rule
 
-If sources disagree on a technique, apply in order: Anthropic documentation first (it describes the actual model behavior), then OpenAI/Google/Microsoft (large-scale research with cross-model relevance), then community sources (patterns and intuition, not authoritative on model internals). When Tier 3 contradicts Tier 1, Tier 1 wins without exception.
+If sources disagree, apply tier order: Anthropic first, then OpenAI/Google/Microsoft, then community. Tier 1 wins when conflicting with lower tiers.
+
+### Outcome preview gate and digest (`prompt-generator`)
+
+See SKILL.md §§107-115 (Phases 4-5) and `TARGET_OUTPUT.md` for the full contract. **Clipboard safety:** `extract_fenced_xml_content` concatenates every ` ```xml ` block—follow §7 sample formatting so clipboard copy stays the lone artifact body.
 
 ### Outcome preview gate and digest (`prompt-generator`)
 
@@ -74,7 +78,7 @@ Jump from concept to the platform specs the post names:
 
 ### Prompt caching (Hook 6)
 
-The [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) is stateless—re-supply prior actions, tool definitions, and instructions each turn. Maximize [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits: **stable prefix first, dynamic tail last**; **append** new content via **messages** instead of rewriting the cached prompt; **avoid mid-session model switches** (caches are model-specific—use a **subagent** for a cheaper model); **treat the tool list as part of the cached prefix** and avoid churn; use **tool search** so dynamic discovery **appends** without invalidating the prefix; for multi-turn agents, **advance breakpoints** toward the latest message (**auto-caching**). Cached input tokens are priced at **10% of base input** per [pricing](https://platform.claude.com/docs/en/about-claude/pricing).
+The Messages API is stateless. Maximize [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): **stable prefix first, dynamic tail last**; **append** via messages; **avoid mid-session model switches** (use a subagent for cheaper models); **treat tool list as cached prefix**; use **tool search** to append without invalidation; **advance breakpoints** toward the latest message. Cached tokens cost **10% of base input**.
 
 ### Typed tools vs bash strings (Hook 7)
 
@@ -179,12 +183,6 @@ Search for this information in a structured way. As you gather data, develop sev
 </research_approach>
 ```
 
-Key elements:
-- Define clear **success criteria** for the research question
-- Encourage **source verification** across multiple sources
-- Track **competing hypotheses** with confidence levels
-- **Self-critique** approach and plan regularly
-
 ## Evaluation loop
 
 For prompt drafts that must hold up over time:
@@ -209,7 +207,7 @@ When deciding how to approach a problem, choose an approach and commit to it. Av
 
 ## Debug JSON schema (prompt-generator pipeline)
 
-Use **only** when the user explicitly requests debug output (for example `show debug`, `full audit table`, `raw internal object`). Default assistant turns complete the normal handoff first: **audit line** + one `xml` fence + **`## Outcome digest`** + optional hook validation block (defined in SKILL.md Terminology; see also `TARGET_OUTPUT.md`); this JSON object is an optional appendix **after** that handoff (and after any hook validation block).
+Use **only** when the user explicitly requests debug output (for example `show debug`, `full audit table`, `raw internal object`). Default assistant turns complete the normal handoff first: one `xml` fence + **`## Outcome digest`** (see also `TARGET_OUTPUT.md`); this JSON object is an optional appendix **after** that handoff.
 
 Shape (field names stable for internal audit helpers and Stop-hook leak detection):