claude-dev-env 8.85.3 → 8.87.0

package/docs/decisions/deepstack-gate.md

@@ -0,0 +1,28 @@
+# DeepStack gate
+
+The first-task hook is the control. A rewrite ships only when `refusal_reason` in `hooks/session/deepen_role_gate.py` returns no reason. DeepStack, the wording rule, and the review rule cite this function. They do not restate it.
+
+## What the unchanged hook did
+
+Recorded before this gate edited `deepen_first_prompt.py`, with `CDE_DEEPEN_OUTPUT=json` on stdin.
+
+The paste path, a first task and no rewrite stub, printed `decision` `deepen`. The rewritten prompt restated the four question stems and ended by telling the same agent to do the job.
+
+The filled four-answer stub printed `decision` `deepen`. The rewritten prompt carried the four answer lines and no role lines.
+
+## What the gate refuses
+
+| Reason | When |
+|---|---|
+| `restates-four-questions` | The rewrite contains every canonical question stem. The paste path is this case. |
+| `missing-role-lines` | `SCOPE (role):`, `EXAMPLES (illustration only):`, or `ZOOM-IN BLOCKER:` is missing or blank. |
+| `example-noun-in-scope` | The scope line contains an example noun and `ZOOM-IN BLOCKER:` is `none`. |
+| `dropped-hard-constraint` | A bullet under `HARD CONSTRAINTS` in the task is absent as its own line in the rewrite. |
+
+Json mode prints `{"decision": "refuse", "reason": "..."}`. Rewrite mode and the command-hook path print nothing, so the prompt-submit mod leaves the submitted text in place.
+
+## Proof shape
+
+Run the hook on stdin with `CDE_DEEPEN_OUTPUT=json`. The paste path refuses. A role rewrite that leaves the example noun out deepens. Removing `refusal_reason` from `decide_first_prompt` lets the paste path deepen again, and `test_should_refuse_the_paste_path_as_the_known_bad` fails. The wrong twin puts the example noun in the scope line with `ZOOM-IN BLOCKER: none` and is refused.
+
+`hooks/session/grade_deepstack_replay.py` scores a fixture whose task names one failure as an example. It calls `refusal_reason` and does not rewrite.

package/docs/rule-guides/agent-board.md

@@ -4,7 +4,7 @@ Back to the [rules index](../../rules/index.md).
 
 ## In brief
 
-When `NTFY_SERVER` is set, the session can reach the agent board, an ntfy server. Read `board-rules.md` in the agent-channels repository and follow it. Name the sender project in every post title. On the first board use in a session, post `joined: <project>` to this project's channel from `projects.md`.
+When `NTFY_SERVER` is set, the session can reach the agent board, an ntfy server. Read `board-rules.md` in the repository your project instructions name and follow it. Name the sender project in every post title. On the first board use in a session, post `joined: <project>` to this project's channel from `projects.md`.
 
 **Enforcement:** none.
 
@@ -12,7 +12,7 @@ When `NTFY_SERVER` is set, the session can reach the agent board, an ntfy server
 
 ## Rule
 
-1. Find the agent-channels repository that your project instructions name. Attach it with the `mcp__claude-code-remote__add_repo` tool if the session lacks it.
+1. Find the repository your project instructions name for the board. Attach it with the `mcp__claude-code-remote__add_repo` tool if the session lacks it.
 2. Read `board-rules.md` and the README in the attached checkout. When `board-rules.md` is missing, skip the board and say so in the report. Follow `board-rules.md` for every post and every listen. The README section "How to listen" has the listen commands. These rules rank above `board-rules.md`.
 3. Take the project name from your project instructions. When they name no project, ask your coordinator with `send_message` and wait for the answer before you post. A session with no coordinator skips the board and says so in its report.
 4. Every project shares one board token, so the token does not name the sender. Do not call `/v1/account` to find the project name.

package/docs/rule-guides/explore-thoroughly.md

@@ -6,7 +6,7 @@ Back to the [rules index](../../rules/index.md).
 
 **When:** Before you log, plan, delegate, or build an ask, or choose an approach.
 
