claude-dev-env 1.15.0 → 1.16.1

package/agents/skill-writer-agent.md

@@ -268,7 +268,7 @@ You are a specialized agent that orchestrates the skill-writer skill for creatin
 ## Examples
 
 <example>
-<context>User wants to create a simple skill for git commit message formatting (single file, straightforward).</context>
+<background>User wants to create a simple skill for git commit message formatting (single file, straightforward).</background>
 
 <user>
 Create a skill for writing good git commit messages following conventional commits.
@@ -303,7 +303,7 @@ This is straightforward enough for the skill to handle directly without needing
 </example>
 
 <example>
-<context>User needs comprehensive web automation skill with TDD patterns, helper scripts, and team deployment.</context>
+<background>User needs comprehensive web automation skill with TDD patterns, helper scripts, and team deployment.</background>
 
 <user>
 We need a comprehensive skill for web automation development. It should include:
@@ -378,7 +378,7 @@ Once I have these details, I'll create the complete package with progressive dis
 </example>
 
 <example>
-<context>User asks about allowed-tools frontmatter field.</context>
+<background>User asks about allowed-tools frontmatter field.</background>
 
 <user>
 When should I use the allowed-tools field in SKILL.md frontmatter?

package/hooks/HOOK_SPECS_PROMPT_WORKFLOW.md

@@ -54,3 +54,9 @@ These two signals are runtime-checked by the Stop guard whenever a prompt-workfl
 ## Deterministic Boundary
 
 These hooks enforce only structural/runtime checks. Semantic quality remains in auditor layer.
+
+## Reviewing Flattened Transcript Exports
+
+- Live prompt-workflow responses still require an explicit `Audit:` line plus one outer `xml` fence. The Stop guard and clipboard path continue to evaluate that literal boundary.
+- Saved transcript exports can flatten blocked retry turns and omit the outer fence lines. Normalize those files with `prompt_workflow_gate_core.normalize_prompt_workflow_export(...)`, then evaluate the rebuilt message with `extract_fenced_xml_content(...)` or `extract_fenced_xml_content_from_export(...)`.
+- Fence-relative evals review the **last successful Audit + artifact pair** after normalization. Earlier blocked retries in the flattened transcript remain diagnostic evidence and do not count as extra delivered artifacts.

