claude-dev-env 8.89.0 → 8.90.0

package/scripts/ci/install-playtest.mjs

@@ -5,7 +5,8 @@
  * The driver installs this package into a scratch home, reads the hook roster
  * the install wrote into `settings.json`, starts one SessionStart hook and one
  * PreToolUse hook from that installed tree against fixture payloads, and reads
- * the output envelope each one returns.
+ * the output envelope each one returns. A last stage checks that the install
+ * left no deepen piece behind.
  *
  * Every stage writes the envelope it read to the evidence directory and prints
  * one line carrying the stage name, the artifact path and the artifact's
@@ -31,6 +32,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { RETIRED_HOOK_STAND_IN_MARKER } from '../../bin/install.mjs';
 import {
     createScratchHome,
     removeScratchHome,
@@ -54,59 +56,16 @@ export const PRE_TOOL_USE_EVENT_NAME = 'PreToolUse';
 export const SESSION_START_HOOK_SCRIPT_NAME = 'working_style_prompt.py';
 export const BASH_HOOK_SCRIPT_NAME = 'bash_pre_tool_use_dispatcher.py';
 export const BASH_MATCHER = 'Bash';
-export const USER_PROMPT_SUBMIT_EVENT_NAME = 'UserPromptSubmit';
-export const DEEPEN_HOOK_SCRIPT_NAME = 'deepen_first_prompt.py';
-export const NESTED_HOOK_SCRIPT_NAME = 'nested_project_hooks.py';
-export const DEEPEN_MARKER = 'CDE_DEEPEN:v1';
-export const DEEPEN_AGENT_MARKER = 'CDE_DEEPEN_AGENT';
-export const DEEPEN_STAGE_NAME = 'deepen_first_prompt';
-export const DEEPEN_SKIP_STAGE_NAME = 'deepen_skips';
-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.',
-    'Proof: screenshot of the settings page in dark mode.',
-].join('\n');
-export const CLAUDE_SUBAGENT_PROMPT_PREFIX = (
-    'Before any other work, invoke the poteto-mode skill with the Skill tool. '
-    + 'Every prompt you write for a subagent opens with the same instruction.'
-);
-export const CLOUD_GAP_EVIDENCE = {
-    cursorCloud: {
-        doc: 'https://cursor.com/docs/hooks',
-        quotes: [
-            'User-level hooks (`~/.cursor/hooks.json`) are not available in cloud agents. Cloud agent VMs don\'t have access to your local home directory configuration.',
-            'sessionStart: Deferred while cloud agents can still start in a read-only environment. Hooks don\'t load there, so a cloud sessionStart would fire too late (after the first write) rather than at true session start.',
-            'beforeSubmitPrompt output is continue and user_message only.',
-        ],
-        path: 'the deepen skill under ~/.cursor/skills',
-    },
-    codexCloud: {
-        doc: 'https://learn.chatgpt.com/docs/hooks',
-        quotes: [
-            'Command/shell, prompt, and agent handlers; hooks from local configuration, plugins, or local directories; environment-scoped hooks; and SessionEnd MCP hooks are not supported with cloud orchestration, even when tools execute locally.',
-        ],
-    },
-    claudeUserPromptSubmit: {
-        doc: 'https://code.claude.com/docs/en/hooks',
-        quotes: [
-            'UserPromptSubmit: can\'t replace the prompt; it only injects additionalContext alongside it',
-        ],
-    },
-    claudePromptSubmitMod: {
-        doc: 'https://code.claude.com/docs/en/plugins/mods/events',
-        quotes: [
-            'Rewrite the prompt. The transcript and your prompt history show the new text. next({ ...e, text: newText })',
-            'A cloud session: Yes, for a plugin that reaches the cloud session. This package still keeps the Python hook as the cloud fallback because mods that replace settings hooks stay off when CLAUDE_CODE_REMOTE is true.',
-        ],
-    },
-};
+export const RETIRED_DEEPEN_STAGE_NAME = 'retired_deepen_absent';
+export const RETIRED_DEEPEN_HOOK_SCRIPT_NAME = 'deepen_first_prompt.py';
+export const RETIRED_DEEPEN_CODEX_BLOCK_START = '<!-- claude-dev-env deepen: start -->';
+export const ALL_RETIRED_DEEPEN_RELATIVE_PATHS = Object.freeze([
+    join('.claude', 'skills', 'deepen'),
+    join('.agents', 'skills', 'deepen'),
+    join('.claude', 'commands', 'deepen.md'),
+    join('.claude', 'hooks', 'session', RETIRED_DEEPEN_HOOK_SCRIPT_NAME),
+    join('.cursor', 'skills', 'deepen'),
+]);
 
 export const SESSION_START_PAYLOAD = {
     hook_event_name: SESSION_START_EVENT_NAME,
@@ -280,273 +239,68 @@ function runSessionStartStage(settingsPath, scratchHome, evidenceDirectory) {
     if (typeof envelope.additionalContext !== 'string' || envelope.additionalContext.length === 0) {
         throw new Error('The SessionStart envelope carries no additionalContext');
     }
-    if (envelope.additionalContext.includes(DEEPEN_MARKER)) {
-        throw new Error('The SessionStart envelope repeated first-task deepen text');
-    }
     const evidencePath = writeEvidence(evidenceDirectory, SESSION_START_STAGE_NAME, JSON.stringify(envelope));
     reportStage(SESSION_START_STAGE_NAME, evidencePath);
 }
 
-function userPromptPayload(prompt, transcriptPath) {
-    const payload = {
-        hook_event_name: USER_PROMPT_SUBMIT_EVENT_NAME,
-        prompt,
-        session_id: 'playtest-session',
-    };
-    if (transcriptPath) payload.transcript_path = transcriptPath;
-    return payload;
-}
-
-function deepenHookEnvironment(extraEnvironment = {}) {
-    return {
-        CDE_DEEPEN_REWRITE: DEEPEN_STUB_REWRITE,
-        ...extraEnvironment,
-    };
-}
-
-function parseJsonDecision(stdout) {
-    const trimmed = stdout.trim();
-    if (!trimmed) return { decision: 'silent' };
-    return JSON.parse(trimmed);
+function readTextWhenPresent(filePath) {
+    return existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
 }
 
-function runDeepenFirstTaskStage(settingsPath, scratchHome, evidenceDirectory) {
-    const command = selectHookCommand(
-        hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME),
-        DEEPEN_HOOK_SCRIPT_NAME,
-    );
-    const transcriptPath = join(evidenceDirectory, 'first-task.jsonl');
-    const extraEnvironment = deepenHookEnvironment();
-    const envelopeResult = runInstalledHook(
-        command,
-        scratchHome,
-        userPromptPayload('Add dark mode to the settings page', transcriptPath),
-        extraEnvironment,
-    );
-    const envelope = readEnvelope(envelopeResult.stdout, USER_PROMPT_SUBMIT_EVENT_NAME);
-    if (!String(envelope.additionalContext || '').includes(DEEPEN_MARKER)) {
-        throw new Error('The UserPromptSubmit envelope carries no deepen marker');
-    }
-    if (!String(envelope.additionalContext).includes('src/settings/theme.ts')) {
-        throw new Error('The UserPromptSubmit envelope omitted the stub source');
-    }
-    const evidencePath = writeEvidence(
-        evidenceDirectory,
-        DEEPEN_STAGE_NAME,
-        JSON.stringify(envelope),
-    );
-    reportStage(DEEPEN_STAGE_NAME, evidencePath);
-    return { command, transcriptPath };
+/**
+ * Whether a path holds the inert stand-in the installer leaves for a stale registration.
+ *
+ * @param {string} absolutePath Path to read.
+ * @returns {boolean} True when the file carries the stand-in marker.
+ */
+function isRetiredHookStandIn(absolutePath) {
+    return absolutePath.endsWith('.py') && readTextWhenPresent(absolutePath).includes(RETIRED_HOOK_STAND_IN_MARKER);
 }
 
-function runDeepenRewriteStage(command, scratchHome, evidenceDirectory) {
-    const transcriptPath = join(evidenceDirectory, 'mod-text.jsonl');
-    const hookResult = runInstalledHook(
-        command,
-        scratchHome,
-        userPromptPayload('Add dark mode to the settings page', transcriptPath),
-        deepenHookEnvironment({ CDE_DEEPEN_OUTPUT: 'rewrite' }),
-    );
-    const printed = hookResult.stdout;
-    if (!printed.startsWith(DEEPEN_MARKER)) {
-        throw new Error(`The rewrite output did not start with ${DEEPEN_MARKER}`);
-    }
-    if (printed.includes('hookSpecificOutput')) {
-        throw new Error('The Claude mod rewrite printed a command-hook envelope');
+/**
+ * Check that the install left no deepen piece behind.
+ *
+ * The deepen skill, the /deepen command, the first-task hook and its
+ * registrations in Claude, Codex and Cursor, and the Codex AGENTS.md block
+ * were all retired. Any one of them in the scratch home fails the stage.
+ *
+ * @param {string} scratchHome Scratch home the install wrote into.
+ * @param {string} evidenceDirectory Directory the stage writes its evidence to.
+ * @returns {void}
+ * @throws {Error} The install left a deepen piece.
+ */
+function runRetiredDeepenStage(scratchHome, evidenceDirectory) {
+    const allLeftoverPaths = ALL_RETIRED_DEEPEN_RELATIVE_PATHS
+        .map((relativePath) => join(scratchHome, relativePath))
+        .filter((absolutePath) => existsSync(absolutePath))
+        .filter((absolutePath) => !isRetiredHookStandIn(absolutePath));
+    if (allLeftoverPaths.length > 0) {
+        throw new Error(`The install left retired deepen paths: ${allLeftoverPaths.join(', ')}`);
     }
-    const evidencePath = writeEvidence(
-        evidenceDirectory,
-        DEEPEN_REWRITE_STAGE_NAME,
-        JSON.stringify({ stdout: printed }),
-    );
-    reportStage(DEEPEN_REWRITE_STAGE_NAME, evidencePath);
-}
-
-function runDeepenSkipStage(command, scratchHome, evidenceDirectory, firstTranscriptPath) {
-    const jsonEnvironment = deepenHookEnvironment({ CDE_DEEPEN_OUTPUT: 'json' });
-    const cases = [
-        {
-            name: 'thanks',
-            payload: userPromptPayload('thanks', join(evidenceDirectory, 'thanks.jsonl')),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'trivial' },
-        },
-        {
-            name: 'slash',
-            payload: userPromptPayload('/sr-loop', join(evidenceDirectory, 'slash.jsonl')),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'slash-command' },
-        },
-        {
-            name: 'spawn',
-            payload: userPromptPayload(
-                `${CLAUDE_SUBAGENT_PROMPT_PREFIX}\n\nReply leaf.`,
-                join(evidenceDirectory, 'spawn.jsonl'),
-            ),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'spawn-rewrite' },
-        },
-        {
-            name: 'skip-flag',
-            payload: userPromptPayload('Add dark mode to the settings page', join(evidenceDirectory, 'skip-flag.jsonl')),
-            extraEnvironment: deepenHookEnvironment({ CDE_DEEPEN_OUTPUT: 'json', CDE_SKIP_DEEPEN: '1' }),
-            expected: { decision: 'skip', reason: 'skip-flag' },
-        },
-        {
-            name: 'later-turn',
-            payload: userPromptPayload('and also the billing page', firstTranscriptPath),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'later-turn' },
-        },
-        {
-            name: 'marker',
-            payload: userPromptPayload(`${DEEPEN_MARKER}\n\nDo the job.`, join(evidenceDirectory, 'marker.jsonl')),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'marker-present' },
-        },
-        {
-            name: 'loop',
-            payload: userPromptPayload('/loop until tests pass', join(evidenceDirectory, 'loop.jsonl')),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'loop-or-helper' },
-        },
-        {
-            name: 'deepen-agent',
-            payload: userPromptPayload(
-                `${DEEPEN_AGENT_MARKER}\nAnswer the four deepening questions.`,
-                join(evidenceDirectory, 'agent.jsonl'),
-            ),
-            extraEnvironment: jsonEnvironment,
-            expected: { decision: 'skip', reason: 'deepen-agent' },
-        },
+    const allHookConfigurationPaths = [
+        join(scratchHome, SETTINGS_RELATIVE_PATH),
+        join(scratchHome, '.codex', 'hooks.json'),
+        join(scratchHome, '.cursor', 'hooks.json'),
     ];