-Search for what already does the ask, in full or in part. When something exists, stop and report it to the user in four points; run the `search-before-acting` skill. Then read files, patterns, and constraints, scaled to risk. Once the files, constraints, and success condition are known, act without repeating settled research.
+Search for what already does the ask, in full or in part. When something exists, report it to the user in four points and run the `search-before-acting` skill. When the role-level job is already authorized, continue that job. Then read files, patterns, and constraints, scaled to risk. Once the files, constraints, and success condition are known, act without repeating settled research.
 
 **Enforcement:** the pull request gate denies a body with no "Existing work" section.
 
@@ -18,7 +18,7 @@ Note: This deliberately chooses exploration depth over the "commit and execute q
 
 Before you log, plan, delegate, or build an ask, search for what already does it in full or in part. An ask is any request for new or changed behavior, a tool, a check, a workflow, a report, a tracker entry, or a plan. The `search-before-acting` skill holds the search places, the four-point report, and a playbook for each next move.
 
-When the search finds something, stop before you act and report what exists and where, what it covers of the ask, what is missing, and what the addition would add. When it covers the whole ask, tell the user they already have it. When the search finds nothing, say where you looked and continue.
+When the search finds something, report what exists and where, what it covers of the ask, what is missing, and what the addition would add. When the role-level job is already authorized, continue that job. When it covers the whole ask, tell the user they already have it. When the search finds nothing, say where you looked and continue.
 
 [`prefer-existing-tools.md`](../../rules/prefer-existing-tools.md) and [`build-needs-a-user.md`](../../rules/build-needs-a-user.md) load only when a session touches a script, hook, or manifest path. This rule loads in every session, so the search comes before the plan is set.
 

package/docs/rule-guides/features-start-with-an-eval.md

@@ -4,7 +4,7 @@ Back to the [rules index](../../rules/index.md).
 
 ## In brief
 
-Your first action is the Skill tool with skill `claude-api` and args `build-eval`. Build the feature against that eval. When the work touches an existing feature with no eval, start a separate session to build that eval in parallel. An Agent-tool subagent does not count. You own its result.
+The DeepStack reproducible-check leaf calls this guide when the work is a new feature or a change in behavior. Only the forced position as the very first action is retired. A reproducible, re-runnable check is still required before any done claim. Red before the fix, the wrong twin fails, and undo fails again. Build the feature against that eval. When the work touches an existing feature with no eval, start a separate session to build that eval in parallel. An Agent-tool subagent does not count. You own its result.
 
 **Enforcement:** `hooks/blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file before the build-eval call. `hooks/blocking/pr_lifecycle_skill_gate.py` denies a `feat` pull request with no "Eval" section or no build-eval call.
 
@@ -18,7 +18,7 @@ An eval is three things for one feature: a set of input cases with their expecte
 
 ## Rule
 
-1. Make the Skill tool call with skill `claude-api` and args `build-eval` your first action on the ask. A user who types `/claude-api build-eval` has made the same call.
+1. Call the Skill tool with skill `claude-api` and args `build-eval` before the change. A user who types `/claude-api build-eval` has made the same call. A reproducible, re-runnable check is still required before any done claim. Red before the fix, the wrong twin fails, and undo fails again. Only the forced position as the very first action is retired.
 2. Run the existing-work search from [`explore-thoroughly.md`](explore-thoroughly.md) next. The guide's own first step also looks for cases, graders, and runners that exist.
 3. Follow the guide the skill loads. It asks the user to approve the inputs and the grading method, and to approve the cost before the first paid run. Ask through the session's question tool. Where the host says to keep working while a question waits, continue on the option you recommended and change course if the answer differs.
 4. Run the eval before the change to get a baseline, build the feature, and run it again.

package/docs/second-claude-account.md

@@ -9,7 +9,7 @@ keeps its own sign-in and history.
 | File | What it does |
 |---|---|
 | `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
