claude-dev-env 1.16.0 → 1.17.0

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

package/skills/prompt-generator/SKILL.md

@@ -23,6 +23,8 @@ description: >-
 
 **Eval contract:** The user-visible behavior this skill must satisfy is defined in `packages/claude-dev-env/skills/prompt-generator/TARGET_OUTPUT.md`. Automated evals live in `packages/claude-dev-env/skills/prompt-generator/evals/prompt-generator.json`.
 
+**Templates:** Under `packages/claude-dev-env/skills/prompt-generator/templates/`, `skill-from-ground-up.md` is the collaborative prompt for **net-new** checkpointed Agent Skill packages; `skill-refinement-package.md` is the sibling prompt for **existing-skill** multi-file refinements and package-aware polish. Skill-builder and skill-writer in this repo require implementers to use the matching template before checkpointed package work.
+
 **Terminology:** **Prompt artifact** — the full XML inside the single user-facing `xml` fence (the paste-ready handoff). **Scope block** — the five-key contract in §3A that grounds instructions. **Default refinement pipeline** — §10: base draft → section refine → merge → 15-row compliance audit → capped fixes (subagent-internal unless draft-only). **Light self-check** — §8: fast pre-return sanity pass (shape, tools, scope, patterns); *not* the compliance audit. **Compliance audit (15-row)** — §11: hook-keyed rows that set the `Audit: pass|fail` numerator. **Execution handoff** — `/agent-prompt` after explicit user intent to run work.
 
 **Hook-survival invariant (read first):** The fenced XML artifact is the primary deliverable and MUST survive Stop-hook retries. If a Stop hook rejects the response, only the surrounding audit summary and runtime signal scaffolding may change between retries—the XML inside the fence MUST be re-emitted in full on every retry. Recovery pattern: re-emit the complete fenced XML first, then adjust the audit line. Trimming, summarizing, or deferring the prompt artifact to satisfy a hook gate is forbidden.

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

@@ -72,10 +72,10 @@
       "prompt": "/prompt-generator Create a prompt for an agent that traces a routing bug across shared_utils/export_handler.py, orchestrator.py, and download_manager.py — find where extract_apk is called and whether it handles APK signature check failures",
       "files": ["packages/samsung-automation/shared_utils/export_handler.py"],
       "expected_behavior": [
-        "No tool_use blocks appear after the first fence marker of the prompt artifact",
+        "No tool_use blocks appear after the first fence marker of the canonical prompt artifact",
         "All Glob/Grep discovery calls precede the AskUserQuestion",
         "All AskUserQuestion interactions precede the fenced block",
-        "Prompt artifact emits in a single uninterrupted response"
+        "Review the last successful Audit + fenced xml pair; blocked retry attempts preserved by flattened transcript exports do not count as additional delivered artifacts"
       ]
     },
     {
@@ -85,7 +85,7 @@
       "prompt": "/prompt-generator Write a detailed agent-harness prompt for a TDD bug-fix workflow that traces a routing error across 5+ files, with state management for multi-window execution and structured test tracking",
       "files": [],
       "expected_behavior": [
-        "Opening fence has a matching closing fence",
+        "The canonical prompt artifact has one opening xml fence and one matching closing fence; flattened transcript exports are normalized to that same boundary before review",
         "Every XML tag properly opened and closed",
         "No truncation at numbered-list bullets (the Issue #41 failure mode)",
         "No mid-sentence cuts or incomplete sections",
@@ -102,8 +102,8 @@
         "Discovery tool calls attempt to locate scoring logic before prompt generation",
         "If resolved: prompt references concrete file paths from discovery",
         "If unresolved: prompt contains <open_question> in <background> for downstream agent",
-        "No re-entry to discovery after fenced block starts",
-        "AskUserQuestion may surface the uncertainty if discovery was inconclusive"
+        "No re-entry to discovery after the canonical artifact fence starts",
+        "AskUserQuestion may surface the uncertainty if discovery was inconclusive; when discovery resolves concrete paths before the artifact, absence of <open_question> is expected"
       ]
     },
     {