package/hooks/blocking/prompt_workflow_gate_core.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import re
+import textwrap
 from typing import Iterable
 
 from prompt_workflow_gate_config import (
@@ -18,25 +19,57 @@ from prompt_workflow_gate_config import (
     REQUIRED_XML_SECTIONS,
 )
 
+TRIPLE_BACKTICK = "```"
+AUDIT_LINE_PATTERN = re.compile(r"^\s*[●•]?\s*(Audit:\s*.+?)\s*$")
 
 def _line_opens_xml_fence(line: str) -> bool:
     stripped = line.strip()
-    if not stripped.startswith("```"):
+    if not stripped.startswith(TRIPLE_BACKTICK):
         return False
-    remainder = stripped[3:].strip()
+    fence_marker_length = len(TRIPLE_BACKTICK)
+    remainder = stripped[fence_marker_length:].strip()
     return remainder == "xml" or remainder.startswith("xml ")
 
-
 def _line_is_bare_fence_close(line: str) -> bool:
-    return line.strip() == "```"
-
+    return line.strip() == TRIPLE_BACKTICK
 
 def _line_opens_inner_markdown_fence(line: str) -> bool:
     stripped = line.strip()
-    if not stripped.startswith("```"):
+    if not stripped.startswith(TRIPLE_BACKTICK):
         return False
-    return stripped != "```"
-
+    return stripped != TRIPLE_BACKTICK
+
+def _collect_inner_markdown_fence(
+    lines: list[str],
+    start_index: int,
+) -> tuple[list[str], int]:
+    inner_lines: list[str] = []
+    index = start_index
+    while index < len(lines):
+        current_line = lines[index]
+        inner_lines.append(current_line)
+        index += 1
+        if _line_is_bare_fence_close(current_line):
+            break
+    return inner_lines, index
+
+def _collect_xml_fence_body(
+    lines: list[str],
+    start_index: int,
+) -> tuple[list[str], int]:
+    body_lines: list[str] = []
+    index = start_index
+    while index < len(lines):
+        current_line = lines[index]
+        if _line_is_bare_fence_close(current_line):
+            return body_lines, index + 1
+        if _line_opens_inner_markdown_fence(current_line):
+            inner_lines, index = _collect_inner_markdown_fence(lines, index)
+            body_lines.extend(inner_lines)
+            continue
+        body_lines.append(current_line)
+        index += 1
+    return body_lines, index
 
 def extract_fenced_xml_content(text: str) -> str:
     """Extract bodies of ```xml fenced blocks.
@@ -50,31 +83,104 @@ def extract_fenced_xml_content(text: str) -> str:
     lines = text.splitlines()
     index = 0
     while index < len(lines):
-        if _line_opens_xml_fence(lines[index]):
+        if not _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
+        body_lines, index = _collect_xml_fence_body(lines, index + 1)
+        results.append("\n".join(body_lines))
     return "\n".join(results)
 
+def _line_is_audit_line(line: str) -> bool:
+    return AUDIT_LINE_PATTERN.match(line) is not None
+
+def _normalize_audit_line(line: str) -> str:
+    match = AUDIT_LINE_PATTERN.match(line)
+    if match:
+        return match.group(1).strip()
+    return line.strip()
+
+def _line_starts_exported_artifact(line: str) -> bool:
+    stripped = line.strip()
+    if not stripped:
+        return False
+    if _line_opens_xml_fence(stripped):
+        return True
+    exported_artifact_pattern = re.compile(
+        r"^<(\?xml\b|prompt\b|runtime_context\b|role\b|background\b|instructions\b|constraints\b|output_format\b|illustrations\b|open_question\b)",
+    )
+    return exported_artifact_pattern.match(stripped) is not None
+
+def _trim_trailing_blank_lines(lines: list[str]) -> list[str]:
+    trimmed = list(lines)
+    while trimmed and not trimmed[-1].strip():
+        trimmed.pop()
+    return trimmed
+
+def _trim_flattened_export_tail(lines: list[str]) -> list[str]:
+    trimmed = _trim_trailing_blank_lines(lines)
+    while trimmed and trimmed[-1].lstrip().startswith("✻ "):
+        trimmed.pop()
+        trimmed = _trim_trailing_blank_lines(trimmed)
+    return trimmed
+
+def _find_last_audit_index(lines: list[str]) -> int | None:
+    last_audit_index: int | None = None
+    for index, line in enumerate(lines):
+        if _line_is_audit_line(line):
+            last_audit_index = index
+    return last_audit_index
+
+def _find_first_artifact_index(lines: list[str]) -> int | None:
+    for index, line in enumerate(lines):
+        if _line_starts_exported_artifact(line):
+            return index
+    return None
+
+def _rebuild_from_existing_fence(audit_line: str, artifact_text: str) -> str:
+    fenced_body = extract_fenced_xml_content(artifact_text).strip()
+    if not fenced_body:
+        return audit_line
+    return f"{audit_line}\n```xml\n{fenced_body}\n```"
+
+def _rebuild_from_flattened_body(audit_line: str, artifact_text: str) -> str:
+    dedented_body = textwrap.dedent(artifact_text).strip("\n")
+    if not dedented_body:
+        return audit_line
+    return f"{audit_line}\n```xml\n{dedented_body}\n```"
+
+def _rebuild_canonical_export(audit_line: str, artifact_lines: list[str]) -> str:
+    if not artifact_lines:
+        return audit_line
+    artifact_text = "\n".join(artifact_lines).rstrip()
+    if _line_opens_xml_fence(artifact_lines[0]):
+        return _rebuild_from_existing_fence(audit_line, artifact_text)
+    return _rebuild_from_flattened_body(audit_line, artifact_text)
+
+def normalize_prompt_workflow_export(text: str) -> str:
+    """Return the last successful Audit + fenced XML pair from a message or export.
+
+    Saved transcript exports can flatten blocked retry turns and strip the outer
+    ``xml`` fence. This helper keeps only the last successful ``Audit:`` attempt
+    and rebuilds the canonical audit-plus-fence shape used by prompt-workflow
+    hooks and reviewers.
+    """
+    lines = text.splitlines()
+    last_audit_index = _find_last_audit_index(lines)
+    if last_audit_index is None:
+        return text.strip()
+    audit_line = _normalize_audit_line(lines[last_audit_index])
+    artifact_index = _find_first_artifact_index(lines[last_audit_index + 1 :])
+    if artifact_index is None:
+        return audit_line
+    artifact_lines = _trim_flattened_export_tail(
+        lines[last_audit_index + 1 + artifact_index :],
+    )
+    return _rebuild_canonical_export(audit_line, artifact_lines)
+
+def extract_fenced_xml_content_from_export(text: str) -> str:
+    """Extract fenced XML from a canonical message or flattened transcript export."""
+    normalized = normalize_prompt_workflow_export(text)
+    return extract_fenced_xml_content(normalized)
 
 def missing_required_xml_sections(text: str) -> list[str]:
     fenced_body = extract_fenced_xml_content(text)
@@ -88,6 +194,30 @@ def missing_required_xml_sections(text: str) -> list[str]:
             missing_sections.append(section_name)
     return missing_sections
 
+def _build_negative_keyword_violation(
+    match: re.Match[str],
+    line_number: int,
+    line_text: str,
+) -> dict[str, str | int]:
+    return {
+        "keyword": match.group(),
+        "line_number": line_number,
+        "line_text": line_text.strip(),
+    }
+
+def _find_pattern_violations(
+    patterns: Iterable[re.Pattern[str]],
+    line_text: str,
+    line_number: int,
+) -> list[dict[str, str | int]]:
+    violations: list[dict[str, str | int]] = []
+    for pattern in patterns:
+        match = pattern.search(line_text)
+        if match:
+            violations.append(
+                _build_negative_keyword_violation(match, line_number, line_text),
+            )
+    return violations
 
 def find_negative_keywords_in_fenced_xml(
     text: str,
@@ -95,45 +225,37 @@ def find_negative_keywords_in_fenced_xml(
     fenced_content = extract_fenced_xml_content(text)
     if not fenced_content:
         return []
-    fenced_lines = fenced_content.splitlines()
     all_violations: list[dict[str, str | int]] = []
-    for line_index, each_line in enumerate(fenced_lines):
-        for each_pattern in COMPILED_NEGATIVE_KEYWORD_PATTERNS:
-            each_match = each_pattern.search(each_line)
-            if each_match:
-                all_violations.append({
-                    "keyword": each_match.group(),
-                    "line_number": line_index + 1,
-                    "line_text": each_line.strip(),
-                })
-        for each_pattern in COMPILED_NEGATIVE_INDIRECT_PATTERNS:
-            each_match = each_pattern.search(each_line)
-            if each_match:
-                all_violations.append({
-                    "keyword": each_match.group(),
-                    "line_number": line_index + 1,
-                    "line_text": each_line.strip(),
-                })
+    for line_index, each_line in enumerate(fenced_content.splitlines(), start=1):
+        all_violations.extend(
+            _find_pattern_violations(
+                COMPILED_NEGATIVE_KEYWORD_PATTERNS,
+                each_line,
+                line_index,
+            ),
+        )
+        all_violations.extend(
+            _find_pattern_violations(
+                COMPILED_NEGATIVE_INDIRECT_PATTERNS,
+                each_line,
+                line_index,
+            ),
+        )
     return all_violations
 
-
 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_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 []
@@ -144,16 +266,13 @@ def find_ambiguous_scope_terms(text: str) -> list[str]:
             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 = [
@@ -161,7 +280,6 @@ def is_prompt_workflow_response(text: str) -> bool:
     ]
     return len(matched_markers) >= 2
 
-
 def missing_context_control_signals(text: str) -> list[str]:
     required_signals: tuple[str, ...] = (
         "base_minimal_instruction_layer: true",

package/hooks/blocking/test_prompt_workflow_gate_core.py

@@ -2,6 +2,7 @@
 
 from prompt_workflow_gate_core import (
     extract_fenced_xml_content,
+    extract_fenced_xml_content_from_export,
     find_ambiguous_scope_terms,
     has_checklist_container,
     has_internal_object_leak,
@@ -10,31 +11,27 @@ from prompt_workflow_gate_core import (
     missing_checklist_rows,
     missing_required_xml_sections,
     missing_scope_anchors,
+    normalize_prompt_workflow_export,
 )
 
-
 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"
@@ -43,22 +40,36 @@ def test_prompt_workflow_response_detection() -> None:
     )
     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
 
-
 def _fenced_xml(body: str) -> str:
     return f"```xml\n{body}\n```"
 
+def _runtime_context_lines() -> tuple[str, ...]:
+    return (
+        "<runtime_context>",
+        "base_minimal_instruction_layer: true",
+        "on_demand_skill_loading: true",
+        "</runtime_context>",
+        "",
+    )
+
+def _flattened_transcript(*lines: str) -> str:
+    return "\n".join(lines) + "\n"
+
+def _flattened_attempt(*body_lines: str, audit_line: str = "Audit: pass 15/15") -> str:
+    flattened_lines = [audit_line, ""]
+    for line in body_lines:
+        flattened_lines.append(f"  {line}" if line else "")
+    return "\n".join(flattened_lines)
 
 def test_missing_required_xml_sections_all_present_returns_empty() -> None:
     body = (
@@ -70,7 +81,6 @@ def test_missing_required_xml_sections_all_present_returns_empty() -> None:
     )
     assert missing_required_xml_sections(_fenced_xml(body)) == []
 
-
 def test_missing_required_xml_sections_missing_background() -> None:
     body = (
         "<role>R.</role>\n"
@@ -80,7 +90,6 @@ def test_missing_required_xml_sections_missing_background() -> None:
     )
     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"
@@ -90,11 +99,9 @@ def test_missing_required_xml_sections_missing_role_and_output_format() -> None:
     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"
@@ -105,7 +112,6 @@ def test_missing_required_xml_sections_prose_without_tags_counts_as_missing() ->
     )
     assert missing_required_xml_sections(_fenced_xml(body)) == ["background"]
 
-
 def test_extract_fenced_xml_preserves_content_after_nested_inner_fence() -> None:
     message = (
         "```xml\n"
@@ -122,3 +128,68 @@ def test_extract_fenced_xml_preserves_content_after_nested_inner_fence() -> None
     extracted = extract_fenced_xml_content(message)
     assert "</illustrations>" in extracted
     assert "<background>B</background>" in extracted
+
+def test_normalize_prompt_workflow_export_rebuilds_fence_from_flattened_transcript() -> None:
+    transcript = _flattened_transcript(
+        _flattened_attempt(
+            *_runtime_context_lines(),
+            "<role>R</role>",
+            "<background>B</background>",
+            "<instructions>I</instructions>",
+            "<constraints>C</constraints>",
+            "<output_format>O</output_format>",
+            "✻ Worked for 1m 7s",
+            audit_line="● Audit: pass 15/15",
+        ),
+    )
+    normalized = normalize_prompt_workflow_export(transcript)
+    assert normalized.startswith("Audit: pass 15/15\n```xml\n")
+    assert normalized.endswith("\n```")
+    assert "<runtime_context>" in normalized
+    assert "✻ Worked for 1m 7s" not in normalized
+
+def test_normalize_prompt_workflow_export_uses_last_audit_attempt() -> None:
+    first_attempt = _flattened_attempt(
+        "<role>FIRST</role>",
+        "<background>Old</background>",
+        "<instructions>Old</instructions>",
+        "<constraints>Old</constraints>",
+        "<output_format>Old</output_format>",
+        audit_line="● Audit: pass 15/15",
+    )
+    second_attempt = _flattened_attempt(
+        *_runtime_context_lines(),
+        "<role>FINAL</role>",
+        "<background>Fresh</background>",
+        "<instructions>I</instructions>",
+        "<constraints>C</constraints>",
+        "<output_format>O</output_format>",
+        "✻ Worked for 2m 8s",
+    )
+    transcript = _flattened_transcript(
+        first_attempt,
+        "",
+        "● Re-emitting the full artifact with the runtime signals added.",
+        "",
+        second_attempt,
+    )
+    normalized = normalize_prompt_workflow_export(transcript)
+    assert "<role>FINAL</role>" in normalized
+    assert "<role>FIRST</role>" not in normalized
+
+def test_extract_fenced_xml_content_from_export_supports_flattened_transcript() -> None:
+    transcript = _flattened_transcript(
+        _flattened_attempt(
+            "<role>R</role>",
+            "<background>B</background>",
+            "<instructions>I</instructions>",
+            "<constraints>C</constraints>",
+            "<output_format>O</output_format>",
+            "✻ Worked for 31s",
+            audit_line="● Audit: pass 15/15",
+        ),
+    )
+    extracted = extract_fenced_xml_content_from_export(transcript)
+    assert extracted.startswith("<role>R</role>")
+    assert "<output_format>O</output_format>" in extracted
+    assert "Worked for" not in extracted

package/package.json

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

package/skills/prompt-generator/REFERENCE.md

@@ -217,8 +217,8 @@ Shape (field names stable for internal audit helpers and Stop-hook leak detectio
     "comparison_basis": "...",
     "completion_boundary": "..."
   },
-  "required_sections": ["role", "context", "instructions", "constraints", "output_format", "examples"],
-  "base_prompt_xml": "<role>...</role><context>...</context><instructions>...</instructions><constraints>...</constraints><examples>...</examples><output_format>...</output_format>",
+  "required_sections": ["role", "background", "instructions", "constraints", "output_format", "illustrations"],
+  "base_prompt_xml": "<role>...</role><background>...</background><instructions>...</instructions><constraints>...</constraints><illustrations>...</illustrations><output_format>...</output_format>",
   "section_scope_rule": "Each refiner edits exactly one section and returns sibling sections unchanged.",
   "section_output_contract": {
     "required_fields": ["improved_block", "rationale", "concise_diff"]

package/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md

@@ -28,11 +28,11 @@ Use this command:
      - `completion_boundary`
    - 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>`
+     - `<background>`
      - `<instructions>`
      - `<constraints>`
      - `<output_format>`
-     - `<examples>`
+     - `<illustrations>`
    - Includes internal refinement object with:
      - `pipeline_mode: internal_section_refinement_with_final_audit`
      - `required_sections` list with all six sections
@@ -129,7 +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`.
+   - **Section-presence gate (Stop)** — Block responses where the fenced XML artifact is missing any of the five required section tag pairs: `role`, `background`, `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.
@@ -149,7 +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)
+  - Missing required XML sections (`role`, `background`, `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