-| `scripts/account_broker.py` | Reads the account roster and usage meters, chooses an account, and runs Claude with that account's home |
+| `scripts/account_broker.py` | Reads the account list and usage meters, chooses an account, and runs Claude with that account's home |
 | `scripts/claude_account_worker.py` | Runs one headless Claude worker through the broker |
 | `scripts/claude_account_worker_process.py` | Sends the brief to the broker and measures the run |
 | `scripts/claude_account_worker_report.py` | Builds and writes the JSON report a worker leaves behind |

package/hooks/features/session-context.md

@@ -32,7 +32,7 @@ Preconditions:
 - **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
-- **First-task deepen.** Input is a first UserPromptSubmit task. Run `python -m pytest packages/claude-dev-env/hooks/session/test_deepen_first_prompt.py -q`. The adjacent test observes a skip table and a rewrite that names the four omitted answers.
+- **First-task deepen.** Input is a first UserPromptSubmit task. Run `python -m pytest packages/claude-dev-env/hooks/session/test_deepen_first_prompt.py -q`. The adjacent test observes a skip table, a refusal of the paste path, and a rewrite that carries the SCOPE, EXAMPLES, and ZOOM-IN BLOCKER lines.
 - **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 

package/hooks/hooks_constants/deepen_first_prompt_constants.py