-    const results = [];
-    for (const eachCase of cases) {
-        const hookResult = runInstalledHook(
-            command,
-            scratchHome,
-            eachCase.payload,
-            eachCase.extraEnvironment,
-        );
-        const decision = parseJsonDecision(hookResult.stdout);
-        if (decision.decision !== eachCase.expected.decision || decision.reason !== eachCase.expected.reason) {
-            throw new Error(
-                `Skip ${eachCase.name} returned ${JSON.stringify(decision)} expected ${JSON.stringify(eachCase.expected)}`,
-            );
-        }
-        results.push({ name: eachCase.name, decision });
-    }
-    const silentThanks = runInstalledHook(
-        command,
-        scratchHome,
-        userPromptPayload('thanks', join(evidenceDirectory, 'thanks-silent.jsonl')),
-        deepenHookEnvironment(),
-    );
-    if (silentThanks.stdout.trim() !== '') {
-        throw new Error('A skipped prompt printed command-hook output');
-    }
-    const evidencePath = writeEvidence(
-        evidenceDirectory,
-        DEEPEN_SKIP_STAGE_NAME,
-        JSON.stringify({ results, silentThanks: silentThanks.stdout }),
-    );
-    reportStage(DEEPEN_SKIP_STAGE_NAME, evidencePath);
-}
-
-function runDeepenNestedStage(settingsPath, scratchHome, evidenceDirectory) {
-    const nestedCommand = selectHookCommand(
-        hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME),
-        NESTED_HOOK_SCRIPT_NAME,
-    );
-    const deepenCommand = selectHookCommand(
-        hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME),
-        DEEPEN_HOOK_SCRIPT_NAME,
-    );
-    const sessionDirectory = join(evidenceDirectory, 'nested-session');
-    const checkoutDirectory = join(sessionDirectory, 'alpha');
-    mkdirSync(join(checkoutDirectory, '.git'), { recursive: true });
-    mkdirSync(join(checkoutDirectory, '.claude'), { recursive: true });
-    writeFileSync(
-        join(checkoutDirectory, '.claude', 'settings.json'),
-        `${JSON.stringify({
-            hooks: {
-                UserPromptSubmit: [
-                    {
-                        matcher: '',
-                        hooks: [{ type: 'command', command: deepenCommand, timeout: 10 }],
-                    },
-                ],
-            },
-        }, null, 2)}\n`,
-    );
-    const hookResult = spawnSync(nestedCommand, {
-        shell: true,
-        input: JSON.stringify(userPromptPayload(
-            'Add dark mode to the settings page',
-            join(evidenceDirectory, 'nested.jsonl'),
-        )),
-        encoding: 'utf8',
-        cwd: sessionDirectory,
-        timeout: HOOK_TIMEOUT_MILLISECONDS,
-        env: {
-            ...scratchHomeEnvironment(scratchHome),
-            ...deepenHookEnvironment(),
-            CLAUDE_PROJECT_DIR: sessionDirectory,
-        },
-    });
-    const envelope = readEnvelope(hookResult.stdout, USER_PROMPT_SUBMIT_EVENT_NAME);
-    if (!String(envelope.additionalContext || '').includes(DEEPEN_MARKER)) {
-        throw new Error('The nested home-folder session carried no deepen marker');
-    }
-    const evidencePath = writeEvidence(
-        evidenceDirectory,
-        DEEPEN_NESTED_STAGE_NAME,
-        JSON.stringify(envelope),
-    );
-    reportStage(DEEPEN_NESTED_STAGE_NAME, evidencePath);
-}
-
-function runDeepenInstallSurfaceStage(scratchHome, evidenceDirectory) {
-    const settingsPath = join(scratchHome, SETTINGS_RELATIVE_PATH);
-    const userPromptCommands = hookCommandsForEvent(settingsPath, USER_PROMPT_SUBMIT_EVENT_NAME);
-    if (!userPromptCommands.some((each) => each.command.includes(DEEPEN_HOOK_SCRIPT_NAME))) {
-        throw new Error('The installed Claude settings declare no deepen_first_prompt.py');
-    }
-    const codexHooksPath = join(scratchHome, '.codex', 'hooks.json');
-    const codexHooks = JSON.parse(readFileSync(codexHooksPath, 'utf8'));
-    const codexUserPrompt = JSON.stringify(codexHooks.hooks?.UserPromptSubmit ?? []);
-    if (!codexUserPrompt.includes(DEEPEN_HOOK_SCRIPT_NAME)) {
-        throw new Error('The installed Codex hooks declare no UserPromptSubmit deepen_first_prompt.py');
-    }
-    const cursorSkillPath = join(scratchHome, '.cursor', 'skills', 'deepen', 'SKILL.md');
-    if (!existsSync(cursorSkillPath)) {
-        throw new Error(`The install wrote no ${cursorSkillPath}`);
+    const allRegisteringPaths = allHookConfigurationPaths
+        .filter((configurationPath) => readTextWhenPresent(configurationPath).includes(RETIRED_DEEPEN_HOOK_SCRIPT_NAME));
+    if (allRegisteringPaths.length > 0) {
+        throw new Error(`The install registered ${RETIRED_DEEPEN_HOOK_SCRIPT_NAME} in ${allRegisteringPaths.join(', ')}`);
     }
     const codexAgentsPath = join(scratchHome, '.codex', 'AGENTS.md');
-    const codexAgentsText = existsSync(codexAgentsPath) ? readFileSync(codexAgentsPath, 'utf8') : '';
-    if (!codexAgentsText.includes('<!-- claude-dev-env deepen: start -->')) {
-        throw new Error(`The install wrote no deepen block into ${codexAgentsPath}`);
+    if (readTextWhenPresent(codexAgentsPath).includes(RETIRED_DEEPEN_CODEX_BLOCK_START)) {
+        throw new Error(`The install wrote the deepen block into ${codexAgentsPath}`);
     }
     const evidencePath = writeEvidence(
         evidenceDirectory,
-        'deepen_install_surfaces',
+        RETIRED_DEEPEN_STAGE_NAME,
         JSON.stringify({
-            claudeUserPromptSubmit: userPromptCommands.map((each) => each.command),
-            codexUserPromptSubmit: codexHooks.hooks.UserPromptSubmit,
-            cursorSkillPath,
+            checkedPaths: ALL_RETIRED_DEEPEN_RELATIVE_PATHS,
+            checkedHookConfigurations: allHookConfigurationPaths,
             codexAgentsPath,
         }),
     );
-    reportStage('deepen_install_surfaces', evidencePath);
-}
-
-function runDeepenCloudGapStage(evidenceDirectory) {
-    const evidencePath = writeEvidence(
-        evidenceDirectory,
-        DEEPEN_CLOUD_GAP_STAGE_NAME,
-        JSON.stringify(CLOUD_GAP_EVIDENCE),
-    );
-    reportStage(DEEPEN_CLOUD_GAP_STAGE_NAME, evidencePath);
+    reportStage(RETIRED_DEEPEN_STAGE_NAME, evidencePath);
 }
 
 function runBlockingStage(settingsPath, scratchHome, evidenceDirectory) {
@@ -592,18 +346,8 @@ export function runPlaytest(argv) {
         runSessionStartStage(settingsPath, scratchHome, evidenceDirectory);
         stageName = BLOCKING_STAGE_NAME;
         runBlockingStage(settingsPath, scratchHome, evidenceDirectory);
-        stageName = 'deepen_install_surfaces';
-        runDeepenInstallSurfaceStage(scratchHome, evidenceDirectory);
-        stageName = DEEPEN_STAGE_NAME;
-        const deepen = runDeepenFirstTaskStage(settingsPath, scratchHome, evidenceDirectory);
-        stageName = DEEPEN_REWRITE_STAGE_NAME;
-        runDeepenRewriteStage(deepen.command, scratchHome, evidenceDirectory);
-        stageName = DEEPEN_SKIP_STAGE_NAME;
-        runDeepenSkipStage(deepen.command, scratchHome, evidenceDirectory, deepen.transcriptPath);
-        stageName = DEEPEN_NESTED_STAGE_NAME;
-        runDeepenNestedStage(settingsPath, scratchHome, evidenceDirectory);
-        stageName = DEEPEN_CLOUD_GAP_STAGE_NAME;
-        runDeepenCloudGapStage(evidenceDirectory);
+        stageName = RETIRED_DEEPEN_STAGE_NAME;
+        runRetiredDeepenStage(scratchHome, evidenceDirectory);
     } catch (error) {
         reportFailure(stageName, error instanceof Error ? error.message : String(error));
         return 1;

package/scripts/ci/install-playtest.test.mjs

@@ -7,6 +7,7 @@ import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 
 import { parseArguments, readEnvelope, selectHookCommand } from './install-playtest.mjs';
+import { RETIRED_HOOK_STAND_IN_MARKER } from '../../bin/install.mjs';
 import { SANDBOX_GIT_CONFIG_BODY, SANDBOX_GIT_CONFIG_NAME } from './scratch-home-install.mjs';
 
 const CI_DIRECTORY = dirname(fileURLToPath(import.meta.url));
@@ -30,12 +31,7 @@ test('the driver reads an envelope from every stage of a fresh install, and repo
         assert.match(greenRun.stdout, /\[PASS\] playtest install .* sha256=[0-9a-f]{64}/);
         assert.match(greenRun.stdout, /\[PASS\] playtest session_start_hook .* sha256=[0-9a-f]{64}/);
         assert.match(greenRun.stdout, /\[PASS\] playtest blocking_hook .* sha256=[0-9a-f]{64}/);
-        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_install_surfaces .* sha256=[0-9a-f]{64}/);
-        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_first_prompt .* sha256=[0-9a-f]{64}/);
-        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_mod_text .* sha256=[0-9a-f]{64}/);
-        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_skips .* sha256=[0-9a-f]{64}/);
-        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_nested_home .* sha256=[0-9a-f]{64}/);
-        assert.match(greenRun.stdout, /\[PASS\] playtest deepen_cloud_gaps .* sha256=[0-9a-f]{64}/);
+        assert.match(greenRun.stdout, /\[PASS\] playtest retired_deepen_absent .* sha256=[0-9a-f]{64}/);
         const blockingEnvelope = JSON.parse(readFileSync(join(evidenceDirectory, 'blocking_hook.json'), 'utf8'));
         assert.equal(Object.hasOwn(blockingEnvelope, 'permissionDecision'), false);
         assert.ok(
@@ -90,3 +86,25 @@ test('readEnvelope refuses output that names another event or no envelope at all
         /names PreToolUse rather than SessionStart/,
     );
 });
