claude-dev-env 1.13.0 → 1.15.0

package/bin/install.mjs

@@ -29,6 +29,7 @@ const INSTALL_GROUPS = {
         description: 'Prompt engineering tools',
         skills: ['prompt-generator', 'agent-prompt'],
         includeHookFiles: [
+            'blocking/prompt_workflow_gate_config.py',
             'blocking/prompt_workflow_gate_core.py',
             'blocking/prompt-workflow-stop-guard.py',
             'HOOK_SPECS_PROMPT_WORKFLOW.md',

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

@@ -1,5 +1,10 @@
 #!/usr/bin/env python3
-"""Stop hook gate for prompt-workflow leakage and deterministic audit coverage."""
+"""Stop hook gate for prompt-workflow leakage and deterministic audit coverage.
+
+When every workflow gate passes, the fenced ``xml`` artifact body is copied to the
+system clipboard via :mod:`prompt_workflow_clipboard` (tkinter, then pyperclip).
+Set ``PROMPT_WORKFLOW_SKIP_CLIPBOARD=1`` to disable (tests, CI, headless).
+"""
 
 from __future__ import annotations
 
@@ -9,7 +14,9 @@ import sys
 from collections.abc import Callable
 from pathlib import Path
 
+from prompt_workflow_clipboard import copy_text_to_system_clipboard
 from prompt_workflow_gate_core import (
+    extract_fenced_xml_content,
     find_ambiguous_scope_terms,
     find_negative_keywords_in_fenced_xml,
     has_debug_intent,
@@ -18,6 +25,7 @@ from prompt_workflow_gate_core import (
     is_prompt_workflow_response,
     missing_context_control_signals,
     missing_checklist_rows,
+    missing_required_xml_sections,
     missing_scope_anchors,
 )
 
@@ -150,10 +158,23 @@ def _check_negative_keywords_in_artifact(assistant_message: str) -> dict | None:
         ),
     )
 
+def _check_required_xml_sections(assistant_message: str) -> dict | None:
+    missing_sections = missing_required_xml_sections(assistant_message)
+    if not missing_sections:
+        return None
+    return _build_block(
+        brief_label="retrying: include all required XML sections",
+        full_reason=(
+            "PROMPT-WORKFLOW GATE: Fenced XML artifact missing required sections: "
+            + ", ".join(missing_sections)
+        ),
+    )
+
 def _evaluate_workflow_gates(assistant_message: str) -> dict | None:
     if not is_prompt_workflow_response(assistant_message):
         return None
     workflow_gate_checks: tuple[Callable[[str], dict | None], ...] = (
+        _check_required_xml_sections,
         _check_missing_checklist_rows,
         _check_missing_scope_anchors,
         _check_missing_context_signals,
@@ -185,6 +206,10 @@ def main() -> None:
 
     if block is not None:
         sys.stdout.write(json.dumps(block) + "\n")
+    elif is_prompt_workflow_response(assistant_message):
+        artifact_text = extract_fenced_xml_content(assistant_message).strip()
+        if artifact_text:
+            copy_text_to_system_clipboard(artifact_text)
 
     sys.exit(0)
 

package/hooks/blocking/prompt_workflow_clipboard.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Cross-platform clipboard writes for prompt-workflow XML artifacts."""
+
+from __future__ import annotations
+
+import os
+
+
+def _clipboard_disabled_by_env() -> bool:
+    flag = os.environ.get("PROMPT_WORKFLOW_SKIP_CLIPBOARD", "").strip().lower()
+    return flag in {"1", "true", "yes", "on"}
+
+
+def copy_text_to_system_clipboard(text: str) -> bool:
+    """Write ``text`` to the OS clipboard using Python-only backends.
+
+    Tries :mod:`tkinter` (stdlib) first, then optional ``pyperclip`` if installed.
+    Returns ``True`` when a backend reports success, ``False`` otherwise
+    (missing dependency, headless display, empty payload, or env opt-out).
+    """
+    if not text.strip():
+        return False
+    if _clipboard_disabled_by_env():
+        return False
+    if _copy_via_tkinter(text):
+        return True
+    return _copy_via_pyperclip(text)
+
+
+def _copy_via_tkinter(text: str) -> bool:
+    try:
+        import tkinter as tk
+    except ImportError:
+        return False
+    root: tk.Tk | None = None
+    try:
+        root = tk.Tk()
+        root.withdraw()
+        root.clipboard_clear()
+        root.clipboard_append(text)
+        root.update_idletasks()
+        root.update()
+        return True
+    except Exception:
+        return False
+    finally:
+        if root is not None:
+            try:
+                root.destroy()
+            except Exception:
+                pass
+
+
+def _copy_via_pyperclip(text: str) -> bool:
+    try:
+        import pyperclip
+    except ImportError:
+        return False
+    try:
+        pyperclip.copy(text)
+        return True
+    except Exception:
+        return False

package/hooks/blocking/prompt_workflow_gate_config.py

@@ -0,0 +1,113 @@
+"""Static lists and compiled regexes for prompt-workflow gate checks.
+
+Edit this file to change scope anchors, checklist rows, markers, or keyword lists
+without touching gate logic in prompt_workflow_gate_core.py.
+"""
+
+from __future__ import annotations
+
+import re
+
+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",
+    "reversible_action_and_safety_check_guidance",
+    "concrete_output_contract",
+    "scope_boundary_present",
+    "explicit_scope_anchors_present",
+    "all_instructions_artifact_bound",
+    "scope_terms_explicit_and_anchored",
+    "completion_boundary_measurable",
+    "citation_grounding_policy_present",
+    "source_priority_rules_present",
+    "artifact_language_confidence",
+)
+
+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": {',
+)
+
+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",
+)
+
+NEGATIVE_KEYWORDS_IN_ARTIFACT: tuple[str, ...] = (
+    "no",
+    "not",
+    "don't",
+    "do not",
+    "never",
+    "avoid",
+    "without",
+    "refrain",
+    "stop",
+    "prevent",
+    "exclude",
+    "prohibit",
+    "forbid",
+    "reject",
+    "cannot",
+    "unless",
+)
+
+NEGATIVE_INDIRECT_PATTERNS_IN_ARTIFACT: tuple[str, ...] = (
+    r"instead of\s+\w+",
+    r"rather than\s+\w+",
+    r"as opposed to\s+\w+",
+)
+
+REQUIRED_XML_SECTIONS: tuple[str, ...] = (
+    "role",
+    "background",
+    "instructions",
+    "constraints",
+    "output_format",
+)
+
+COMPILED_NEGATIVE_KEYWORD_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
+    re.compile(rf"\b{re.escape(keyword)}\b", re.IGNORECASE)
+    for keyword in NEGATIVE_KEYWORDS_IN_ARTIFACT
+)
+
+COMPILED_NEGATIVE_INDIRECT_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in NEGATIVE_INDIRECT_PATTERNS_IN_ARTIFACT
+)

package/hooks/blocking/prompt_workflow_gate_core.py

@@ -6,116 +6,87 @@ 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",
+from prompt_workflow_gate_config import (
+    AMBIGUOUS_SCOPE_TERMS,
+    COMPILED_NEGATIVE_INDIRECT_PATTERNS,
+    COMPILED_NEGATIVE_KEYWORD_PATTERNS,
+    DEBUG_INTENT_MARKERS,
+    INTERNAL_OBJECT_MARKERS,
+    PROMPT_WORKFLOW_RESPONSE_MARKERS,
+    REQUIRED_CHECKLIST_ROWS,
+    REQUIRED_SCOPE_ANCHORS,
+    REQUIRED_XML_SECTIONS,
 )
 
-REQUIRED_CHECKLIST_ROWS: tuple[str, ...] = (
-    "structured_scoped_instructions",
-    "sequential_steps_present",
-    "positive_framing",
-    "acceptance_criteria_defined",
-    "safety_reversibility_language",
-    "reversible_action_and_safety_check_guidance",
-    "concrete_output_contract",
-    "scope_boundary_present",
-    "explicit_scope_anchors_present",
-    "all_instructions_artifact_bound",
-    "scope_terms_explicit_and_anchored",
-    "completion_boundary_measurable",
-    "citation_grounding_policy_present",
-    "source_priority_rules_present",
-    "artifact_language_confidence",
-)
-
-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": {',
-)
+def _line_opens_xml_fence(line: str) -> bool:
+    stripped = line.strip()
+    if not stripped.startswith("```"):
+        return False
+    remainder = stripped[3:].strip()
+    return remainder == "xml" or remainder.startswith("xml ")
 
-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 _line_is_bare_fence_close(line: str) -> bool:
+    return line.strip() == "```"
 
 
-NEGATIVE_KEYWORDS_IN_ARTIFACT: tuple[str, ...] = (
-    "no",
-    "not",
-    "don't",
-    "do not",
-    "never",
-    "avoid",
-    "without",
-    "refrain",
-    "stop",
-    "prevent",
-    "exclude",
-    "prohibit",
-    "forbid",
-    "reject",
-    "cannot",
-    "unless",
-)
-
-NEGATIVE_INDIRECT_PATTERNS_IN_ARTIFACT: tuple[str, ...] = (
-    r"instead of\s+\w+",
-    r"rather than\s+\w+",
-    r"as opposed to\s+\w+",
-)
-
-COMPILED_NEGATIVE_KEYWORD_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
-    re.compile(rf"\b{re.escape(keyword)}\b", re.IGNORECASE)
-    for keyword in NEGATIVE_KEYWORDS_IN_ARTIFACT
-)
-
-COMPILED_NEGATIVE_INDIRECT_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
-    re.compile(pattern, re.IGNORECASE)
-    for pattern in NEGATIVE_INDIRECT_PATTERNS_IN_ARTIFACT
-)
-
-FENCED_XML_BLOCK_PATTERN: re.Pattern[str] = re.compile(
-    r"```xml\s*\n(.*?)```", re.DOTALL
-)
+def _line_opens_inner_markdown_fence(line: str) -> bool:
+    stripped = line.strip()
+    if not stripped.startswith("```"):
+        return False
+    return stripped != "```"
 
 
 def extract_fenced_xml_content(text: str) -> str:
-    all_matches = FENCED_XML_BLOCK_PATTERN.findall(text)
-    return "\n".join(all_matches)
+    """Extract bodies of ```xml fenced blocks.
+
+    The closing delimiter is a line whose stripped text is exactly three backticks.
+    Inner Markdown code fences (for example a line starting with three backticks
+    plus a language tag) are scanned until their own closing backtick line so the
+    outer ``xml`` fence does not end early.
+    """
+    results: list[str] = []
+    lines = text.splitlines()
+    index = 0
+    while index < len(lines):
+        if _line_opens_xml_fence(lines[index]):
+            index += 1
+            body_lines: list[str] = []
+            while index < len(lines):
+                line = lines[index]
+                if _line_is_bare_fence_close(line):
+                    index += 1
+                    break
+                if _line_opens_inner_markdown_fence(line):
+                    body_lines.append(line)
+                    index += 1
+                    while index < len(lines):
+                        inner_line = lines[index]
+                        body_lines.append(inner_line)
+                        index += 1
+                        if _line_is_bare_fence_close(inner_line):
+                            break
+                    continue
+                body_lines.append(line)
+                index += 1
+            results.append("\n".join(body_lines))
+            continue
+        index += 1
+    return "\n".join(results)
+
+
+def missing_required_xml_sections(text: str) -> list[str]:
+    fenced_body = extract_fenced_xml_content(text)
+    if not fenced_body.strip():
+        return []
+    missing_sections: list[str] = []
+    for section_name in REQUIRED_XML_SECTIONS:
+        open_tag = re.compile(rf"<{re.escape(section_name)}(\s[^>]*)?>")
+        close_tag = re.compile(rf"</{re.escape(section_name)}>")
+        if not open_tag.search(fenced_body) or not close_tag.search(fenced_body):
+            missing_sections.append(section_name)
+    return missing_sections
 
 
 def find_negative_keywords_in_fenced_xml(
@@ -192,6 +163,9 @@ def is_prompt_workflow_response(text: str) -> bool:
 
 
 def missing_context_control_signals(text: str) -> list[str]:
-    return [
-        signal for signal in REQUIRED_CONTEXT_CONTROL_SIGNALS if signal not in text.lower()
-    ]
+    required_signals: tuple[str, ...] = (
+        "base_minimal_instruction_layer: true",
+        "on_demand_skill_loading: true",
+    )
+    lowered = text.lower()
+    return [signal for signal in required_signals if signal not in lowered]

package/hooks/blocking/test_prompt_workflow_clipboard.py

@@ -0,0 +1,54 @@
+"""Tests for prompt_workflow_clipboard."""
+
+from __future__ import annotations
+
+import pytest
+
+from prompt_workflow_clipboard import copy_text_to_system_clipboard
+
+
+def test_empty_text_returns_false() -> None:
+    assert copy_text_to_system_clipboard("") is False
+    assert copy_text_to_system_clipboard("   \n") is False
+
+
+def test_respects_skip_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PROMPT_WORKFLOW_SKIP_CLIPBOARD", "1")
+    assert copy_text_to_system_clipboard("hello") is False
+
+
+@pytest.mark.parametrize(
+    "flag_value",
+    ("1", "true", "YES", "on"),
+)
+def test_skip_env_variants(monkeypatch: pytest.MonkeyPatch, flag_value: str) -> None:
+    monkeypatch.setenv("PROMPT_WORKFLOW_SKIP_CLIPBOARD", flag_value)
+    assert copy_text_to_system_clipboard("payload") is False
+
+
+def test_prefers_tkinter_when_it_succeeds(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PROMPT_WORKFLOW_SKIP_CLIPBOARD", raising=False)
+    monkeypatch.setattr(
+        "prompt_workflow_clipboard._copy_via_tkinter",
+        lambda t: True,
+    )
+
+    def _fail_pyperclip(_t: str) -> bool:
+        raise AssertionError("pyperclip must run only when tkinter fails")
+
+    monkeypatch.setattr("prompt_workflow_clipboard._copy_via_pyperclip", _fail_pyperclip)
+    assert copy_text_to_system_clipboard("hello") is True
+
+
+def test_falls_back_to_pyperclip(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PROMPT_WORKFLOW_SKIP_CLIPBOARD", raising=False)
+    monkeypatch.setattr("prompt_workflow_clipboard._copy_via_tkinter", lambda t: False)
+    monkeypatch.setattr("prompt_workflow_clipboard._copy_via_pyperclip", lambda t: True)
+    assert copy_text_to_system_clipboard("hello") is True
+
+
+def test_returns_false_when_both_backends_fail(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PROMPT_WORKFLOW_SKIP_CLIPBOARD", raising=False)
+    monkeypatch.setattr("prompt_workflow_clipboard._copy_via_tkinter", lambda t: False)
+    monkeypatch.setattr("prompt_workflow_clipboard._copy_via_pyperclip", lambda t: False)
+    assert copy_text_to_system_clipboard("hello") is False

package/hooks/blocking/test_prompt_workflow_gate_core.py

@@ -1,12 +1,14 @@
 """Unit tests for shared prompt workflow gate logic."""
 
 from prompt_workflow_gate_core import (
+    extract_fenced_xml_content,
     find_ambiguous_scope_terms,
     has_checklist_container,
     has_internal_object_leak,
     is_prompt_workflow_response,
     missing_context_control_signals,
     missing_checklist_rows,
+    missing_required_xml_sections,
     missing_scope_anchors,
 )
 
@@ -52,3 +54,71 @@ def test_ambiguous_scope_terms_detected() -> None:
     terms = find_ambiguous_scope_terms(text)
     assert "this session" in terms
     assert "current files" in terms
+
+
+def _fenced_xml(body: str) -> str:
+    return f"```xml\n{body}\n```"
+
+
+def test_missing_required_xml_sections_all_present_returns_empty() -> None:
+    body = (
+        "<role>R.</role>\n"
+        "<background>C.</background>\n"
+        "<instructions>I.</instructions>\n"
+        "<constraints>Co.</constraints>\n"
+        "<output_format>O.</output_format>\n"
+    )
+    assert missing_required_xml_sections(_fenced_xml(body)) == []
+
+
+def test_missing_required_xml_sections_missing_background() -> None:
+    body = (
+        "<role>R.</role>\n"
+        "<instructions>I.</instructions>\n"
+        "<constraints>Co.</constraints>\n"
+        "<output_format>O.</output_format>\n"
+    )
+    assert missing_required_xml_sections(_fenced_xml(body)) == ["background"]
+
+
+def test_missing_required_xml_sections_missing_role_and_output_format() -> None:
+    body = (
+        "<background>C.</background>\n"
+        "<instructions>I.</instructions>\n"
+        "<constraints>Co.</constraints>\n"
+    )
+    missing = missing_required_xml_sections(_fenced_xml(body))
+    assert missing == ["role", "output_format"]
+
+
+def test_missing_required_xml_sections_no_fence_returns_empty() -> None:
+    assert missing_required_xml_sections("no fenced xml here") == []
+
+
+def test_missing_required_xml_sections_prose_without_tags_counts_as_missing() -> None:
+    body = (
+        "<role>R.</role>\n"
+        "background appears in prose but has no tags.\n"
+        "<instructions>I.</instructions>\n"
+        "<constraints>Co.</constraints>\n"
+        "<output_format>O.</output_format>\n"
+    )
+    assert missing_required_xml_sections(_fenced_xml(body)) == ["background"]
+
+
+def test_extract_fenced_xml_preserves_content_after_nested_inner_fence() -> None:
+    message = (
+        "```xml\n"
+        "<role>R</role>\n"
+        "<illustrations>\n"
+        "```bash\necho hi\n```\n"
+        "</illustrations>\n"
+        "<background>B</background>\n"
+        "<instructions>I</instructions>\n"
+        "<constraints>C</constraints>\n"
+        "<output_format>O</output_format>\n"
+        "```\n"
+    )
+    extracted = extract_fenced_xml_content(message)
+    assert "</illustrations>" in extracted
+    assert "<background>B</background>" in extracted

package/hooks/blocking/test_prompt_workflow_stop_guard.py

@@ -10,6 +10,14 @@ import pytest
 
 SCRIPT_PATH = Path(__file__).parent / "prompt-workflow-stop-guard.py"
 
+
+@pytest.fixture(autouse=True)
+def _disable_prompt_workflow_clipboard_in_subprocess(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Subprocess hook inherits env; clipboard would be flaky in CI."""
+    monkeypatch.setenv("PROMPT_WORKFLOW_SKIP_CLIPBOARD", "1")
+
 def _run_hook(payload: dict) -> subprocess.CompletedProcess[str]:
     return subprocess.run(
         [sys.executable, str(SCRIPT_PATH)],
@@ -118,6 +126,16 @@ def test_blocks_ambiguous_scope_phrasing() -> None:
     assert response["decision"] == "block"
     assert "Ambiguous scope phrasing detected" in response["reason"]
 
+def _wrap_five_section_scaffold(inner_body: str) -> str:
+    return (
+        "<role>Test role sentence one.</role>\n"
+        "<background>Test background sentence one.</background>\n"
+        f"{inner_body}\n"
+        "<constraints>Test constraints sentence one.</constraints>\n"
+        "<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"
@@ -137,7 +155,9 @@ def _build_prompt_workflow_message_with_fenced_xml(fenced_xml_body: str) -> str:
 
 
 def test_allows_positive_phrasing_inside_fenced_xml() -> None:
-    fenced_content = "<instructions>Ensure all functions have explicit return types.</instructions>"
+    fenced_content = _wrap_five_section_scaffold(
+        "<instructions>Ensure all functions have explicit return types.</instructions>"
+    )
     payload = {
         "last_assistant_message": _build_prompt_workflow_message_with_fenced_xml(fenced_content),
     }
@@ -172,7 +192,9 @@ def test_blocks_banned_pattern_inside_fenced_xml(
     fenced_xml_content: str,
 ) -> None:
     payload = {
-        "last_assistant_message": _build_prompt_workflow_message_with_fenced_xml(fenced_xml_content),
+        "last_assistant_message": _build_prompt_workflow_message_with_fenced_xml(
+            _wrap_five_section_scaffold(fenced_xml_content)
+        ),
     }
     result = _run_hook(payload)
     response = json.loads(result.stdout)
@@ -180,12 +202,15 @@ def test_blocks_banned_pattern_inside_fenced_xml(
 
 
 def test_permits_negative_keywords_outside_fenced_xml() -> 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"
-        "<instructions>Ensure all functions have explicit return types.</instructions>\n"
-        "```\n"
+        + fenced_inner
+        + "\n```\n"
         "overall_status: pass\n"
         + _full_checklist_rows()
         + "target_local_roots\n"
@@ -201,6 +226,23 @@ def test_permits_negative_keywords_outside_fenced_xml() -> None:
     assert result.stdout.strip() == ""
 
 
+def test_blocks_when_fenced_xml_missing_background_section() -> 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"
+    )
+    payload = {
+        "last_assistant_message": _build_prompt_workflow_message_with_fenced_xml(fenced_body),
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+    assert "background" in response["reason"]
+    assert "include all required XML sections" in response["systemMessage"]
+
+
 def test_allows_fully_structured_prompt_workflow_output() -> None:
     payload = {
         "last_assistant_message": (

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.13.0",
+    "version": "1.15.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md

@@ -26,7 +26,7 @@ Use this command:
      - `target_file_globs`
      - `comparison_basis`
      - `completion_boundary`
-   - XML scaffold includes all sections:
+   - XML scaffold includes all sections — verified by the Stop hook at runtime; each required section tag must have both an opening and a closing tag:
      - `<role>`
      - `<context>`
      - `<instructions>`
@@ -129,6 +129,7 @@ If `overall_status` is `fail`:
 Validate fail-closed runtime gates:
 
 1. **Stop leakage/scope/checklist gate**
+   - **Section-presence gate (Stop)** — Block responses where the fenced XML artifact is missing any of the five required section tag pairs: `role`, `context`, `instructions`, `constraints`, `output_format`.
    - Block responses that leak raw internal refinement object fields unless debug intent is explicit.
    - Block responses missing deterministic checklist rows when audit output is present.
    - Block responses using ambiguous scope phrasing in scope-bound sections.
@@ -148,6 +149,7 @@ Validate fail-closed runtime gates:
   - Missing required scope anchors (when Stop guard applies)
   - Raw internal object leakage without debug intent
   - Missing required checklist rows in audit output
+  - Missing required XML sections (`role`, `context`, `instructions`, `constraints`, `output_format`) in the fenced artifact (opening and closing tags)
   - Ambiguous scope terms in scope-bound text
   - Negative keywords inside fenced XML artifacts
   - Hedging language inside fenced XML artifacts

package/skills/prompt-generator/SKILL.md

@@ -185,6 +185,7 @@ Expand the light self-check with this internal checklist when useful:
 - [ ] Emotion-informed framing is present: collaborative language, explicit success criteria, and explicit permission to express uncertainty ("say so if unsure")
 - [ ] Constraints are surfaced upfront (proactive constraint awareness) so the model can incorporate them into its plan, and each non-obvious constraint carries its motivation
 - [ ] Self-correction chaining is considered when the prompt must hold up over time (generate → review → refine)
+- [ ] All five required XML sections (`<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`) are present with both opening and closing tags in the fenced artifact
 
 ### 9. Deliver (orchestrator)
 
@@ -196,6 +197,8 @@ Audit: pass 15/15
 
 (or `fail N/15 — …`), immediately followed by **one** fenced XML block; **send boundary** is immediately after the closing fence so the user receives a copy-ready pair (audit line + artifact) in one assistant message before the conversation continues.
 
+**Render-survival:** When the fenced XML uses tag names that **collide with HTML5 elements** (`context`, `section`, `summary`, `details`, `header`, `footer`, `main`, `aside`, `article`, `nav`, `figure`), or when the artifact is **very large**, **write the artifact to a file** and give the user the path together with the usual one-line audit. Add a brief **section inventory** (confirming the five required sections) so the user can trust the file even if the inline fence would render poorly. Details: **TARGET_OUTPUT.md — Structural invariant E**.
+
 ### 10. Default refinement mode (subagent-internal)
 
 For non-trivial requests, run inside the drafting subagent (use **draft-only** when the user explicitly asks for a quick draft / no refinement loop):
@@ -212,6 +215,8 @@ Required section list is immutable for this pipeline: `role`, `context`, `instru
 
 **Two-tier validation — tier 2:** The `15` in `Audit: pass 15/15` counts these **compliance** rows (stable ids for hooks). Tier 1 is the **light self-check** in §8—keep the steps separate so models do not merge them.
 
+**Runtime Stop hook:** In addition to the 15-row internal audit, the `prompt-workflow-stop-guard` Stop hook enforces **section presence** on prompt-workflow responses: any fenced Markdown XML block must include opening and closing tags for `role`, `context`, `instructions`, `constraints`, and `output_format`. Missing tags trigger a retry before the user sees a passing turn. Pair this with **Structural invariant E** in `TARGET_OUTPUT.md` so users still receive intact XML when chat renderers strip HTML-named tags.
+
 | # | Row name |
 |---|----------|
 | 1 | structured_scoped_instructions |

package/skills/prompt-generator/TARGET_OUTPUT.md

@@ -87,6 +87,13 @@ This file is the **target output spec** for eval-driven iteration of the `prompt
 - Place residual uncertainty only in `<open_question>` elements (one topic per tag) with a clear decision you need from the executor or user.
 - Use definitive phrasing inside instructions (e.g. “Run tests in `packages/foo` with `pytest tests/`”) so each step reads like an executable checklist.
 
+## Structural invariant E — Render-survival for XML sections
+
+- **Problem:** Tag names used for prompt XML sections can overlap **HTML5 element names**. Chat renderers may treat those tokens as HTML and hide or alter the content between tags. High-risk examples include: `context`, `section`, `summary`, `details`, `header`, `footer`, `main`, `aside`, `article`, `nav`, `figure`. The raw assistant text may be complete while the **rendered** message looks like sections are missing (notably `<context>`).
+- **Primary mitigation:** When the fenced XML artifact **contains any tag whose local name is on that HTML-collision list**, or when the artifact is **large enough that render truncation is likely**, the orchestrator **must write the full artifact to a file** (default: under `data/prompts/` or a path the user supplied earlier) and **paste the absolute file path** in the chat message. Pair the path with a **short section inventory** confirming all five required sections (`role`, `context`, `instructions`, `constraints`, `output_format`) are present in the file.
+- **Fallback when file write is unavailable:** Escape the **opening angle bracket** of colliding tags (for example `&lt;context>` — user restores `<` when pasting) or use another distinctive wrapper **documented in the same message**, so the user can recover literal XML. State explicitly that the user should restore brackets when copying into another system.
+- **Structural safety net:** Regardless of renderer behavior, the **Stop hook section-presence gate** blocks any prompt-workflow response whose fenced XML is missing any required opening/closing section tag pair. Methodology: [Anthropic — Agent Skills: evaluation and iteration](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration).
+
 ## XML artifact (minimum sections)
 
 Include at least:

package/skills/prompt-generator/evals/prompt-generator.json

@@ -133,6 +133,43 @@
         "Example: 'Ensure all functions have explicit return types' passes; 'Do not leave return types implicit' fails; 'Avoid missing return types' fails",
         "Applies to all sections inside the fenced block: <role>, <context>, <instructions>, <constraints>, <output_format>"
       ]
+    },
+    {
+      "id": 10,
+      "name": "required_sections_present_in_artifact",
+      "scenario": "Section completeness gate (render-survival)",
+      "prompt": "/prompt-generator Write a system prompt for a Python linting agent that auto-fixes code style issues in this repo",
+      "files": [],
+      "expected_behavior": [
+        "Fenced XML block contains opening and closing tags for all five required sections: role, context, instructions, constraints, output_format",
+        "Each required section contains substantive content (minimum one sentence each)",
+        "The Stop hook section-presence check passes for this output (no missing section tags)",
+        "Sections appear in order: role first, output_format last among the five required sections"
+      ]
+    },
+    {
+      "id": 11,
+      "name": "section_missing_triggers_hook_block",
+      "scenario": "Section completeness gate — failure path",
+      "prompt": "Synthetic eval: assistant final message is prompt-workflow shaped (overall_status, checklist, scope anchors, runtime signals) with a fenced Markdown XML block whose body omits the entire context section (no context opening/closing tags); observer asserts Stop hook behavior and successful retry.",
+      "files": [],
+      "expected_behavior": [
+        "The Stop hook runs _check_required_xml_sections and returns a block decision naming context as a missing section",
+        "The model retry includes all five required sections with both opening and closing tags",
+        "The retry output passes the section-presence gate (empty missing list from missing_required_xml_sections)"
+      ]
+    },
+    {
+      "id": 12,
+      "name": "render_survival_file_fallback",
+      "scenario": "Render-layer mitigation",
+      "prompt": "/prompt-generator Write a comprehensive agent prompt for migrating a large Prisma schema and all related API routes, with step-by-step rollout, rollback, and verification — artifact sized like the migration prompt that triggered chat render stripping.",
+      "files": [],
+      "expected_behavior": [
+        "When the artifact exceeds a size threshold or contains XML section tag names that collide with HTML5 elements (context, section, summary, details, header, footer, main, aside, article, nav, figure), the orchestrator writes the full artifact to a file under data/prompts/ or a user-specified path",
+        "The file contains the complete XML with all tags preserved as literal text",
+        "The user-facing message states the file path and briefly inventories which required sections the artifact contains"
+      ]
     }
   ]
 }