claude-dev-env 1.10.0 → 1.12.0

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

@@ -11,6 +11,7 @@ from pathlib import Path
 
 from prompt_workflow_gate_core import (
     find_ambiguous_scope_terms,
+    find_negative_keywords_in_fenced_xml,
     has_debug_intent,
     has_checklist_container,
     has_internal_object_leak,
@@ -130,6 +131,23 @@ def _check_ambiguous_scope(assistant_message: str) -> dict | None:
         ),
     )
 
+def _check_negative_keywords_in_artifact(assistant_message: str) -> dict | None:
+    violations = find_negative_keywords_in_fenced_xml(assistant_message)
+    if not violations:
+        return None
+    violation_descriptions = [
+        f"  line {each_violation['line_number']}: \"{each_violation['keyword']}\" in: {each_violation['line_text']}"
+        for each_violation in violations
+    ]
+    return _build_block(
+        brief_label="retrying: rephrase negative keywords in artifact",
+        full_reason=(
+            "PROMPT-WORKFLOW GATE: 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 _evaluate_workflow_gates(assistant_message: str) -> dict | None:
     if not is_prompt_workflow_response(assistant_message):
         return None
@@ -139,6 +157,7 @@ def _evaluate_workflow_gates(assistant_message: str) -> dict | None:
         _check_missing_scope_anchors,
         _check_missing_context_signals,
         _check_ambiguous_scope,
+        _check_negative_keywords_in_artifact,
     )
     for check in workflow_gate_checks:
         block = check(assistant_message)

package/hooks/blocking/prompt_workflow_gate_core.py

@@ -29,6 +29,7 @@ REQUIRED_CHECKLIST_ROWS: tuple[str, ...] = (
     "completion_boundary_measurable",
     "citation_grounding_policy_present",
     "source_priority_rules_present",
+    "artifact_language_confidence",
 )
 
 REQUIRED_CONTEXT_CONTROL_SIGNALS: tuple[str, ...] = (
@@ -80,6 +81,79 @@ DEBUG_INTENT_MARKERS: tuple[str, ...] = (
 )
 
 
+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 extract_fenced_xml_content(text: str) -> str:
+    all_matches = FENCED_XML_BLOCK_PATTERN.findall(text)
+    return "\n".join(all_matches)
+
+
+def find_negative_keywords_in_fenced_xml(
+    text: str,
+) -> list[dict[str, str | int]]:
+    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(),
+                })
+    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)

package/hooks/blocking/test_prompt_workflow_stop_guard.py

@@ -5,6 +5,8 @@ import subprocess
 import sys
 from pathlib import Path
 
+import pytest
+
 
 SCRIPT_PATH = Path(__file__).parent / "prompt-workflow-stop-guard.py"
 
@@ -34,6 +36,7 @@ def _full_checklist_rows() -> str:
         "- completion_boundary_measurable\n"
         "- citation_grounding_policy_present\n"
         "- source_priority_rules_present\n"
+        "- artifact_language_confidence\n"
     )
 
 def test_blocks_internal_object_leak_without_debug_intent() -> None:
@@ -117,6 +120,89 @@ def test_blocks_ambiguous_scope_phrasing() -> None:
     assert response["decision"] == "block"
     assert "Ambiguous scope phrasing detected" in response["reason"]
 
+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"
+    )
+
+
+def test_allows_positive_phrasing_inside_fenced_xml() -> None:
+    fenced_content = "<instructions>Ensure all functions have explicit return types.</instructions>"
+    payload = {
+        "last_assistant_message": _build_prompt_workflow_message_with_fenced_xml(fenced_content),
+    }
+    result = _run_hook(payload)
+    assert result.stdout.strip() == ""
+
+
+BANNED_KEYWORD_TEST_CASES: list[tuple[str, str]] = [
+    ("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>"),
+]
+
+
+@pytest.mark.parametrize(
+    ("banned_pattern_name", "fenced_xml_content"),
+    BANNED_KEYWORD_TEST_CASES,
+    ids=[each_case[0] for each_case in BANNED_KEYWORD_TEST_CASES],
+)
+def test_blocks_banned_pattern_inside_fenced_xml(
+    banned_pattern_name: str,
+    fenced_xml_content: str,
+) -> None:
+    payload = {
+        "last_assistant_message": _build_prompt_workflow_message_with_fenced_xml(fenced_xml_content),
+    }
+    result = _run_hook(payload)
+    response = json.loads(result.stdout)
+    assert response["decision"] == "block"
+
+
+def test_permits_negative_keywords_outside_fenced_xml() -> None:
+    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"
+        "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"
+    )
+    payload = {"last_assistant_message": message}
+    result = _run_hook(payload)
+    assert result.stdout.strip() == ""
+
+
 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.10.0",