+
+test('the retired deepen stage accepts the installer stand-in and fails on a restored deepen hook', () => {
+    const scratchHome = mkdtempSync(join(tmpdir(), 'cde-playtest-home-'));
+    const evidenceDirectory = mkdtempSync(join(tmpdir(), 'cde-playtest-evidence-'));
+    const retiredHookPath = join(scratchHome, '.claude', 'hooks', 'session', 'deepen_first_prompt.py');
+    try {
+        const installRun = runDriver(['--home', scratchHome, '--evidence', evidenceDirectory]);
+        assert.equal(installRun.status, 0, `${installRun.stdout}\n${installRun.stderr}`);
+
+        writeFileSync(retiredHookPath, `"""${RETIRED_HOOK_STAND_IN_MARKER}."""\n`);
+        const standInRun = runDriver(['--home', scratchHome, '--evidence', evidenceDirectory, '--skip-install']);
+        assert.match(standInRun.stdout, /\[PASS\] playtest retired_deepen_absent/);
+
+        writeFileSync(retiredHookPath, SILENT_HOOK_SOURCE);
+        const restoredRun = runDriver(['--home', scratchHome, '--evidence', evidenceDirectory, '--skip-install']);
+        assert.equal(restoredRun.status, 1, `${restoredRun.stdout}\n${restoredRun.stderr}`);
+        assert.match(restoredRun.stdout, /\[FAIL\] playtest retired_deepen_absent The install left retired deepen paths/);
+    } finally {
+        rmSync(scratchHome, { recursive: true, force: true });
+        rmSync(evidenceDirectory, { recursive: true, force: true });
+    }
+});

