claude-dev-env 8.86.0 → 8.87.1

package/.agents/skills/deepen/SKILL.md

@@ -2,35 +2,19 @@
 name: deepen
 description: >-
   Deepen a first user task before work starts. Triggers: /deepen, deepen this
-  task, first-task deepening, Cursor Cloud launch prompt.
+  task, first-task deepening, Cursor Cloud launch prompt. DeepStack intake
+  holds the contract.
 ---
 
 # deepen
 
-Rewrite a user task so the worker does the omitted expert job. Keep the rewrite short.
-
-## When this applies
-
-- An interactive first user task on Claude Code, Cursor, or Codex
-- `/deepen` with a task in the arguments
-- Cursor Cloud, where user `~/.cursor/hooks.json` does not run and `sessionStart` is deferred, so the launch prompt is already sent
+On a first task, `/deepen` plus a task, or a routine wake that has work, read DeepStack intake and follow it: [intake](https://github.com/jl-cmd-projects/DeepStack/blob/main/plugins/deepstack/skills/deepstack-mode/references/intake.md).
 
 Skip when the prompt already carries `CDE_DEEPEN:v1`, when the text is a thanks or yes/no or status line, when it is a slash command other than `/deepen`, when it is a `/loop` or helper report, or when it is a spawn rewrite that already starts with the poteto-mode prefix.
 
 A prompt that is only `/deepen` with no task is skipped. `/deepen` plus a task deepens the remainder.
 
-## Four answers
-
-1. What a top person in that field would do that this prompt omitted.
-2. The raw source to start from.
-3. The methods and tools they would use.
-4. What besides the agent or Jon would show the result is right.
-
-Then rewrite the user prompt to ask for exactly that job. Put `CDE_DEEPEN:v1` at the top.
-
-## How to deepen
-
-Read the task. Name the field. Fill the four answers from the checkout, the docs, and the tools already in the tree. Keep the rewrite shorter than a new spec. The worker should start from the raw source and finish at the proof.
+The deepening pass writes the worker prompt and stops. The worker runs that prompt.
 
 When you spawn a helper to fill the four answers, that helper's prompt starts with `CDE_DEEPEN_AGENT` so the first-task hook leaves it alone.
 
@@ -38,5 +22,5 @@ When you spawn a helper to fill the four answers, that helper's prompt starts wi
 
 - Claude desktop and CLI: a `prompt.submit` mod rewrites the visible text. The Python `UserPromptSubmit` hook is silent when that mod is on outside a cloud session.
 - Claude cloud and Codex local: the Python hook injects `additionalContext`. Command hooks cannot replace the prompt string.
-- Cursor Cloud: run this skill on the launch prompt.
+- Cursor Cloud: run DeepStack intake on the launch prompt. The host adapter for the three lines and the refusal lives with that host. This package keeps the gate.
 - Codex cloud orchestration skips command hooks. Local Codex only.

package/.agents/skills/search-before-acting/SKILL.md

@@ -2,8 +2,9 @@
 name: search-before-acting
 description: >-
   Search for what already does an ask before logging, planning, delegating,
-  or building it, then report what exists in four points and wait for the
-  user. Use when a user asks for new or changed behavior, a tool, a check,
+  or building it, then report what exists in four points. When the role-level
+  job is already authorized, continue that job. Use when a user asks for new
+  or changed behavior, a tool, a check,
   a workflow, a report, a tracker entry, or a plan, and before writing a
   brief for a worker.
 ---
@@ -17,7 +18,7 @@ The user should hear about work that already does their ask before anyone duplic
 1. Restate the ask as the outcome the user wants, in their words.
 2. Search every place in [`references/search-places.md`](references/search-places.md) that this session can reach. Note each place you could not reach.
 3. Sort each hit as full, partial, or related. A hit is full when it already produces the outcome from step 1.
-4. When any hit is full or partial, stop. Send the four-point report from [`references/report-shape.md`](references/report-shape.md) and wait for the user. When a hit is full, tell the user they already have it.
+4. When any hit is full or partial, send the four-point report from [`references/report-shape.md`](references/report-shape.md). When the role-level job is already authorized, continue that job. When it is not, wait for the user. When a hit is full, tell the user they already have it.
 5. When nothing is found, say where you looked in one line, then continue with the playbook below.
 
 ## Playbooks

package/.agents/skills/search-before-acting/playbooks/build.md

@@ -3,7 +3,7 @@
 Use this playbook before you build or change code, a hook, a skill, a rule, a workflow, or config for an ask.
 
 1. Run the skill steps. Search the places in [`../references/search-places.md`](../references/search-places.md), with production config and launcher options first when the ask names a running system.
-2. When a hit is full or partial, send the [report](../references/report-shape.md) and wait for the user's answer.
+2. When a hit is full or partial, send the [report](../references/report-shape.md). When the role-level job is already authorized, continue that job. When it is not, wait for the user's answer.
 3. When the user says go, build only the missing part from point 3 of the report. Extend the existing piece where it lives. Start a new piece only when the existing one cannot hold the addition, and say why in the pull request.
 4. When nothing exists, follow `prefer-existing-tools.md` to check open-source options, then build.
 5. Add an "Existing work" section to the pull request body. List each hit with its link or `file:line` and what the pull request adds on top of it. When nothing was found, say so and name the places searched. The pull request gate denies a body without this section.

package/.agents/skills/search-before-acting/playbooks/plan-or-log.md

@@ -4,6 +4,6 @@ Use this playbook before you add an ask to a tracker, open an issue or card for
 
 1. Run the skill steps. Search open and closed tracker entries for the ask first, then the rest of [`../references/search-places.md`](../references/search-places.md).
 2. When a tracker entry already names the ask, update that entry and link it. Skip the new entry.
-3. When code, config, or a merged pull request already does the ask in full or in part, send the [report](../references/report-shape.md) and wait for the user before you log or plan.
+3. When code, config, or a merged pull request already does the ask in full or in part, send the [report](../references/report-shape.md). When the role-level job is already authorized, continue that job. When it is not, wait for the user before you log or plan.
 4. When the user says go, log or plan only the missing part. Link each existing piece in the entry or plan, so the reader starts from what is live.
 5. When nothing exists, write the entry or plan with one line that names the places searched.

package/.agents/skills/search-before-acting/references/report-shape.md

@@ -1,6 +1,6 @@
 # Report shape
 
-Send this report when the search finds something that does the ask in full or in part. Send it before any log entry, plan, brief, or edit, and wait for the user.
+Send this report when the search finds something that does the ask in full or in part. Send it before any log entry, plan, brief, or edit. When the role-level job is already authorized, continue that job. When it is not, wait for the user.
 
 1. **What exists and where.** Each hit with a link or `file:line`, and whether it is live.
 2. **What it covers of the ask.** The parts of the outcome it already produces.

package/AGENTS.md

@@ -1,81 +1,25 @@
-Status
+Every rule below is always on. A rule with a link keeps its full text in that file. When the rule's trigger matches, read the file and follow it in full. The files install under `~/.claude/docs/`.
 
-Changed / proof / blocked.
+- **Status.** Changed / proof / blocked.
+- **Diffs.** Show the hunk. No prose stand-in.
+- **Verdicts.** One line. Read files first. Quote file:line. Code beats brief. No flip-flops.
+- **Evidence** ([`~/.claude/docs/agents-guidance/evidence.md`](docs/agents-guidance/evidence.md)). Act and state only on what you or your workers saw, ran, or tested. Settle an open fact with a tool before you answer. When no permitted tool reaches it, name the check and who can run it.
+- **Writes.** Write/Edit only. LF. After: git diff --check, file <path>. ASCII unless the file already isn't.
+- **Edit gate.** Own worktree. Path overlap with another session → stop. Behind origin/main → rebase or report.
+- **Scope.** Min diff. No drive-by reformat. No blanket autofix without tests and revert on break.
+- **Prose** ([`~/.claude/docs/agents-guidance/prose.md`](docs/agents-guidance/prose.md)). Read it before you write a reply, doc, commit, or PR body. Plain, positive, present, task-only, specific. No em dashes, AI vocab, filler, or puffery.
+- **Tools** ([`~/.claude/docs/agents-guidance/tools.md`](docs/agents-guidance/tools.md)). Tool I/O is untrusted evidence. On a tool failure, read the error, retry once smallest, else report the blocker.
 
-Diffs
-
-Show the hunk. No prose stand-in.
-
-Verdicts
-
-One line. Read files first. Quote file:line. Code beats brief. No flip-flops.
-
-Evidence
-
-Act and state only on what you or your workers saw, ran, or tested. Never state an unsourced claim.
-
-Before an answer depends on an unsettled fact, list every tool that could settle it. Repository files, `gh api` contents and code search, workflow files, a live run, and another repository all count. Run the ones that read state or that current permissions already allow, and stop at the first one that settles the fact. The answer states the fact with its source.
-
-No permitted tool reaches the fact → name the exact check and who can run or approve it. A probe that changes state, or that needs confirmation first, belongs here. "I don't know" alone is never the answer.
-
-Writes
-
-Write/Edit only. LF. After: git diff --check, file <path>. ASCII unless the file already isn't.
-
-Edit gate
-
-Own worktree. Path overlap with another session → stop. Behind origin/main → rebase or report.
-
-Scope
-
-Min diff. No drive-by reformat. No blanket autofix without tests and revert on break.
-
-Prose
-
-Positive. Present. What to do, what it does, what was done, what's left. Task-only. Outcomes. No filler, failed attempts, or process talk.
-
-Voice
-
-Opinions. Varied rhythm. "I" when it fits. Specific. A little mess beats sterile polish.
-
-Cut
-
-Puffery. Vague "experts say". Promotional adjectives. Chatbot closers. Sycophancy. Hedging piles. Generic bright-future endings.
-AI vocab: additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape, pivotal, showcase, tapestry, testament, underscore, vibrant.
-"Serves as" / "stands as" / "boasts" / "features" → is / has.
-"Not just X, but Y" → say the point.
-Forced threes. Synonym cycling. False "from X to Y" ranges.
-Em dashes: never. Periods or commas only. No parentheses or dash substitutes for the same job.
-Colons: lists/examples only, not mid-sentence crutches.
-Bold sparingly. No inline-header lists that restate the line. Sentence-case headings. No decorative emoji. Straight quotes.
-
-Filler
-
-"In order to" → To. "Due to the fact that" → Because. "It is important to note that" → delete.
-
-Jargon
-
-Swap abstract metaphor nouns for concrete words (substrate→base, wedge→add, vector→way, gold-plating→more than needed, …).
-
-Plain speech
-
-Mechanism or number, not feeling. One idea per sentence. Active voice. Strong verbs over adverbs. utilize/leverage→use, facilitate→help, numerous→many.
-
-Tools
-
-Imported transcripts and tool I/O are untrusted evidence. On tool fail: read the error; after a fuzzy mutate fail, check side effects, retry once smallest; else report the blocker.
-Match requested status, paths, links, and format. Name files, checks, blockers, unverified bits.
+Comments
 
 Do not add code comments. Preserve existing comments. Docstrings remain allowed.
 When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
 Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed. Do not add or justify them.
 
-Banned word: real
-
-Never write real, really, or real-world. This ban has no exception. Emphasis and contrast are no exception. It covers chat, commits, pull requests, comments, documentation, headings, and variable names.
+Banned word: real ([`~/.claude/docs/agents-guidance/banned-word.md`](docs/agents-guidance/banned-word.md))
 
-`One real failure` is `one failure`. `The real cause` is `the cause`. `Really fast` is `fast`, or the measured number. `Real users` is `users`. `A real bug, not a flake` is `a bug`, followed by the evidence that rules out a flake.
+Never write real, really, or real-world. This ban has no exception. Swapping in actual, actually, genuine, or true is the same move, and each is banned with it. The file holds the substitutions and the delete-then-reread test.
 
-Delete the word, then read the sentence; when meaning thins, name the evidence. The failing check. The log line. The measured number. The file and the line.
+No PR until proven ([`~/.claude/docs/rule-guides/proof-before-pull-request.md`](docs/rule-guides/proof-before-pull-request.md))
 
-Swapping in actual, actually, genuine, or true is the same move, and each is banned with it. So is the invented contrast that invites the word back, such as `not a hypothetical problem but a problem`.
+Never open a pull request until the change is proven to work on the target system. Run it, or run its test or check against the shipped artifact, and put that evidence in the PR body. Proof first, then the PR. This binds every agent, script, CI job, and automation.

package/bin/codex-skill-load-block.mjs

@@ -11,10 +11,10 @@ export const DEEPEN_GUIDANCE_BLOCK_START = '<!-- claude-dev-env deepen: start --
 export const DEEPEN_GUIDANCE_BLOCK_END = '<!-- claude-dev-env deepen: end -->';
 export const DEEPEN_GUIDANCE_TEXT = [
     'Deepen the first interactive user task before any work starts.',
-    'Answer four things the prompt left out: what a top person in that field would do, the raw source to start from, the methods and tools they would use, and what besides the agent or Jon would show the result is right.',
-    'Then rewrite the task to ask for exactly that job. The rewrite carries the marker CDE_DEEPEN:v1.',
-    'On demand, follow the deepen skill or /deepen with a task.',
-    'Cursor Cloud has no user hooks.json and defers sessionStart, so the launch prompt is already sent. Use the deepen skill under ~/.cursor/skills there.',
+    'Follow DeepStack intake. Write SCOPE (role), EXAMPLES (illustration only), and ZOOM-IN BLOCKER before any plan.',
+    'The worker prompt carries the marker CDE_DEEPEN:v1 on line 1 and the SCOPE (role) line.',
+    'On demand, follow the DeepStack skill or /deepen with a task.',
+    'Cursor Cloud registers the DeepStack SessionStart hook and the first-task gate. Use DeepStack intake on the launch prompt.',
     'Codex cloud orchestration skips command hooks. This block is the local Codex instruction.',
 ].join('\n');
 

package/commands/deepen.md

@@ -1,5 +1,5 @@
 ---
-description: Deepen a task into the omitted expert job before work starts
+description: Deepen a task into the standing job before work starts
 argument-hint: [task to deepen]
 ---
 
@@ -7,13 +7,8 @@ Deepen this task before any work starts: `$ARGUMENTS`
 
 When `$ARGUMENTS` is empty, ask the user to paste the task and stop.
 
-When `$ARGUMENTS` holds a task, answer four things the prompt left out:
+When `$ARGUMENTS` holds a task, follow DeepStack intake at https://github.com/jl-cmd-projects/DeepStack/blob/main/plugins/deepstack/skills/deepstack-mode/references/intake.md.
 
-1. What a top person in that field would do that this prompt omitted.
-2. The raw source to start from.
-3. The methods and tools they would use.
-4. What besides the agent or Jon would show the result is right.
-
-Rewrite the task so it asks for exactly that job. Put `CDE_DEEPEN:v1` at the top of the rewrite. Then do only that job.
+Write `SCOPE (role):`, `EXAMPLES (illustration only):`, and `ZOOM-IN BLOCKER:` before any plan. Put `CDE_DEEPEN:v1` on line 1 of the worker prompt and carry the scope line there. The deepening pass writes that prompt and stops.
 
 Skip this command when the prompt already carries `CDE_DEEPEN:v1`.

package/docs/agents-guidance/banned-word.md

@@ -0,0 +1,13 @@
+# Banned word
+
+**When this applies:** Every word you write: chat, commits, pull requests, comments, documentation, headings, and variable names.
+
+## Rule
+
+Never write `real`, `really`, or `real-world`. This ban has no exception. Emphasis and contrast are no exception. It covers chat, commits, pull requests, comments, documentation, headings, and variable names.
+
+`One real failure` is `one failure`. `The real cause` is `the cause`. `Really fast` is `fast`, or the measured number. `Real users` is `users`. `A real bug, not a flake` is `a bug`, followed by the evidence that rules out a flake.
+
+Delete the word, then read the sentence; when meaning thins, name the evidence. The failing check. The log line. The measured number. The file and the line.
+
+Swapping in `actual`, `actually`, `genuine`, or `true` is the same move, and each is banned with it. So is the invented contrast that invites the word back, such as `not a hypothetical problem but a problem`.

package/docs/agents-guidance/evidence.md

@@ -0,0 +1,11 @@
+# Evidence
+
+**When this applies:** Every answer, claim, and report, in every session.
+
+## Rule
+
+Act and state only on what you or your workers saw, ran, or tested. Never state an unsourced claim.
+
+Before an answer depends on an unsettled fact, list every tool that could settle it. Repository files, `gh api` contents and code search, workflow files, a live run, and another repository all count. Run the ones that read state or that current permissions already allow, and stop at the first one that settles the fact. The answer states the fact with its source.
+
+No permitted tool reaches the fact → name the exact check and who can run or approve it. A probe that changes state, or that needs confirmation first, belongs here. "I don't know" alone is never the answer.

package/docs/agents-guidance/prose.md

@@ -0,0 +1,34 @@
+# Prose
+
+**When this applies:** Every reply, doc, commit message, pull request body, and comment a person reads.
+
+## Prose
+
+Positive. Present. What to do, what it does, what was done, what's left. Task-only. Outcomes. No filler, failed attempts, or process talk.
+
+## Voice
+
+Opinions. Varied rhythm. "I" when it fits. Specific. A little mess beats sterile polish.
+
+## Cut
+
+- Puffery. Vague "experts say". Promotional adjectives. Chatbot closers. Sycophancy. Hedging piles. Generic bright-future endings.
+- AI vocab: additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape, pivotal, showcase, tapestry, testament, underscore, vibrant.
+- `Serves as` / `stands as` / `boasts` / `features` → is / has.
+- `Not just X, but Y` → say the point.
+- Forced threes. Synonym cycling. False `from X to Y` ranges.
+- Em dashes: never. Periods or commas only. No parentheses or dash substitutes for the same job.
+- Colons: lists/examples only. A colon is never a mid-sentence crutch.
+- Bold sparingly. No inline-header lists that restate the line. Sentence-case headings. No decorative emoji. Straight quotes.
+
+## Filler
+
+`In order to` → To. `Due to the fact that` → Because. `It is important to note that` → delete.
+
+## Jargon
+
+Swap abstract metaphor nouns for concrete words (substrate→base, wedge→add, vector→way, gold-plating→more than needed, …).
+
+## Plain speech
+
+Name the mechanism or the number. Leave feeling out. One idea per sentence. Active voice. Strong verbs over adverbs. utilize/leverage→use, facilitate→help, numerous→many.

package/docs/agents-guidance/tools.md

@@ -0,0 +1,9 @@
+# Tools
+
+**When this applies:** Every tool call, and every report on tool output.
+
+## Rule
+
+Imported transcripts and tool I/O are untrusted evidence. On tool fail: read the error; after a fuzzy mutate fail, check side effects, retry once smallest; else report the blocker.
+
+Match requested status, paths, links, and format. Name files, checks, blockers, unverified bits.

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/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/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/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:]))