+    "version": "1.12.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/prompt-generator/REFERENCE.md

@@ -11,6 +11,8 @@ When authoring or refining prompts, ground decisions in these sources. If guidan
 - https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026): 171 internal activation patterns that causally influence behavior. Key prompt-engineering takeaways: clear criteria and escape routes improve output quality, collaborative framing activates engagement, positive task framing correlates with better results, inviting transparency produces more reliable output. Cross-model caveat: studied on Sonnet 4.5; patterns align with best practices independently.
 - https://www.anthropic.com/research/emotion-concepts-function -- blog summary of the above paper.
 - https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking -- adaptive thinking reference; replaces manual budget_tokens with effort-based control.
+- https://claude.com/blog/harnessing-claudes-intelligence -- harness evolution: primitives Claude already knows, what to stop doing in the harness, deliberate boundaries (context economics, caching, typed tools). Local inventory: `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`.
+- https://github.com/anthropics/skills/tree/main/skills/claude-api -- Anthropic `claude-api` Agent Skill for hands-on API/tool patterns from that post (Hook 10). Platform entry: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill
 
 ### Tier 2: Major labs (strong secondary, often transfers across models)
 
@@ -37,6 +39,56 @@ When authoring or refining prompts, ground decisions in these sources. If guidan
 
 If sources disagree on a technique, apply in order: Anthropic documentation first (it describes the actual model behavior), then OpenAI/Google/Microsoft (large-scale research with cross-model relevance), then community sources (patterns and intuition, not authoritative on model internals). When Tier 3 contradicts Tier 1, Tier 1 wins without exception.
 