package/scripts/policy_lint/adapter_configuration.py

@@ -140,6 +140,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/merge_over_review_offer_gate.py   -> exempt
         hooks/blocking/final_reply_gate.py               -> exempt
         hooks/blocking/open_tasks_stop_gate.py           -> exempt
+        hooks/blocking/session_title_turn_gate.py        -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons

package/scripts/policy_lint/config/constants.py

@@ -79,6 +79,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/merge_over_review_offer_gate.py",
     "blocking/final_reply_gate.py",
     "blocking/open_tasks_stop_gate.py",
+    "blocking/session_title_turn_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/test_deepstack_review_criterion.py

@@ -7,9 +7,8 @@ from pathlib import Path
 _RULES = Path(__file__).resolve().parent.parent / "docs" / "CODE_RULES.md"
 
 
-def test_new_instruction_criterion_cites_the_gate() -> None:
+def test_new_instruction_criterion_names_the_manifest() -> None:
     text = _RULES.read_text(encoding="utf-8")
     assert "## 11.7 A NEW INSTRUCTION NAMES THE TRIGGER THAT COVERS IT" in text
-    assert "hooks/session/deepen_first_prompt.py" in text
     assert "rules-archived/ARCHIVE-MANIFEST.md" in text
-    assert "DeepStack" in text
+    assert "deepen_first_prompt.py" not in text