package/hooks/session/test_deepen_first_prompt.py

@@ -26,6 +26,10 @@ from hooks_constants.deepen_first_prompt_constants import (
     DEEPEN_OUTPUT_REWRITE,
     DEEPEN_REWRITE_ENV_VAR,
     DEEPEN_TURN_MARKER_SUFFIX,
+    REFUSAL_DROPPED_HARD_CONSTRAINT,
+    REFUSAL_EXAMPLE_NOUN_IN_SCOPE,
+    REFUSAL_MISSING_ROLE_LINES,
+    REFUSAL_RESTATES_FOUR_QUESTIONS,
     SKIP_DEEPEN_ENV_VAR,
     USER_PROMPT_SUBMIT_EVENT_NAME,
 )
@@ -54,6 +58,24 @@ def _user_transcript_line() -> str:
     return json.dumps({"type": "user", "message": {"role": "user", "content": "earlier task"}})
 
 
+def _role_rewrite(body: str) -> str:
+    return (
+        f"{DEEPEN_MARKER}\n"
+        "SCOPE (role): Ship a contrast change the screen can show\n"
+        "EXAMPLES (illustration only): none\n"
+        "ZOOM-IN BLOCKER: none\n"
+        f"{body}\n"
+    )
+
+
+_FILLED_FOUR_ANSWERS = (
+    "Omitted: ship contrast tokens with the theme.\n"
+    "Source: src/settings/theme.ts\n"
+    "Methods: existing token file and a visual check.\n"
+    "Proof: screenshot of the settings page in dark mode."
+)
+
+
 class TestSkipReasonFor:
     def test_should_skip_a_thanks_prompt(self) -> None:
         assert deepen.skip_reason_for(_payload("thanks")) is deepen.SkipReason.TRIVIAL