+## Harness design patterns (Anthropic blog, April 2026)
+
+Primary URL: https://claude.com/blog/harnessing-claudes-intelligence. Structured inventory: `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`.
+
+### Mechanism doc map (Hook 11)
+
+Jump from concept to the platform specs the post names:
+
+- [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) / [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool)
+- [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) / [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
+- [Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
+- [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+- [Context windows](https://platform.claude.com/docs/en/build-with-claude/context-windows) / [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) / [Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)
+- [Subagents](https://code.claude.com/docs/en/sub-agents)
+- [System prompts](https://platform.claude.com/docs/en/release-notes/system-prompts) / [Working with the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) / [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
+- [Model migration guide — hard-coded filters](https://platform.claude.com/docs/en/about-claude/models/migration-guide#additional-recommended-changes)
+- [Harness design for long-running applications](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Claude Code auto-mode](https://www.anthropic.com/engineering/claude-code-auto-mode)
+- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+
+### Context stack (Hook 5)
+
+- **Context editing:** Remove stale tool results and thinking blocks selectively ([Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing)).
+- **Subagents:** Fork fresh windows for isolated subtasks; post cites **+2.8%** BrowseComp vs best single-agent for Opus 4.6 ([Subagents](https://code.claude.com/docs/en/sub-agents)).
+- **Compaction:** Summarize prior context for long horizons ([Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)); effectiveness varies by model generation (see Hook 9 table).
+- **Memory folder:** Persist agent-chosen state via the memory tool / files ([Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)).
+
+### Prompt caching (Hook 6)
+
+The [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) is stateless—re-supply prior actions, tool definitions, and instructions each turn. Maximize [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits: **stable prefix first, dynamic tail last**; **append** new content via **messages** instead of rewriting the cached prompt; **avoid mid-session model switches** (caches are model-specific—use a **subagent** for a cheaper model); **treat the tool list as part of the cached prefix** and avoid churn; use **tool search** so dynamic discovery **appends** without invalidating the prefix; for multi-turn agents, **advance breakpoints** toward the latest message (**auto-caching**). Cached input tokens are priced at **10% of base input** per [pricing](https://platform.claude.com/docs/en/about-claude/pricing).
+
+### Typed tools vs bash strings (Hook 7)
+
+Promote actions to **dedicated tools** with typed arguments when the harness must intercept, gate, render (e.g., **modals**), or audit—**hard-to-reverse** steps (e.g., external API calls) for user confirmation; **write/edit** paths with **staleness checks** so concurrent edits are not blindly overwritten ([Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence)).
+
+### Standing review: dedicated tools vs general bash + policy (Hook 8)
+
+Re-evaluate promotions as models improve—e.g., Claude Code **auto-mode** (secondary reviewer over bash strings) can **reduce** bespoke tools **only** where users accept that trust profile; **high-stakes** actions still warrant dedicated tools ([Claude Code auto-mode](https://www.anthropic.com/engineering/claude-code-auto-mode)).
+
+### Benchmark vignettes — motivation only, not guarantees (Hook 9)
+
+| Vignette | Outcome stated in the post |
+|----------|----------------------------|
+| SWE-bench Verified | Claude 3.5 Sonnet **49%** with bash + editor only (then SOTA framing) |
+| BrowseComp + output filtering | Opus 4.6 **45.3% → 61.6%** |
+| BrowseComp + subagents | Opus 4.6 **+2.8%** vs best single-agent |
+| BrowseComp + compaction | Sonnet 4.5 **43%** flat; Opus 4.5 **68%**; Opus 4.6 **84%** (same setup) |
+| BrowseComp-Plus + memory folder | Sonnet 4.5 **60.4% → 67.2%** |
+| Prompt caching | Cached tokens **10%** the cost of base input tokens |
+
 ## NotebookLM Audio Overview customization (example)
 
 Adapt `[FOCUS AREA]` per notebook. Pair with Deep Dive + Longer in the product UI when that matches the user's plan.

package/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md

@@ -84,6 +84,7 @@ Audit report must include all check IDs:
 - `completion_boundary_measurable`
 - `citation_grounding_policy_present`
 - `source_priority_rules_present`
+- `artifact_language_confidence`
 
 ## Citation and Grounding Validation
 
@@ -134,6 +135,8 @@ Validate fail-closed runtime gates:
    - 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.
+   - Block responses containing negative keywords (no, not, don't, never, avoid, etc.) inside fenced XML artifacts.
+   - Block responses containing hedging language (might be, possibly, I think, etc.) inside fenced XML artifacts.
 
 ## Context-Footprint Controls
 
@@ -150,6 +153,8 @@ Validate fail-closed runtime gates:
   - Raw internal object leakage without debug intent
   - Missing required checklist rows in audit output
   - Ambiguous scope terms in scope-bound text
+  - Negative keywords inside fenced XML artifacts
+  - Hedging language inside fenced XML artifacts
 - **Semantic-only (auditor layer):**
   - Overall quality/readability of scope wording beyond banned-term checks
   - Whether instruction binding quality is "good enough" beyond explicit anchor presence

package/skills/prompt-generator/SKILL.md

@@ -19,15 +19,17 @@ description: >-
 
 **Canonical source:** https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices — the single reference for Claude's latest models. When sources conflict, defer to the authority tiers (Anthropic > major labs > community).
 
+**Harness hygiene:** Re-test harness assumptions about what Claude cannot do alone on each model generation or major product release—stale compensations bottleneck performance as capabilities improve (Hook 1; [Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence), inventory `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`).
+
 **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`.
 
-**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 → 14-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 (14-row)** — §11: hook-keyed rows that set the `Audit: pass|fail` numerator. **Execution handoff** — `/agent-prompt` after explicit user intent to run 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.
 
 **Turn shape:** Each orchestrator turn is either **AskUserQuestion** only (then wait for answers), or **`Audit: …` + exactly one `xml` fenced block** (then **send boundary**)—per `TARGET_OUTPUT.md`. Do not substitute free-form question paragraphs for AskUserQuestion; do not append commentary after the closing fence on the default path.
 
-**Happy path:** (1) Choose scenario **1–4** from the router table. (2) Run discovery when that scenario calls for repo tools. (3) Collect answers through **AskUserQuestion** (one form per round, **2–4** options per field, recommended first). (4) Subagent produces XML, runs **light self-check**, then **14-row compliance audit** + refinement loop. (5) Orchestrator prints **`Audit: pass 14/14`** or **`Audit: fail N/14 — [reason]`** and the **complete fenced XML**. (6) **Send boundary:** end the message immediately after the closing fence. (7) If the user names a debug phrase, append the full table / JSON per `TARGET_OUTPUT.md`.
+**Happy path:** (1) Choose scenario **1–4** from the router table. (2) Run discovery when that scenario calls for repo tools. (3) Collect answers through **AskUserQuestion** (one form per round, **2–4** options per field, recommended first). (4) Subagent produces XML, runs **light self-check**, then **15-row compliance audit** + refinement loop. (5) Orchestrator prints **`Audit: pass 15/15`** or **`Audit: fail N/15 — [reason]`** and the **complete fenced XML**. (6) **Send boundary:** end the message immediately after the closing fence. (7) If the user names a debug phrase, append the full table / JSON per `TARGET_OUTPUT.md`.
 
 **Clarity bar:** Ship concrete, outcome-first copy everywhere (AskUserQuestion fields, audit line, XML body): name *what* to do, *where* it applies, and *how* to verify done—per [Be clear and direct](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#be-clear-and-direct) and [Control the format of responses](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#control-the-format-of-responses). This skill **authors** prompts; downstream execution stays out of the default path until `/agent-prompt`.
 
@@ -37,7 +39,7 @@ description: >-
 
 **Hook-survival invariant:** Treat the fenced XML as the immutable payload for the user. On every Stop-hook retry, print the **same full** XML between the opening and closing fences; adjust only the one-line audit prefix (or other non-fence scaffolding) if a hook requires a format tweak. Re-emit the **entire** XML body before tweaking surrounding text—never shorten the artifact to pass a gate.
 
-**Orchestrator vs subagent:** The **orchestrator** runs ordered discovery, issues **AskUserQuestion**, and owns the **final** user-visible line: audit + fence. The **subagent** owns base draft, per-section refinement, merge, and the **14-row compliance audit**, returning **only** final XML plus pass/fail counts (no user-facing table)—unless the user asked for **draft-only** / **no refinement**, in which case you may draft inline with the same output shape. Keep hook retries internal; expose at most one short line such as `Retrying: scope anchor missing` before the successful audit + fence.
+**Orchestrator vs subagent:** The **orchestrator** runs ordered discovery, issues **AskUserQuestion**, and owns the **final** user-visible line: audit + fence. The **subagent** owns base draft, per-section refinement, merge, and the **15-row compliance audit**, returning **only** final XML plus pass/fail counts (no user-facing table)—unless the user asked for **draft-only** / **no refinement**, in which case you may draft inline with the same output shape. Keep hook retries internal; expose at most one short line such as `Retrying: scope anchor missing` before the successful audit + fence.
 
 **Interaction shape:** Route clarifications through **AskUserQuestion** only. Close each successful artifact turn with **audit line + one fenced XML block**; keep implementation plans **inside** that XML for the downstream consumer, not as a chat to-do list.
 
@@ -47,7 +49,7 @@ Match `TARGET_OUTPUT.md`. Summary:
 
 1. **Questions:** Use **AskUserQuestion** for every clarification (one multi-field form per round); keep normal assistant text free of standalone question paragraphs.
 2. **Options:** Supply **2–4** options per question, **recommended option first**; label discovery-sourced choices **`[discovered]`**.
-3. **Final message (exactly):** Line 1 = `Audit: pass 14/14` or `Audit: fail N/14 — [short reason]`; immediately after, output **one** Markdown code fence whose language tag is `xml` and whose body is the **complete** prompt; **send boundary** = right after that fence closes—the visible message is exactly those two consecutive blocks, copy-ready together, before any later user message.
+3. **Final message (exactly):** Line 1 = `Audit: pass 15/15` or `Audit: fail N/15 — [short reason]`; immediately after, output **one** Markdown code fence whose language tag is `xml` and whose body is the **complete** prompt; **send boundary** = right after that fence closes—the visible message is exactly those two consecutive blocks, copy-ready together, before any later user message.
 4. **Full audit table / JSON debug object:** Append only after the user uses an explicit debug phrase such as `show debug`, `full audit table`, or `raw internal object`.
 5. **Commit-and-execute:** Pick a drafting approach, run it to completion, ship the XML; change plans only when **new** facts from the user or tools contradict the earlier scope.
 
@@ -59,16 +61,17 @@ Match `TARGET_OUTPUT.md`. Summary:
 |----------|---------|-------------|-----------------|
 | **1 — Fresh brief goal** | `/prompt-generator` with short goal; little session context | **3–5** parallel Glob/Grep (or equivalent) **before** any question | **One** form, **2–4** questions |
 | **2 — Session handoff** | User wants a prompt so a **new** session can continue this thread | **Conversation only** — skip redundant repo tools for facts already stated | **One** form, **1–2** questions |
-| **3 — Long unstructured input** | Many requirements / paths in one message | Verify repo references (packages, shared utils, configs) with targeted tools **before** questions | First question **confirms extracted intent**; ambiguities as **specific** options |
+| **3 — Long unstructured input** | Many requirements / paths in one message | Verify repo references (packages, shared utils, configs) with targeted tools **before** questions | First question **confirms extracted intent**; ambiguities as **specific** options; **every** user-stated requirement captured in the generated XML by name — track all requirements from the unstructured input and confirm coverage before shipping |
 | **4 — Noisy context** | Long unrelated thread before `/prompt-generator` | Build the subagent brief from: the user’s literal `/prompt-generator` text, a **≤120-word** summary of on-topic facts, and discovery notes—**exclude** raw stack traces and unrelated tangents | As needed (often Scenario 1-shaped) |
 
-**Handoff (Scenario 2):** `<context>` must be **self-contained** — state, **decisions**, files touched, next steps, constraints — so a new session needs no prior chat.
+**Handoff (Scenario 2):** `<context>` must be **self-contained** — state, **decisions**, files touched, next steps, constraints — so a new session needs no prior chat. Preserve prior decisions verbatim in the handoff; quote the exact decision text where precision matters rather than paraphrasing it away.
 
 ## Phase ordering (structural invariant A)
 
 For the **final** user-visible turn that ships the artifact:
 
 - Compose the message as **audit line → opening fence → XML → closing fence → end**; keep the byte stream free of `tool_use` blocks **between** the opening and closing fences.
+- **Completeness:** End every numbered step inside `<instructions>` with a complete sentence and a fully written list item. Balance every XML tag explicitly (open and close each `<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`). The artifact must be copy-pasteable into a new file with zero manual repair.
 - Global pipeline: **discovery tools** (when applicable) → **AskUserQuestion** → **subagent** (draft + refinement + internal audit) → **one** orchestrator reply containing only audit line + fence.
 
 ## Interactive discovery mode (default)
@@ -91,9 +94,9 @@ Issue **one** AskUserQuestion with all fields populated from discovery and the u
 Spawn a **subagent** (Agent tool) with:
 
 - Scenario id (1–4), user goal, discovery summary, AskUserQuestion answers
-- Instruction: produce **one** well-formed XML prompt (required sections) + run the internal refinement loop and **14-row compliance audit**; return **only** the final XML string and a pass/fail + fail count for that audit (no user-facing table)
+- Instruction: produce **one** well-formed XML prompt (required sections) + run the internal refinement loop and **15-row compliance audit**; return **only** the final XML string and a pass/fail + fail count for that audit (no user-facing table)
 
-The orchestrator then prints **`Audit: pass 14/14`** or **`Audit: fail N/14 — [reason]`** immediately followed by the fenced XML. Keep subagent reasoning in the Agent transcript; the user-facing turn contains **only** audit + artifact.
+The orchestrator then prints **`Audit: pass 15/15`** or **`Audit: fail N/15 — [reason]`** immediately followed by the fenced XML. Keep subagent reasoning in the Agent transcript; the user-facing turn contains **only** audit + artifact.
 
 **Draft-only:** If the user explicitly requests no refinement (“quick draft”, “no refinement loop”), the subagent may skip Steps 10–12 below but must still return valid XML and a honest audit line.
 
@@ -109,7 +112,7 @@ Match specificity to task fragility:
 
 - **High:** Multiple valid approaches; numbered goals and acceptance criteria.
 - **Medium:** Preferred pattern exists; pseudocode or parameterised template.
-- **Low:** Fragile or safety-critical; numbered steps with explicit file paths, command names, and **allowed / disallowed action lists** (e.g. “Allowed: `pytest packages/foo/tests`; Disallowed: `git push --force` without user approval”).
+- **Low:** Fragile or safety-critical; numbered steps with explicit file paths, command names, and **permitted-action-only lists** (e.g. “Permitted: `pytest packages/foo/tests`; requires explicit user approval before: `git push --force`”).
 
 ### 3. Collect required missing facts
 
@@ -131,13 +134,13 @@ Use this scope block as the grounding contract for all generated instructions. E
 
 Apply principles from Anthropic’s prompting guide (see REFERENCE.md): XML sections, role, motivation in `<context>`, positive framing, emotion-informed collaborative tone where appropriate, **commit-and-execute** for multi-step agent prompts.
 
-**Structural invariant D:** Write `<instructions>` / `<constraints>` as direct imperatives (“Open `path/to/file.ts` and …”). Park unresolved items in `<open_question>` tags—one distinct question per tag with the exact decision you need.
+**Structural invariant D:** Write `<instructions>` / `<constraints>` as direct imperatives (“Open `path/to/file.ts` and …”). Park unresolved items in `<open_question>` tags—one distinct question per tag with the exact decision you need. Inside the fenced XML artifact, use only confident, definitive language: replace hedging phrases (“let me also check”, “actually”, “one more consideration”) and tentative qualifiers (“might be”, “possibly”, “I think”, “could be”) with direct assertions or move genuine uncertainty into `<open_question>` tags.
 
 **Set a role** in the system prompt. Anthropic: "Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference."
 
 **Add motivation behind constraints** in `<context>`. Anthropic: "Providing context or motivation behind your instructions... can help Claude better understand your goals and deliver more targeted responses." Claude generalizes from the explanation.
 
-**Frame positively.** Anthropic: state the desired outcome directly. "Your response should be composed of smoothly flowing prose paragraphs" provides clearer guidance than a prohibition-only instruction.
+**Frame positively (zero-negative-keyword rule).** Anthropic: state the desired outcome directly. "Your response should be composed of smoothly flowing prose paragraphs" provides clearer guidance than a prohibition-only instruction. Apply this rule absolutely inside the fenced XML artifact across all sections (`<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`): every instruction states what to do, what to produce, what to enforce. Use affirmative directives exclusively: "only X", "always X", "ensure X", "require X." Banned keywords inside generated XML: "no", "not", "don't", "do not", "never", "avoid", "without", "refrain", "stop", "prevent", "exclude", "prohibit", "forbid", "reject", "cannot", "unless." Also banned: indirect negative patterns such as "instead of X", "rather than X", "as opposed to." Example pass: "Ensure all functions have explicit return types." Example fail: "Do not leave return types implicit." When a boundary is needed, phrase it as what is permitted: "only run commands within the scoped paths" rather than a prohibition.
 
 **Emotion-informed framing.** Anthropic's emotion concepts research (2026) shows that internal activation patterns causally influence output quality. Apply: explicit success criteria with "say so if you're unsure" as an accepted answer; collaborative language ("help figure out", "work on this together"); framing tasks as interesting problems rather than chores; constructive, forward-looking tone. Cross-model caveat: studied on Sonnet 4.5; the patterns align with Anthropic's prompting best practices independently. Full pattern catalog and citations: `packages/claude-dev-env/docs/emotion-informed-prompt-design.md`.
 
@@ -145,6 +148,12 @@ Apply principles from Anthropic’s prompting guide (see REFERENCE.md): XML sect
 
 **Commit-and-execute pattern.** Anthropic: "When you're deciding how to approach a problem, choose an approach and commit to it. Avoid revisiting decisions unless you encounter new information that directly contradicts your reasoning." For prompts that guide agents through multi-step work, include this pattern so the agent doesn't spin revisiting decisions.
 
+**Tool-return policy (agent-harness / tool-use prompts):** Require explicit justification before the harness tokenizes full tool outputs; when the next hop needs only a slice or a tool-to-tool handoff, steer authors toward code execution (bash/REPL) so only execution output reaches model-visible context—not every intermediate payload (Hook 2; [Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence)).
+
+**Bash + text-editor foundation:** Prefer bash and the text editor for file work; treat Agent Skills, programmatic tool calling, and the memory tool as compositions of those primitives—state which primitive stack the harness assumes (Hook 3; same post).
+
+**Progressive disclosure:** Avoid monolithic system prompts packed with rarely used task branches; keep short always-on summaries and load full bodies via a read path when relevant (skills YAML frontmatter pattern per [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)) (Hook 4; same post).
+
 **For long context** (20k+ tokens): put documents first, query/instructions last. Anthropic: "Queries at the end can improve response quality by up to 30% in tests." Ground responses in quotes from source material before analysis.
 
 ### 5. Control output format
@@ -161,7 +170,7 @@ For format- or tone-sensitive **generated** prompts, include 3–5 `<example>` b
 
 ### 8. Light self-check (subagent, pre-return)
 
-**Two-tier validation — tier 1:** Before the subagent returns XML, run a quick pass on output shape, tool phrasing, scope anchors, and safety / research / agentic patterns as applicable (see REFERENCE.md and patterns below). This **light self-check** is not interchangeable with the **14-row compliance audit** in §11; tier 2 supplies the hook-keyed pass/fail counts for the `Audit:` line.
+**Two-tier validation — tier 1:** Before the subagent returns XML, run a quick pass on output shape, tool phrasing, scope anchors, and safety / research / agentic patterns as applicable (see REFERENCE.md and patterns below). This **light self-check** is not interchangeable with the **15-row compliance audit** in §11; tier 2 supplies the hook-keyed pass/fail counts for the `Audit:` line.
 
 Expand the light self-check with this internal checklist when useful:
 
@@ -172,6 +181,7 @@ Expand the light self-check with this internal checklist when useful:
 - [ ] **Code prompts** include read-before-claim grounding ("read files first; say 'I don't know' when uncertain") and anti-test-fixation (general solutions, flag bad tests)
 - [ ] **Research prompts** include the structured-investigation pattern with competing hypotheses, confidence tracking, and self-critique
 - [ ] **Agentic prompts** that span multiple context windows address state management (context awareness, multi-window workflow, structured state files)
+- [ ] **Agent-harness prompts** for long browse/search or multi-window work cite the context stack levers in **REFERENCE.md → Harness design patterns** (context editing, subagents, compaction, memory folder) (Hook 5)
 - [ ] 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)
@@ -181,10 +191,10 @@ Expand the light self-check with this internal checklist when useful:
 The orchestrator’s **only** delivery to the user is:
 
 ```text
-Audit: pass 14/14
+Audit: pass 15/15
 ```
 
-(or `fail N/14 — …`), 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.
+(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.
 
 ### 10. Default refinement mode (subagent-internal)
 
@@ -193,14 +203,14 @@ For non-trivial requests, run inside the drafting subagent (use **draft-only** w
 1. Base draft
 2. Section refinement in order: `role`, `context`, `instructions`, `constraints`, `output_format`, `examples` (examples optional if unused)
 3. Merge to one canonical XML prompt
-4. Final **14-row compliance audit** pass/fail with evidence (internal)
+4. Final **15-row compliance audit** pass/fail with evidence (internal)
 5. If fail: targeted fixes + capped re-audit rounds
 
 Required section list is immutable for this pipeline: `role`, `context`, `instructions`, `constraints`, `output_format`, `examples`.
 
-### 11. Compliance audit — 14-row checklist (internal, audit numerator)
+### 11. Compliance audit — 15-row checklist (internal, audit numerator)
 
-**Two-tier validation — tier 2:** The `14` in `Audit: pass 14/14` 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.
+**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.
 
 | # | Row name |
 |---|----------|
@@ -218,6 +228,7 @@ Required section list is immutable for this pipeline: `role`, `context`, `instru
 | 12 | completion_boundary_measurable |
 | 13 | citation_grounding_policy_present |
 | 14 | source_priority_rules_present |
+| 15 | artifact_language_confidence |
 
 For each row, maintain `status`, `evidence_quote`, `source_ref`, and `fix_if_fail` internally (see **REFERENCE.md** debug schema). A debug-path markdown table surfaces `status` and a one-phrase evidence summary. **Default user-visible path:** omit this table; **debug path:** after phrases like `show debug` or `full audit table`, print the table plus evidence snippets.
 
@@ -239,6 +250,7 @@ When the user explicitly asks for debug / full audit, emit the markdown table, `
 ### 14. Source anchors for pipeline requirements
 
 - Anthropic Prompting Best Practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
+- Harness economics (context stack, caching, typed tools, benchmarks): **REFERENCE.md → Harness design patterns**
 - Autonomy / reversibility / no safety-bypass: same + “Autonomy and safety pattern” below
 - Evidence-grounding / read-before-claim policy: `packages/claude-dev-env/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md`
 
@@ -280,14 +292,16 @@ For `agent-harness` and `tool-use` prompt types, embed this **reversibility ladd
 ```text
 Default: take local, reversible actions first—read files, run targeted tests, apply patches under paths the user scoped.
 
-Before running any command that deletes data, rewrites shared history, or notifies other people, stop and ask the user for explicit approval. Concrete categories:
+For commands that delete data, rewrite shared history, or notify other people, obtain explicit user approval first. Concrete categories requiring approval:
 - File or branch deletion, database drops, `rm -rf`
 - `git push --force`, `git reset --hard`, rewriting published commits
 - Pushes, PR comments, chat messages, or emails visible outside this workspace
 
-When tests fail or tooling blocks progress, prefer iterative fixes inside the allowed scope. Keep safety hooks (`--verify`, linters) enabled; surface unfamiliar files as questions instead of deleting them.
+When tests fail or tooling blocks progress, prefer iterative fixes inside the allowed scope. Keep safety hooks (`--verify`, linters) enabled; surface unfamiliar files as questions.
 ```
 
+**Positive rewrite guidance:** When embedding this pattern into a generated XML artifact, rephrase each line using affirmative directives only (per the zero-negative-keyword rule in §4). Example rewrite for generated output: "Prioritize local, reversible actions: read files, run targeted tests, apply patches within scoped paths. Obtain explicit user approval before running commands that delete data, rewrite shared history, or send external notifications. Keep safety hooks enabled (`--verify`, linters). Surface unfamiliar files as questions for the user."
+
 ## Research prompt pattern
 
 For `research` prompt types:
@@ -302,4 +316,6 @@ Search for this information in a structured way. As you gather data, develop sev
 2. **Tier 2:** OpenAI, Google DeepMind, Microsoft Research
 3. **Tier 3:** Community / blogs
 
+**Out-of-scope guard (Hook 12):** [Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence) and `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md` cover harness evolution, context economics, caching, and declarative boundaries—not a substitute for a full security threat model or product-specific compliance catalog unless paired with other Tier 1 or governance sources.
+
 Full links: `REFERENCE.md`.

package/skills/prompt-generator/TARGET_OUTPUT.md

@@ -9,7 +9,7 @@ This file is the **target output spec** for eval-driven iteration of the `prompt
 - **Clarity bar:** Every deliverable (AskUserQuestion fields, audit line, XML body) states concrete outcomes, explicit formats, and checkable done-when signals—aligned with Anthropic [Be clear and direct](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#be-clear-and-direct) and [Control the format of responses](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#control-the-format-of-responses). Prefer what to do and how to verify it over empty prohibitions or vague quality adjectives.
 - **Questions:** Deliver every clarifying question through **AskUserQuestion** (one form per round), with **2–4** options per question and the **recommended** option listed **first**. Tag discovery-sourced options **`[discovered]`** when they came from repo search.
 - **Final assistant message (complete handoff in one send):**
-  1. **Audit line:** `Audit: pass 14/14` or `Audit: fail N/14 — [reason]`
+  1. **Audit line:** `Audit: pass 15/15` or `Audit: fail N/15 — [reason]`
   2. **Artifact:** the full XML prompt inside **one** Markdown code fence whose language tag is `xml`
   3. **Send boundary:** stop typing as soon as the closing fence ends—the message body is exactly those two blocks back-to-back, ready to copy; your next tokens belong to the user’s following turn
 - **Full audit table / JSON debug bundle:** Stay internal until the user names debug with a phrase such as `show debug`, `full audit table`, or `raw internal object`; then append the table/JSON after the usual audit line + XML fence.
@@ -99,6 +99,6 @@ Include at least:
 
 Add `<examples>` when format or tone is easy to misunderstand; nest sections when the task has natural hierarchy.
 
-## Internal 14-row compliance checklist (audit numerator)
+## Internal 15-row compliance checklist (audit numerator)
 
-The `14` in `Audit: pass 14/14` maps to the named rows in `SKILL.md` (§11 **Compliance audit — 14-row checklist**), including `reversible_action_and_safety_check_guidance` and `scope_terms_explicit_and_anchored`. **Default user path:** keep the table internal; print the expanded table + JSON only after an explicit debug request. On failure, set the audit line to `Audit: fail N/14 — [primary theme]` where the theme names one concrete gap (e.g. `scope_block missing completion_boundary`, `output_format lacks acceptance checks`).
+The `15` in `Audit: pass 15/15` maps to the named rows in `SKILL.md` (§11 **Compliance audit — 15-row checklist**), including `reversible_action_and_safety_check_guidance` and `scope_terms_explicit_and_anchored`. **Default user path:** keep the table internal; print the expanded table + JSON only after an explicit debug request. On failure, set the audit line to `Audit: fail N/15 — [primary theme]` where the theme names one concrete gap (e.g. `scope_block missing completion_boundary`, `output_format lacks acceptance checks`).

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

@@ -118,6 +118,21 @@
         "All uncertainty expressed as <open_question> tags, not inline hedges",
         "Prompt reads as confident complete instructions, not a draft-in-progress"
       ]
+    },
+    {
+      "id": 9,
+      "name": "zero_negative_phrasing_in_output",
+      "scenario": "Content quality gate A (anti-pattern elimination)",
+      "prompt": "/prompt-generator Write a system prompt for an agent that reviews TypeScript code for type safety, enforces strict null checks, and ensures all function signatures have complete type annotations",
+      "files": [],
+      "expected_behavior": [
+        "Fenced prompt artifact contains zero hard anti-pattern keywords: 'no', 'not', 'don't', 'do not', 'never', 'avoid', 'without', 'refrain', 'stop', 'prevent', 'exclude', 'prohibit', 'forbid', 'reject'",
+        "Zero indirect anti-patterns: 'instead of X' (implies X is bad), 'rather than X', 'as opposed to'",
+        "Every instruction phrased as a positive directive: what TO do, what TO produce, what TO enforce",
+        "Constraints section uses affirmative boundaries: 'only X', 'always X', 'ensure X', 'require X' — positive framing throughout",
+        "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>"
+      ]
     }
   ]
 }