package/scripts/test_deepstack_wording_rule.py

@@ -1,4 +1,4 @@
-"""The wording rule cites the first-task gate."""
+"""The wording rule keeps the three DeepStack labels and cites no retired gate."""
 
 from __future__ import annotations
 
@@ -7,13 +7,15 @@ from pathlib import Path
 _PACKAGE_ROOT = Path(__file__).resolve().parent.parent
 
 
-def test_wording_rule_cites_the_gate() -> None:
+def test_wording_rule_keeps_the_labels_and_drops_the_retired_gate() -> None:
     rule_text = (_PACKAGE_ROOT / "rules" / "deepstack-wording.md").read_text(encoding="utf-8")
     guide_text = (_PACKAGE_ROOT / "docs" / "rule-guides" / "deepstack-wording.md").read_text(
         encoding="utf-8"
     )
-    assert "hooks/session/deepen_first_prompt.py" in rule_text
-    assert "hooks/session/deepen_first_prompt.py" in guide_text
+    for each_text in (rule_text, guide_text):
+        assert "deepen_first_prompt.py" not in each_text
+        assert "CDE_DEEPEN" not in each_text
+    assert "**Enforcement:** none." in rule_text
     assert "SCOPE (role):" in guide_text
     assert "EXAMPLES (illustration only):" in guide_text
     assert "ZOOM-IN BLOCKER:" in guide_text