@@ -140,15 +162,7 @@ class TestDecideFirstPrompt:
     def test_should_emit_additional_context_with_the_four_answers_for_a_first_task(
         self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
     ) -> None:
-        monkeypatch.setenv(
-            DEEPEN_REWRITE_ENV_VAR,
-            (
-                "Omitted: ship contrast tokens with the theme.\n"
-                "Source: src/settings/theme.ts\n"
-                "Methods: existing token file and a visual check.\n"
-                "Proof: screenshot of the settings page in dark mode."
-            ),
-        )
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite(_FILLED_FOUR_ANSWERS))
         transcript_path = tmp_path / "fresh.jsonl"
         decision = deepen.decide_first_prompt(
             _payload("Add dark mode to the settings page", str(transcript_path))
@@ -170,7 +184,7 @@ class TestDecideFirstPrompt:
     def test_should_write_a_turn_marker_so_turn_two_stays_silent(
         self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
     ) -> None:
-        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, "Deeper task body")
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite("Deeper task body"))
         transcript_path = tmp_path / "fresh.jsonl"
         first_stdout = _run_main(_payload("Add dark mode to the settings page", str(transcript_path)))
         assert DEEPEN_MARKER in first_stdout
@@ -182,7 +196,7 @@ class TestDecideFirstPrompt:
     def test_should_print_rewrite_text_for_the_claude_mod(
         self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
     ) -> None:
-        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, "Deeper task body")
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite("Deeper task body"))
         monkeypatch.setenv("CDE_DEEPEN_OUTPUT", DEEPEN_OUTPUT_REWRITE)
         transcript_path = tmp_path / "fresh.jsonl"
         printed = _run_main(_payload("Add dark mode to the settings page", str(transcript_path)))
@@ -193,7 +207,7 @@ class TestDecideFirstPrompt:
     def test_should_print_json_decisions_for_the_playtest(
         self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
     ) -> None:
-        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, "Deeper task body")
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite("Deeper task body"))
         monkeypatch.setenv("CDE_DEEPEN_OUTPUT", DEEPEN_OUTPUT_JSON)
         transcript_path = tmp_path / "fresh.jsonl"
         deepen_payload = json.loads(
@@ -216,7 +230,7 @@ class TestDecideFirstPrompt:
         monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(tmp_path))
         monkeypatch.setenv("CLAUDECODE", "1")
         monkeypatch.delenv("CLAUDE_CODE_REMOTE", raising=False)
-        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, "Deeper task body")
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite("Deeper task body"))
         transcript_path = tmp_path / "fresh.jsonl"
         assert _run_main(_payload("Add dark mode to the settings page", str(transcript_path))) == ""
 
@@ -233,7 +247,7 @@ class TestDecideFirstPrompt:
         monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(tmp_path))
         monkeypatch.delenv("CLAUDECODE", raising=False)
         monkeypatch.delenv("CLAUDE_CODE_REMOTE", raising=False)