@@ -26,6 +26,22 @@ __all__ = [
     "DEEPEN_OUTPUT_JSON",
     "DEEPEN_OUTPUT_REWRITE",
     "DEEPEN_REWRITE_ENV_VAR",
+    "ALL_EXAMPLE_NOUN_STOPWORDS",
+    "ALL_FOUR_QUESTION_STEMS",
+    "EXAMPLE_NOUN_PATTERN",
+    "HARD_CONSTRAINTS_LABEL",
+    "REFUSAL_DROPPED_HARD_CONSTRAINT",
+    "REFUSAL_EXAMPLE_NOUN_IN_SCOPE",
+    "REFUSAL_MISSING_ROLE_LINES",
+    "REFUSAL_RESTATES_FOUR_QUESTIONS",
+    "ROLE_BLOCKER_LABEL",
+    "ROLE_BLOCKER_NONE",
+    "ROLE_EXAMPLES_LABEL",
+    "BULLET_PREFIX",
+    "QUESTION_LINE_SEPARATOR",
+    "SCORE_ACCEPT",
+    "SCORE_REFUSE",
+    "ROLE_SCOPE_LABEL",
     "DEEPEN_SLASH_COMMAND",
     "DEEPEN_TIMEOUT_SECONDS",
     "DEEPEN_TURN_MARKER_SUFFIX",
@@ -117,3 +133,47 @@ ALL_SPAWN_REWRITE_PREFIXES: tuple[str, ...] = (
     CLAUDE_SUBAGENT_PROMPT_PREFIX,
     CODEX_SUBAGENT_PROMPT_PREFIX,
 )
+
+ROLE_SCOPE_LABEL: str = "SCOPE (role):"
+ROLE_EXAMPLES_LABEL: str = "EXAMPLES (illustration only):"
+ROLE_BLOCKER_LABEL: str = "ZOOM-IN BLOCKER:"
+ROLE_BLOCKER_NONE: str = "none"
+HARD_CONSTRAINTS_LABEL: str = "HARD CONSTRAINTS"
+REFUSAL_RESTATES_FOUR_QUESTIONS: str = "restates-four-questions"
+REFUSAL_MISSING_ROLE_LINES: str = "missing-role-lines"
+REFUSAL_EXAMPLE_NOUN_IN_SCOPE: str = "example-noun-in-scope"
+REFUSAL_DROPPED_HARD_CONSTRAINT: str = "dropped-hard-constraint"
+BULLET_PREFIX: str = "- "
+QUESTION_LINE_SEPARATOR: str = "\n"
+SCORE_ACCEPT: str = "accept"
+SCORE_REFUSE: str = "refuse"
+EXAMPLE_NOUN_PATTERN: str = r"[A-Za-z][A-Za-z0-9_+-]{3,}"
+ALL_FOUR_QUESTION_STEMS: tuple[str, ...] = (
+    "What a top person in that field would do that this prompt omitted.",
+    "The raw source to start from.",
+    "The methods and tools they would use.",
+    "What besides the agent or Jon would show the result is right.",
+)
+ALL_EXAMPLE_NOUN_STOPWORDS: frozenset[str] = frozenset(
+    {
+        "none",
+        "the",
+        "and",
+        "for",
+        "with",
+        "from",
+        "that",
+        "this",
+        "only",
+        "illustration",
+        "example",
+        "into",
+        "when",
+        "your",
+        "their",
+        "about",
+        "such",
+        "like",
+        "say",
+    }
+)

package/hooks/hooks_constants/haiku_spawn_slim_gate_constants.py

@@ -7,23 +7,63 @@ the deny reason that gives the headless slim-profile command.
 from __future__ import annotations
 
 HAIKU_MODEL_FAMILY = "haiku"
+SLIM_PROFILE_NAME = "slim"
+SLIM_PROFILE_EXECUTABLE = "claude"
+SLIM_PROFILE_SETTINGS_JSON = (
+    '{"enabledPlugins": {}, "autoMemoryEnabled": false, "autoCompactWindow": 100000}'
+)
+SLIM_PROFILE_MCP_CONFIG_JSON = '{"mcpServers": {}}'
+SHELL_ARGUMENT_SEPARATOR = " "
+ENVIRONMENT_NAME_SEPARATOR = " and "
+JSON_ARGUMENT_PREFIX = "{"
+ALL_SLIM_PROFILE_ENVIRONMENT = (
+    "CLAUDE_CODE_DISABLE_CLAUDE_MDS=1",
+    "CLAUDE_CODE_DISABLE_AUTO_MEMORY=1",
+)
+ALL_SLIM_PROFILE_ARGUMENTS = (
+    "-p",
+    "--model",
+    HAIKU_MODEL_FAMILY,
+    "--setting-sources",
+    "local",
+    "--settings",
+    SLIM_PROFILE_SETTINGS_JSON,
+    "--strict-mcp-config",
+    "--mcp-config",
+    SLIM_PROFILE_MCP_CONFIG_JSON,
+    "--autocompact",
+    "100k",
+)
 HOOK_EVENT_NAME = "PreToolUse"
 TOOL_INPUT_KEY = "tool_input"
 MODEL_INPUT_KEY = "model"
 DENY_DECISION = "deny"
 PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+
+
+def _shell_argument(argument: str) -> str:
+    if argument.startswith(JSON_ARGUMENT_PREFIX):
+        return f"'{argument}'"
+    return argument
+
+
+SLIM_PROFILE_SHELL_COMMAND = SHELL_ARGUMENT_SEPARATOR.join(
+    (
+        SLIM_PROFILE_EXECUTABLE,
+        *(_shell_argument(each_argument) for each_argument in ALL_SLIM_PROFILE_ARGUMENTS),
+    )
+)
+SLIM_PROFILE_ENVIRONMENT_TEXT = ENVIRONMENT_NAME_SEPARATOR.join(ALL_SLIM_PROFILE_ENVIRONMENT)
 SLIM_PROFILE_DENY_REASON = (
     "BLOCKED: A Haiku agent started from this session runs with this session's settings, plugins, "
     "MCP servers, and CLAUDE.md files. An Agent, Task, or thread spawn has no field for setting sources, "
     "a plugin directory, or an MCP config, so it cannot load the slim profile. "
-    "Start Haiku as a headless run with the slim profile. Set CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 and "
-    "CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in the environment, then run this from Bash or another POSIX shell, "
+    "Start Haiku as a headless run with the slim profile. Set "
+    f"{SLIM_PROFILE_ENVIRONMENT_TEXT} in the environment, then run this from Bash or another POSIX shell, "
     "because PowerShell strips the double quotes inside the single-quoted JSON: "
     'python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <report.json> -- '
-    "claude -p --model haiku --setting-sources local "
-    '--settings \'{"enabledPlugins": {}, "autoMemoryEnabled": false, "autoCompactWindow": 100000}\' '
-    "--strict-mcp-config --mcp-config '{\"mcpServers\": {}}' --autocompact 100k. "
+    f"{SLIM_PROFILE_SHELL_COMMAND}. "
     "Send the task on standard input. In a cloud session, run the same claude -p command without the broker. "
-    "Where the efficient-review skill is installed, /efficient-review headless or /efficient-review auto builds "
-    "this profile. To keep the agent in this session, spawn it on opus or sonnet."
+    "Where the efficient-review skill is installed, its plan prints that claude -p command without the broker. "
+    "To keep the agent in this session, spawn it on opus or sonnet."
 )

package/hooks/session/deepen_first_prompt.py

@@ -26,6 +26,8 @@ if _hooks_dir not in sys.path:
 from hooks_constants.cloud_session import is_cloud_session
 from hooks_constants.deepen_first_prompt_constants import (
     ADDITIONAL_CONTEXT_KEY,
+    ALL_FOUR_QUESTION_STEMS,
+    QUESTION_LINE_SEPARATOR,
     ALL_HELPER_REPORT_MARKERS,
     ALL_LOOP_PROMPT_PREFIXES,
     ALL_NONINTERACTIVE_ENV_TRUE_VALUES,
@@ -63,6 +65,7 @@ from hooks_constants.deepen_first_prompt_constants import (
 from hooks_constants.mod_handoff import is_mod_plugin_enabled
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.subprocess_window import hidden_window_creation_flags
+from deepen_role_gate import refusal_reason
 
 
 class SkipReason(StrEnum):
@@ -94,7 +97,14 @@ class Deepen:
     additional_context: str
 
 
-DeepenDecision = Skip | Deepen
+@dataclass(frozen=True)
+class Refuse:
+    """Leave the submitted prompt unchanged because the candidate rewrite failed."""
+
+    reason: str
+
+
+DeepenDecision = Skip | Deepen | Refuse
 
 
 def submitted_prompt_text(all_hook_fields: dict[str, object]) -> str:
@@ -266,15 +276,17 @@ def _command_rewrite(task_text: str) -> str | None:
 
 
 def _default_rewrite(task_text: str) -> str:
+    """Return the paste path: the four question stems and an order to do the job."""
+    numbered_stems = QUESTION_LINE_SEPARATOR.join(
+        f"{each_index}. {each_stem}"
+        for each_index, each_stem in enumerate(ALL_FOUR_QUESTION_STEMS, start=1)
+    )
     return (
         f"{DEEPEN_MARKER}\n\n"
         "Do this task as a leading practitioner in its field would.\n\n"
         f"{task_text}\n\n"
         "Cover four things the original prompt left out:\n"
-        "1. What a top person in that field would do that this prompt omitted.\n"
-        "2. The raw source to start from.\n"
-        "3. The methods and tools they would use.\n"
-        "4. What besides the agent or Jon would show the result is right.\n"
+        f"{numbered_stems}\n"
         "Then do exactly that job."
     )
 
@@ -301,11 +313,15 @@ def additional_context_for(rewritten_prompt: str) -> str:
 
 
 def decide_first_prompt(all_hook_fields: dict[str, object]) -> DeepenDecision:
-    """Skip or deepen one UserPromptSubmit payload."""
+    """Skip, refuse, or deepen one UserPromptSubmit payload."""
     reason = skip_reason_for(all_hook_fields)
     if reason is not None:
         return Skip(reason)
-    rewritten_prompt = expand_first_task(submitted_prompt_text(all_hook_fields))
+    prompt = submitted_prompt_text(all_hook_fields)
+    rewritten_prompt = expand_first_task(prompt)
+    refusal = refusal_reason(task_text_for_deepen(prompt), rewritten_prompt)
+    if refusal is not None:
+        return Refuse(refusal)
     return Deepen(
         rewritten_prompt=rewritten_prompt,
         additional_context=additional_context_for(rewritten_prompt),
@@ -316,6 +332,10 @@ def _print_skip_json(reason: SkipReason) -> None:
     sys.stdout.write(json.dumps({"decision": "skip", "reason": reason.value}) + "\n")
 
 
+def _print_refuse_json(reason: str) -> None:
+    sys.stdout.write(json.dumps({"decision": "refuse", "reason": reason}) + "\n")
+
+
 def _print_deepen_json(deepen: Deepen) -> None:
     sys.stdout.write(
         json.dumps(
@@ -364,6 +384,10 @@ def emit_decision(decision: DeepenDecision, all_hook_fields: dict[str, object])
         if output_mode == DEEPEN_OUTPUT_JSON:
             _print_skip_json(decision.reason)
         return
+    if isinstance(decision, Refuse):
+        if output_mode == DEEPEN_OUTPUT_JSON:
+            _print_refuse_json(decision.reason)
+        return
     write_turn_marker(all_hook_fields)
     if output_mode == DEEPEN_OUTPUT_JSON:
         _print_deepen_json(decision)

package/hooks/session/deepen_role_gate.py

@@ -0,0 +1,171 @@
+"""Refusal checks for a first-task rewrite.
+
+The rewriter lives in ``deepen_first_prompt.py``. This module only scores a
+candidate. A grader imports ``refusal_reason`` and does not rewrite.
+"""
+
+from __future__ import annotations
+
+import re
+
+from hooks_constants.deepen_first_prompt_constants import (
+    ALL_EXAMPLE_NOUN_STOPWORDS,
+    ALL_FOUR_QUESTION_STEMS,
+    EXAMPLE_NOUN_PATTERN,
+    BULLET_PREFIX,
+    HARD_CONSTRAINTS_LABEL,
+    REFUSAL_DROPPED_HARD_CONSTRAINT,
+    REFUSAL_EXAMPLE_NOUN_IN_SCOPE,
+    REFUSAL_MISSING_ROLE_LINES,
+    REFUSAL_RESTATES_FOUR_QUESTIONS,
+    ROLE_BLOCKER_LABEL,
+    ROLE_BLOCKER_NONE,
+    ROLE_EXAMPLES_LABEL,
+    ROLE_SCOPE_LABEL,
+)
+
+
+def _labeled_text(rewritten_prompt: str, label: str) -> str | None:
+    """Return the text after ``label`` on its line, or None when the line is absent."""
+    prefix = label
+    for each_line in rewritten_prompt.splitlines():
+        stripped_line = each_line.strip()
+        if stripped_line.startswith(prefix):
+            return stripped_line[len(prefix) :].strip()
+    return None
+
+
+def _restates_four_questions(rewritten_prompt: str) -> bool:
+    """Return True when the rewrite pastes every canonical question stem."""
+    return all(each_stem in rewritten_prompt for each_stem in ALL_FOUR_QUESTION_STEMS)
+
+
+def _role_lines_are_missing(rewritten_prompt: str) -> bool:
+    """Return True when any of the three role lines is absent or blank."""
+    for each_label in (ROLE_SCOPE_LABEL, ROLE_EXAMPLES_LABEL, ROLE_BLOCKER_LABEL):
+        labeled_text = _labeled_text(rewritten_prompt, each_label)
+        if labeled_text is None or not labeled_text:
+            return True
+    return False
+
+
+def _example_nouns(examples_text: str) -> frozenset[str]:
+    """Return content words from the examples line. ``none`` yields an empty set."""
+    if examples_text.strip().rstrip(".").lower() == ROLE_BLOCKER_NONE:
+        return frozenset()
+    noun_pattern = re.compile(EXAMPLE_NOUN_PATTERN)
+    return frozenset(
+        each_match.group(0).lower()
+        for each_match in noun_pattern.finditer(examples_text)
+        if each_match.group(0).lower() not in ALL_EXAMPLE_NOUN_STOPWORDS
+    )
+
+
+def _scope_names_example_noun(scope_text: str, examples_text: str, blocker_text: str) -> bool:
+    """Return True when the scope line names an example noun and the blocker is none."""
+    if blocker_text.strip().rstrip(".").lower() != ROLE_BLOCKER_NONE:
+        return False
+    for each_noun in _example_nouns(examples_text):
+        if re.search(
+            rf"(?i)(?<![A-Za-z0-9]){re.escape(each_noun)}(?![A-Za-z0-9])",
+            scope_text,
+        ):
+            return True
+    return False
+
+
+def _is_constraints_heading(stripped_line: str) -> bool:
+    """Return whether the line opens the hard-constraints block."""
+    return stripped_line.upper().startswith(HARD_CONSTRAINTS_LABEL)
+
+
+def _bullet_body(stripped_line: str) -> str | None:
+    """Return the text after a bullet marker, or None when the line is not a bullet."""
+    if not stripped_line.startswith(BULLET_PREFIX):
+        return None
+    return stripped_line[len(BULLET_PREFIX) :].strip()
+
+
+def _constraint_step(
+    stripped_line: str,
+    collecting: bool,
+    has_sentences: bool,
+) -> tuple[str | None, bool, bool]:
+    """Return the sentence to keep, whether collection stays on, and whether to stop."""
+    if not collecting:
+        return None, _is_constraints_heading(stripped_line), False
+    bullet_body = _bullet_body(stripped_line)
+    if bullet_body is not None:
+        return bullet_body, True, False
+    if stripped_line == "" and not has_sentences:
+        return None, True, False
+    return None, collecting, True
+
+
+def _constraint_sentences(original_task: str) -> tuple[str, ...]:
+    """Return bullet sentences under the hard-constraints heading."""
+    collecting = False
+    all_sentences: list[str] = []
+    for each_line in original_task.splitlines():
+        sentence, collecting, finished = _constraint_step(
+            each_line.strip(),
+            collecting,
+            bool(all_sentences),
+        )
+        if finished:
+            break
+        if sentence is not None:
+            all_sentences.append(sentence)
+    return tuple(all_sentences)
+
+
+def _line_body(stripped_line: str) -> str | None:
+    """Return one rewrite line with a leading bullet marker removed."""
+    if not stripped_line:
+        return None
+    bullet_body = _bullet_body(stripped_line)
+    if bullet_body is not None:
+        return bullet_body
+    return stripped_line
+
+
+def _rewrite_line_bodies(rewritten_prompt: str) -> frozenset[str]:
+    """Return each rewrite line with a leading bullet marker removed."""
+    all_bodies: set[str] = set()
+    for each_line in rewritten_prompt.splitlines():
+        body = _line_body(each_line.strip())
+        if body is not None:
+            all_bodies.add(body)
+    return frozenset(all_bodies)
+
+
+def _dropped_hard_constraint(original_task: str, rewritten_prompt: str) -> bool:
+    """Return True when a hard-constraint sentence is absent as its own line."""
+    rewrite_bodies = _rewrite_line_bodies(rewritten_prompt)
+    return any(
+        each_sentence not in rewrite_bodies for each_sentence in _constraint_sentences(original_task)
+    )
+
+
+def refusal_reason(original_task: str, rewritten_prompt: str) -> str | None:
+    """Return the refusal reason for one candidate rewrite, or None when it can ship.
+
+    Args:
+        original_task: The task text the rewrite must keep constraints from.
+        rewritten_prompt: The candidate worker prompt.
+
+    Returns:
+        A refusal reason string, or None when the candidate passes.
+    """
+    if _restates_four_questions(rewritten_prompt):
+        return REFUSAL_RESTATES_FOUR_QUESTIONS
+    if _role_lines_are_missing(rewritten_prompt):
+        return REFUSAL_MISSING_ROLE_LINES
+    scope_text = _labeled_text(rewritten_prompt, ROLE_SCOPE_LABEL) or ""
+    examples_text = _labeled_text(rewritten_prompt, ROLE_EXAMPLES_LABEL) or ""
+    blocker_text = _labeled_text(rewritten_prompt, ROLE_BLOCKER_LABEL) or ""
+    if _scope_names_example_noun(scope_text, examples_text, blocker_text):
+        return REFUSAL_EXAMPLE_NOUN_IN_SCOPE
+    if _dropped_hard_constraint(original_task, rewritten_prompt):
+        return REFUSAL_DROPPED_HARD_CONSTRAINT
+    return None

package/hooks/session/fixtures/deepstack_replay.json

@@ -0,0 +1,15 @@
+{
+  "task": "Keep the build green. For example, the login failure.\n\nHARD CONSTRAINTS\n- Never open a pull request.\n",
+  "cases": [
+    {
+      "name": "known_bad",
+      "expect": "refuse",
+      "rewrittenPrompt": "CDE_DEEPEN:v1\nSCOPE (role): Fix the login failure\nEXAMPLES (illustration only): login failure\nZOOM-IN BLOCKER: none\n- Never open a pull request.\nRead the workflow log and repair the shared gate.\n"
+    },
+    {
+      "name": "known_good",
+      "expect": "accept",
+      "rewrittenPrompt": "CDE_DEEPEN:v1\nSCOPE (role): Keep every build green across the repository\nEXAMPLES (illustration only): login failure\nZOOM-IN BLOCKER: none\n- Never open a pull request.\nRead the workflow log and repair the shared gate.\n"
+    }
+  ]
+}

package/hooks/session/grade_deepstack_replay.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Score a replay fixture. This script does not rewrite the task."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+from deepen_role_gate import refusal_reason
+from hooks_constants.deepen_first_prompt_constants import (
+    SCORE_ACCEPT,
+    SCORE_REFUSE,
+    UTF8_ENCODING,
+)
+
+
+def score_replay(task_text: str, rewritten_prompt: str) -> dict[str, str]:
+    """Return accept, or refuse plus the gate reason. Never rewrite the task."""
+    reason = refusal_reason(task_text, rewritten_prompt)
+    if reason is None:
+        return {"score": SCORE_ACCEPT}
+    return {"score": SCORE_REFUSE, "reason": reason}
+
+
+def score_fixture(all_replay_fields: dict[str, object]) -> list[dict[str, str]]:
+    """Score each case in a replay fixture against the task it names."""
+    task_text = all_replay_fields["task"]
+    if not isinstance(task_text, str):
+        raise TypeError("fixture task must be a string")
+    cases = all_replay_fields["cases"]
+    if not isinstance(cases, list):
+        raise TypeError("fixture cases must be a list")
+    all_scores: list[dict[str, str]] = []
+    for each_case in cases:
+        if not isinstance(each_case, dict):
+            raise TypeError("each fixture case must be an object")
+        case_name = each_case["name"]
+        rewritten_prompt = each_case["rewrittenPrompt"]
+        expected_score = each_case["expect"]
+        if not isinstance(case_name, str) or not isinstance(rewritten_prompt, str):
+            raise TypeError("case name and rewrittenPrompt must be strings")
+        if not isinstance(expected_score, str):
+            raise TypeError("case expect must be a string")
+        scored = score_replay(task_text, rewritten_prompt)
+        scored["name"] = case_name
+        scored["expect"] = expected_score
+        scored["matched"] = "yes" if scored["score"] == expected_score else "no"
+        all_scores.append(scored)
+    return all_scores
+
+
+def main(all_arguments: list[str]) -> int:
+    """Read one fixture path and print a score line per case."""
+    if len(all_arguments) != 1:
+        sys.stderr.write("usage: grade_deepstack_replay.py <fixture.json>\n")
+        return 2
+    fixture_path = Path(all_arguments[0])
+    fixture = json.loads(fixture_path.read_text(encoding=UTF8_ENCODING))
+    if not isinstance(fixture, dict):
+        sys.stderr.write("fixture root must be an object\n")
+        return 2
+    all_scores = score_fixture(fixture)
+    for each_score in all_scores:
+        sys.stdout.write(json.dumps(each_score) + "\n")
+    if any(each_score["matched"] != "yes" for each_score in all_scores):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))