package/scripts/tests/test_adapter_configuration.py

@@ -138,6 +138,14 @@ def test_new_session_title_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_session_title_turn_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/session_title_turn_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_artifact_page_gate_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/artifact_dark_mode_gate.py"],

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

@@ -1,26 +0,0 @@
----
-name: deepen
-description: >-
-  Deepen a first user task before work starts. Triggers: /deepen, deepen this
-  task, first-task deepening, Cursor Cloud launch prompt. DeepStack intake
-  holds the contract.
----
-
-# deepen
-
-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.
-
-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.
-
-## Hosts
-
-- 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 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/commands/deepen.md

@@ -1,14 +0,0 @@
----
-description: Deepen a task into the standing job before work starts
-argument-hint: [task to deepen]
----
-
-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, follow DeepStack intake at https://github.com/jl-cmd-projects/DeepStack/blob/main/plugins/deepstack/skills/deepstack-mode/references/intake.md.
-
-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/decisions/deepstack-gate.md

@@ -1,32 +0,0 @@
-# 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 old paste path was 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.
-
-## The default rewrite
-
-With no rewrite stub and no `CDE_DEEPEN_COMMAND`, `hooks/session/deepen_default_rewrite.py` builds the rewrite. It takes the scope from the task's own sentences, moves clauses the task marks as examples (`for example`, `for instance`, `e.g.`, `such as`) to the examples line, clips a scope over 240 characters with a pointer to the full task, copies the task with its hard constraints, and ends with one order to do the job. When the scope still names an example, the blocker line asks the worker to confirm before narrowing to it. The gate checks this rewrite like any other, so a first task deepens on every host with nothing configured.
-
-## Proof shape
-
-Run the hook on stdin with `CDE_DEEPEN_OUTPUT=json`. A stub that pastes the four question stems refuses, and the default rewrite deepens. 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.