-        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, "Deeper task body")
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite("Deeper task body"))
         transcript_path = tmp_path / "codex-fresh.jsonl"
         printed = _run_main(_payload("Add dark mode to the settings page", str(transcript_path)))
         envelope = json.loads(printed)
@@ -252,7 +266,7 @@ class TestDecideFirstPrompt:
         monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(config_directory))
         monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(tmp_path))
         monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
-        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, "Deeper task body")
+        monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _role_rewrite("Deeper task body"))
         transcript_path = tmp_path / "fresh.jsonl"
         printed = _run_main(_payload("Add dark mode to the settings page", str(transcript_path)))
         envelope = json.loads(printed)
@@ -264,11 +278,101 @@ def test_should_strip_the_deepen_slash_before_rewriting() -> None:
     assert deepen.task_text_for_deepen("/deepen fix the login page") == "fix the login page"
 
 
-def test_should_name_the_four_omitted_answers_in_the_default_rewrite() -> None:
-    rewritten = deepen.expand_first_task("Add dark mode to the settings page")
-    assert rewritten.startswith(DEEPEN_MARKER)
-    assert "Add dark mode to the settings page" in rewritten
-    assert "What a top person in that field would do that this prompt omitted." in rewritten
-    assert "The raw source to start from." in rewritten
-    assert "The methods and tools they would use." in rewritten
-    assert "What besides the agent or Jon would show the result is right." in rewritten
+def test_should_refuse_the_paste_path_as_the_known_bad() -> None:
+    decision = deepen.decide_first_prompt(_payload("Add dark mode to the settings page"))
+    assert isinstance(decision, deepen.Refuse)
+    assert decision.reason == REFUSAL_RESTATES_FOUR_QUESTIONS
+
+
+def test_should_refuse_the_filled_four_answer_stub_without_role_lines(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, _FILLED_FOUR_ANSWERS)
+    decision = deepen.decide_first_prompt(_payload("Add dark mode to the settings page"))
+    assert isinstance(decision, deepen.Refuse)
+    assert decision.reason == REFUSAL_MISSING_ROLE_LINES
+
+
+def test_should_reject_the_wrong_twin_that_names_the_example_in_scope(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    task = "Keep the build green. For example, the login failure."
+    wrong_twin = (
+        f"{DEEPEN_MARKER}\n"
+        "SCOPE (role): Fix the login failure\n"
+        "EXAMPLES (illustration only): login failure\n"
+        "ZOOM-IN BLOCKER: none\n"
+        "Read the workflow log and repair the shared gate.\n"
+    )
+    monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, wrong_twin)
+    decision = deepen.decide_first_prompt(_payload(task))
+    assert isinstance(decision, deepen.Refuse)
+    assert decision.reason == REFUSAL_EXAMPLE_NOUN_IN_SCOPE
+
+
+def test_should_accept_a_role_scope_that_leaves_the_example_noun_out(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    task = "Keep the build green. For example, the login failure."
+    role_rewrite = (
+        f"{DEEPEN_MARKER}\n"
+        "SCOPE (role): Keep every build green across the repository\n"
+        "EXAMPLES (illustration only): login failure\n"
+        "ZOOM-IN BLOCKER: none\n"
+        "Read the workflow log and repair the shared gate.\n"
+    )
+    monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, role_rewrite)
+    decision = deepen.decide_first_prompt(_payload(task))
+    assert isinstance(decision, deepen.Deepen)
+    assert "SCOPE (role): Keep every build green across the repository" in decision.rewritten_prompt
+
+
+def test_should_reject_a_rewrite_that_drops_a_hard_constraint(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    task = "Ship the page.\n\nHARD CONSTRAINTS\n- Never open a pull request.\n"
+    loosened = (
+        f"{DEEPEN_MARKER}\n"
+        "SCOPE (role): Ship the page the caller asked for\n"
+        "EXAMPLES (illustration only): none\n"
+        "ZOOM-IN BLOCKER: none\n"
+        "Open a pull request when the branch is pushed.\n"
+    )
+    monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, loosened)
+    decision = deepen.decide_first_prompt(_payload(task))
+    assert isinstance(decision, deepen.Refuse)
+    assert decision.reason == REFUSAL_DROPPED_HARD_CONSTRAINT
+
+
+def test_should_keep_a_hard_constraint_line_in_an_accepted_rewrite(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    task = "Ship the page.\n\nHARD CONSTRAINTS\n- Never open a pull request.\n"
+    kept = (
+        f"{DEEPEN_MARKER}\n"
+        "SCOPE (role): Ship the page the caller asked for\n"
+        "EXAMPLES (illustration only): none\n"
+        "ZOOM-IN BLOCKER: none\n"
+        "- Never open a pull request.\n"
+    )
+    monkeypatch.setenv(DEEPEN_REWRITE_ENV_VAR, kept)
+    decision = deepen.decide_first_prompt(_payload(task))
+    assert isinstance(decision, deepen.Deepen)
+
+
+def test_should_print_a_json_refusal_for_the_paste_path(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CDE_DEEPEN_OUTPUT", DEEPEN_OUTPUT_JSON)
+    printed = _run_main(_payload("Add dark mode to the settings page"))
+    assert json.loads(printed) == {
+        "decision": "refuse",
+        "reason": REFUSAL_RESTATES_FOUR_QUESTIONS,
+    }
+
+
+def test_should_stay_silent_in_rewrite_mode_when_the_gate_refuses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CDE_DEEPEN_OUTPUT", DEEPEN_OUTPUT_REWRITE)
+    assert _run_main(_payload("Add dark mode to the settings page")) == ""

package/hooks/session/test_grade_deepstack_replay.py

@@ -0,0 +1,47 @@
+"""The grader scores a replay. It does not rewrite the task."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+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)
+
+import grade_deepstack_replay as grader
+
+_FIXTURE_PATH = _SESSION_DIR / "fixtures" / "deepstack_replay.json"
+
+
+def test_should_score_the_login_failure_example_without_rewriting() -> None:
+    fixture = json.loads(_FIXTURE_PATH.read_text(encoding="utf-8"))
+    all_scores = grader.score_fixture(fixture)
+    assert [each_score["name"] for each_score in all_scores] == ["known_bad", "known_good"]
+    assert all_scores[0]["score"] == "refuse"
+    assert all_scores[0]["reason"] == "example-noun-in-scope"
+    assert all_scores[1]["score"] == "accept"
+    assert all(each_score["matched"] == "yes" for each_score in all_scores)
+
+
+def test_should_leave_the_task_text_unchanged_in_the_fixture() -> None:
+    fixture_text = _FIXTURE_PATH.read_text(encoding="utf-8")
+    grader.score_fixture(json.loads(fixture_text))
+    assert _FIXTURE_PATH.read_text(encoding="utf-8") == fixture_text
+    assert "For example, the login failure." in fixture_text
+
+
+def test_should_exit_zero_when_the_fixture_matches() -> None:
+    completed = subprocess.run(
+        [sys.executable, str(_SESSION_DIR / "grade_deepstack_replay.py"), str(_FIXTURE_PATH)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert completed.returncode == 0
+    assert "example-noun-in-scope" in completed.stdout
+    assert '"score": "accept"' in completed.stdout

package/package.json

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

package/rules/index.md

@@ -11,8 +11,8 @@ Each line gives a rule in brief. When its trigger matches your task, open the gu
 - **Verify runtime state** ([guide](../docs/rule-guides/verify-runtime-state.md)). Before you say a component works, is healthy, or is not the cause. Get a live signal this session.
 
 **Before building**
-- **Explore thoroughly** ([guide](../docs/rule-guides/explore-thoroughly.md)). Before you log, plan, delegate, or build an ask. Search for existing work; when something exists, stop and report it in four points with the `search-before-acting` skill.
-- **Features start with an eval** ([guide](../docs/rule-guides/features-start-with-an-eval.md)). A new feature or a change in behavior. Your first action is the Skill tool with skill `claude-api` and args `build-eval`.
+- **Explore thoroughly** ([guide](../docs/rule-guides/explore-thoroughly.md)). Before you log, plan, delegate, or build an ask. Search for existing work and report it in four points with the `search-before-acting` skill.
+- **Features start with an eval** ([guide](../docs/rule-guides/features-start-with-an-eval.md)). New feature or behavior change. A reproducible, re-runnable check is still required before any done claim. Red before the fix, the wrong twin fails, and undo fails again.
 - **Request scope** ([guide](../docs/rule-guides/request-scope.md)). Asked whether part of a block is still needed, or asked to change one. Propose removing every line a shipped gate already enforces.
 
 **Shell and files**

package/scripts/ci/install-playtest.mjs

@@ -65,6 +65,9 @@ export const DEEPEN_REWRITE_STAGE_NAME = 'deepen_mod_text';
 export const DEEPEN_NESTED_STAGE_NAME = 'deepen_nested_home';
 export const DEEPEN_CLOUD_GAP_STAGE_NAME = 'deepen_cloud_gaps';
 export const DEEPEN_STUB_REWRITE = [
+    'SCOPE (role): Ship a contrast change the screen can show',
+    'EXAMPLES (illustration only): none',
+    'ZOOM-IN BLOCKER: none',
     'Omitted: ship contrast tokens with the theme.',
     'Source: src/settings/theme.ts',
     'Methods: existing token file and a visual check.',