claude-dev-env 1.17.1 → 1.17.2

package/bin/install.mjs

@@ -31,7 +31,8 @@ const INSTALL_GROUPS = {
         includeHookFiles: [
             'blocking/prompt_workflow_gate_config.py',
             'blocking/prompt_workflow_gate_core.py',
-            'blocking/prompt-workflow-stop-guard.py',
+            'blocking/prompt_workflow_validate.py',
+            'blocking/prompt_workflow_clipboard.py',
             'HOOK_SPECS_PROMPT_WORKFLOW.md',
         ],
         includeRules: ['prompt-workflow-context-controls.md'],

package/hooks/HOOK_SPECS_PROMPT_WORKFLOW.md

@@ -6,18 +6,20 @@ Deterministic runtime gates for prompt workflows.
 
 The former `agent-execution-intent-gate.py` hook is **removed**. Native Agent/Task launches do not carry stable custom metadata; enforcing scope text on every spawn blocked legitimate `/agent-prompt` and refinement delegations. Scope and checklist rules remain enforced by the Stop guard when a prompt-workflow response is detected.
 
-## Gate: Leakage + Checklist + Scope (Stop)
+## Gate: Leakage + Checklist + Scope (file-based validation loop)
 
-- Hook: `hooks/blocking/prompt-workflow-stop-guard.py`
-- Event: `Stop`
-- Fail condition:
+- Validator: `hooks/blocking/prompt_workflow_validate.py`
+- Invocation: CLI against `data/prompts/.draft-prompt.xml` (exit 0 allowed, exit 2 blocked)
+- Fail conditions:
   - Raw internal refinement object appears in assistant output without explicit debug intent
   - Prompt-workflow response detected but deterministic checklist container is missing
   - Prompt-workflow response detected and required deterministic checklist rows are missing
   - Prompt-workflow response detected and required scope anchors are missing
   - Prompt-workflow response detected and runtime context-control signals are missing
   - Scope-bound text uses banned ambiguous scope terms
-- Action: `block` with correction reason.
+  - Banned negative keywords found inside fenced XML artifact
+  - Fenced XML artifact missing required sections
+- Enforcement: The drafting subagent writes the draft file, runs the validator, reads stderr violations (each prefixed with `[reason_code]`), edits the file, and re-runs until exit 0.
 
 ## Required Scope Anchors
 
@@ -49,7 +51,7 @@ The former `agent-execution-intent-gate.py` hook is **removed**. Native Agent/Ta
 - `base_minimal_instruction_layer: true`
 - `on_demand_skill_loading: true`
 
-These two signals are runtime-checked by the Stop guard whenever a prompt-workflow response is detected.
+These two signals are checked by the validator CLI whenever a prompt-workflow response is detected.
 
 ## Deterministic Boundary
 

package/hooks/blocking/prompt_workflow_validate.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Shared prompt-workflow validator callable from tests, CLI, and the Stop hook.
+
+Public API
+----------
+validate_prompt_workflow(assistant_message, user_context="")
+    Returns a ``ValidationResult`` with allowed/blocked status and reasons.
+
+CLI
+---
+    python prompt_workflow_validate.py path/to/draft.md
+    cat draft.md | python prompt_workflow_validate.py
+
+Exit codes match hook conventions: 0 allowed, 2 blocked.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from prompt_workflow_gate_core import (
+    find_ambiguous_scope_terms,
+    find_negative_keywords_in_fenced_xml,
+    has_checklist_container,
+    has_debug_intent,
+    has_internal_object_leak,
+    is_prompt_workflow_response,
+    missing_checklist_rows,
+    missing_context_control_signals,
+    missing_required_xml_sections,
+    missing_scope_anchors,
+)
+
+@dataclass(frozen=True)
+class ValidationReason:
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    allowed: bool
+    reasons: tuple[ValidationReason, ...] = field(default_factory=tuple)
+
+    @property
+    def reason_messages(self) -> list[str]:
+        return [each_reason.message for each_reason in self.reasons]
+
+    @property
+    def reason_codes(self) -> list[str]:
+        return [each_reason.code for each_reason in self.reasons]
+
+
+def _blocked(code: str, message: str) -> ValidationResult:
+    return ValidationResult(
+        allowed=False,
+        reasons=(ValidationReason(code=code, message=message),),
+    )
+
+
+def _check_internal_leak(
+    assistant_message: str,
+    debug_requested: bool,
+) -> ValidationResult | None:
+    if not has_internal_object_leak(assistant_message) or debug_requested:
+        return None
+    return _blocked(
+        code="internal_object_leak",
+        message=(
+            "Raw internal refinement object leakage detected. "
+            "Return sanitized user-facing output unless explicit debug intent is present."
+        ),
+    )
+
+
+def _check_required_sections(assistant_message: str) -> ValidationResult | None:
+    missing_sections = missing_required_xml_sections(assistant_message)
+    if not missing_sections:
+        return None
+    return _blocked(
+        code="missing_xml_sections",
+        message=(
+            "Fenced XML artifact missing required sections: "
+            + ", ".join(missing_sections)
+        ),
+    )
+
+
+def _check_checklist_rows(assistant_message: str) -> ValidationResult | None:
+    if not has_checklist_container(assistant_message):
+        return None
+    missing_rows = missing_checklist_rows(assistant_message)
+    if not missing_rows:
+        return None
+    return _blocked(
+        code="missing_checklist_rows",
+        message=("Deterministic checklist rows missing: " + ", ".join(missing_rows)),
+    )
+
+
+def _check_scope_anchors(assistant_message: str) -> ValidationResult | None:
+    missing_anchors = missing_scope_anchors(assistant_message)
+    if not missing_anchors:
+        return None
+    return _blocked(
+        code="missing_scope_anchors",
+        message=("Required scope anchors missing: " + ", ".join(missing_anchors)),
+    )
+
+
+def _check_context_signals(assistant_message: str) -> ValidationResult | None:
+    missing_signals = missing_context_control_signals(assistant_message)
+    if not missing_signals:
+        return None
+    return _blocked(
+        code="missing_context_signals",
+        message=(
+            "Runtime context-control preamble missing. "
+            "Include the two required lines from prompt-workflow-context-controls "
+            "(minimal instruction layer and on-demand skill loading)."
+        ),
+    )
+
+
+def _check_ambiguous_scope(assistant_message: str) -> ValidationResult | None:
+    ambiguous_terms = find_ambiguous_scope_terms(assistant_message)
+    if not ambiguous_terms:
+        return None
+    return _blocked(
+        code="ambiguous_scope",
+        message=("Ambiguous scope phrasing detected: " + ", ".join(ambiguous_terms)),
+    )
+
+
+def _check_negative_keywords(assistant_message: str) -> ValidationResult | None:
+    violations = find_negative_keywords_in_fenced_xml(assistant_message)
+    if not violations:
+        return None
+    violation_descriptions = [
+        f"  line {each_violation['line_number']}: "
+        f'"{each_violation["keyword"]}" in: {each_violation["line_text"]}'
+        for each_violation in violations
+    ]
+    return _blocked(
+        code="negative_keywords_in_artifact",
+        message=(
+            "Banned negative keywords found inside fenced XML artifact. "
+            "Rephrase as positive directives (what TO do, not what to avoid):\n"
+            + "\n".join(violation_descriptions)
+        ),
+    )
+
+
+def validate_prompt_workflow(
+    assistant_message: str,
+    user_context: str = "",
+) -> ValidationResult:
+    """Run all prompt-workflow gates on *assistant_message*.
+
+    Returns ``ValidationResult.allowed == True`` when every gate passes.
+    The first failing gate short-circuits and its reason is returned.
+    """
+    allowed_result = ValidationResult(allowed=True)
+
+    if not assistant_message.strip():
+        return allowed_result
+
+    debug_requested = has_debug_intent(user_context)
+
+    leak_result = _check_internal_leak(assistant_message, debug_requested)
+    if leak_result is not None:
+        return leak_result
+
+    if not is_prompt_workflow_response(assistant_message):
+        return allowed_result
+
+    workflow_checks = (
+        _check_required_sections,
+        _check_checklist_rows,
+        _check_scope_anchors,
+        _check_context_signals,
+        _check_ambiguous_scope,
+        _check_negative_keywords,
+    )
+    for each_check in workflow_checks:
+        gate_result = each_check(assistant_message)
+        if gate_result is not None:
+            return gate_result
+
+    return allowed_result
+
+
+def main() -> None:
+    blocked_exit_code: int = 2
+    allowed_exit_code: int = 0
+
+    if len(sys.argv) > 1:
+        file_path = Path(sys.argv[1])
+        assistant_text = file_path.read_text(encoding="utf-8")
+    elif not sys.stdin.isatty():
+        assistant_text = sys.stdin.read()
+    else:
+        sys.stderr.write("Usage: prompt_workflow_validate.py [path/to/draft.md]\n")
+        sys.stderr.write("       cat draft.md | prompt_workflow_validate.py\n")
+        sys.exit(blocked_exit_code)
+
+    validation_result = validate_prompt_workflow(assistant_text)
+    if validation_result.allowed:
+        sys.exit(allowed_exit_code)
+    for each_reason in validation_result.reasons:
+        sys.stderr.write(f"[{each_reason.code}] {each_reason.message}\n")
+    sys.exit(blocked_exit_code)
+
+
+if __name__ == "__main__":
+    main()

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.2",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

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 |