claude-dev-env 8.28.0 → 8.29.0

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

@@ -8,6 +8,8 @@ export const SKILL_LOAD_INSTRUCTION = 'Load the pstack:poteto-mode skill before
     + 'including a helper started with spawn_agent, whatever its task message says.';
 export const PACKAGE_GUIDANCE_BLOCK_START = '<!-- claude-dev-env package guidance: start -->';
 export const PACKAGE_GUIDANCE_BLOCK_END = '<!-- claude-dev-env package guidance: end -->';
+export const QUESTION_PRESENTATION_BLOCK_START = '<!-- claude-dev-env question presentation: start -->';
+export const QUESTION_PRESENTATION_BLOCK_END = '<!-- claude-dev-env question presentation: end -->';
 
 const WINDOWS_LONG_PATH_PREFIX = '\\\\?\\';
 
@@ -17,9 +19,10 @@ function managedBlock(blockStart, blockBody, blockEnd) {
 }
 
 function withBlockReplaced(guidanceText, blockStart, blockEnd, block) {
-    const startIndex = guidanceText.indexOf(blockStart);
-    const endIndex = startIndex === -1 ? -1 : guidanceText.indexOf(blockEnd, startIndex);
+    const firstStartIndex = guidanceText.indexOf(blockStart);
+    const endIndex = firstStartIndex === -1 ? -1 : guidanceText.indexOf(blockEnd, firstStartIndex);
     if (endIndex === -1) return null;
+    const startIndex = guidanceText.lastIndexOf(blockStart, endIndex);
     let afterBlockIndex = endIndex + blockEnd.length;
     if (guidanceText[afterBlockIndex] === '\n') afterBlockIndex += 1;
     return guidanceText.slice(0, startIndex) + block + guidanceText.slice(afterBlockIndex);
@@ -91,3 +94,48 @@ export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPack
     writeFileSync(agentsPath, updatedText, 'utf8');
     return agentsPath;
 }
+
+export function writeCodexQuestionGuidance(codexHome, policyText) {
+    const agentsPath = join(codexHome, 'AGENTS.md');
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    if (agentsEntry && !agentsEntry.isFile()) return null;
+    const currentText = agentsEntry ? readFileSync(agentsPath, 'utf8') : '';
+    const block = managedBlock(QUESTION_PRESENTATION_BLOCK_START, policyText, QUESTION_PRESENTATION_BLOCK_END);
+    const replacedText = withBlockReplaced(
+        currentText, QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END, block,
+    );
+    const separator = currentText && !currentText.endsWith('\n') ? '\n\n' : currentText ? '\n' : '';
+    const updatedText = replacedText ?? `${currentText}${separator}${block}`;
+    if (updatedText === currentText) return null;
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(agentsPath, updatedText, 'utf8');
+    return agentsPath;
+}
+
+export function hasOnlyQuestionPresentationBlock(guidanceText) {
+    if (!guidanceText.startsWith(`${QUESTION_PRESENTATION_BLOCK_START}\n`)) return false;
+    if (!guidanceText.endsWith(`${QUESTION_PRESENTATION_BLOCK_END}\n`)) return false;
+    return withBlockReplaced(
+        guidanceText, QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END, '',
+    ) === '';
+}
+
+/**
+ * Remove the managed question block while keeping surrounding guidance bytes.
+ *
+ * @param {string} codexHome
+ * @returns {string|null} The changed path, or null when no block was removed.
+ */
+export function removeCodexQuestionGuidance(codexHome) {
+    const agentsPath = join(codexHome, 'AGENTS.md');
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    if (!agentsEntry?.isFile()) return null;
+    const currentText = readFileSync(agentsPath, 'utf8');
+    const updatedText = withBlockReplaced(
+        currentText, QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END, '',
+    );
+    if (updatedText === null) return null;
+    if (updatedText === '') unlinkSync(agentsPath);
+    if (updatedText !== '') writeFileSync(agentsPath, updatedText, 'utf8');
+    return agentsPath;
+}

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

@@ -2,19 +2,24 @@ import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import {
     PACKAGE_GUIDANCE_BLOCK_END,
     PACKAGE_GUIDANCE_BLOCK_START,
+    QUESTION_PRESENTATION_BLOCK_END,
+    QUESTION_PRESENTATION_BLOCK_START,
     SKILL_LOAD_BLOCK_END,
     SKILL_LOAD_BLOCK_START,
     SKILL_LOAD_INSTRUCTION,
+    removeCodexQuestionGuidance,
     withSkillLoadBlock,
     writeCodexAgentsGuidance,
+    writeCodexQuestionGuidance,
 } from './codex-skill-load-block.mjs';
 
 const EXPECTED_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
 const PACKAGE_GUIDANCE = 'Status\n\nChanged / proof / blocked.\n';
+const QUESTION_POLICY = '# Present questions clearly\n\nAsk one question.\n';
 
 function guidanceBlock(guidanceText) {
     return `${PACKAGE_GUIDANCE_BLOCK_START}\n${guidanceText}${PACKAGE_GUIDANCE_BLOCK_END}\n`;
@@ -132,3 +137,117 @@ test('a link to a file the package does not own is left alone', (context) => {
     assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
     assert.equal(readFileSync(ownGuidancePath, 'utf8'), 'My own Codex notes\n');
 });
+
+test('question guidance creates a missing Codex file and repeat writes preserve bytes', (context) => {
+    const homes = makeHomes(context);
+    const expectedBlock = `${QUESTION_PRESENTATION_BLOCK_START}\n${QUESTION_POLICY}${QUESTION_PRESENTATION_BLOCK_END}\n`;
+
+    assert.equal(writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY), homes.agentsPath);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), expectedBlock);
+    assert.equal(writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY), null);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), expectedBlock);
+});
+
+test('question guidance preserves custom text and replaces only its block', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const oldBlock = `${QUESTION_PRESENTATION_BLOCK_START}\nOld policy\n${QUESTION_PRESENTATION_BLOCK_END}\n`;
+    writeFileSync(homes.agentsPath, `Before\n${oldBlock}After\n`);
+
+    assert.equal(writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY), homes.agentsPath);
+    assert.equal(
+        readFileSync(homes.agentsPath, 'utf8'),
+        `Before\n${QUESTION_PRESENTATION_BLOCK_START}\n${QUESTION_POLICY}${QUESTION_PRESENTATION_BLOCK_END}\nAfter\n`,
+    );
+});
+
+test('question guidance appends after custom notes without changing them', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, 'My notes without a final newline');
+
+    writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY);
+
+    assert.ok(readFileSync(homes.agentsPath, 'utf8').startsWith('My notes without a final newline\n\n'));
+});
+
+test('question guidance leaves every symlink and its target unchanged', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    mkdirSync(dirname(homes.sharedGuidancePath), { recursive: true });
+    writeFileSync(homes.sharedGuidancePath, 'Shared notes\n');
+    symlinkSync(homes.sharedGuidancePath, homes.agentsPath);
+
+    assert.equal(writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY), null);
+    assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(homes.sharedGuidancePath, 'utf8'), 'Shared notes\n');
+});
+
+test('question guidance leaves an existing directory and its notes unchanged', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.agentsPath, { recursive: true });
+    const notesPath = join(homes.agentsPath, 'notes.md');
+    writeFileSync(notesPath, 'Directory notes\n');
+
+    assert.equal(writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY), null);
+    assert.equal(lstatSync(homes.agentsPath).isDirectory(), true);
+    assert.equal(readFileSync(notesPath, 'utf8'), 'Directory notes\n');
+});
+
+test('a stray question start marker does not consume notes on repeat writes', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const customNotes = `${QUESTION_PRESENTATION_BLOCK_START}\nIncomplete block\nMy notes\n`;
+    writeFileSync(homes.agentsPath, customNotes);
+
+    writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY);
+    const firstGuidance = readFileSync(homes.agentsPath, 'utf8');
+    assert.ok(firstGuidance.startsWith(customNotes));
+    assert.equal(writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY), null);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), firstGuidance);
+});
+
+for (const eachGuidance of [
+    'Custom guidance\n',
+    `${QUESTION_PRESENTATION_BLOCK_START}\nUnfinished policy\nCustom notes\n`,
+]) {
+    test(`question removal preserves guidance without a complete block ${JSON.stringify(eachGuidance)}`, (context) => {
+        const homes = makeHomes(context);
+        mkdirSync(homes.codexHome, { recursive: true });
+        writeFileSync(homes.agentsPath, eachGuidance);
+
+        assert.equal(removeCodexQuestionGuidance(homes.codexHome), null);
+        assert.equal(readFileSync(homes.agentsPath, 'utf8'), eachGuidance);
+    });
+}
+
+test('question removal preserves a linked file even when its target holds a managed block', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome, { recursive: true });
+    const linkedGuidance = `${QUESTION_PRESENTATION_BLOCK_START}\n${QUESTION_POLICY}${QUESTION_PRESENTATION_BLOCK_END}\n`;
+    mkdirSync(dirname(homes.sharedGuidancePath), { recursive: true });
+    writeFileSync(homes.sharedGuidancePath, linkedGuidance);
+    symlinkSync(homes.sharedGuidancePath, homes.agentsPath);
+
+    assert.equal(removeCodexQuestionGuidance(homes.codexHome), null);
+    assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(homes.sharedGuidancePath, 'utf8'), linkedGuidance);
+});
+
+test('question removal preserves a guidance directory and its notes', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.agentsPath, { recursive: true });
+    const notesPath = join(homes.agentsPath, 'notes.md');
+    writeFileSync(notesPath, 'Directory notes\n');
+
+    assert.equal(removeCodexQuestionGuidance(homes.codexHome), null);
+    assert.equal(lstatSync(homes.agentsPath).isDirectory(), true);
+    assert.equal(readFileSync(notesPath, 'utf8'), 'Directory notes\n');
+});
+
+test('question removal leaves a missing guidance file absent', (context) => {
+    const homes = makeHomes(context);
+
+    assert.equal(removeCodexQuestionGuidance(homes.codexHome), null);
+    assert.equal(lstatSync(homes.agentsPath, { throwIfNoEntry: false }), undefined);
+});

package/bin/ever-shipped-skills.mjs

@@ -17,6 +17,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'comments',
     'condensing-instructions',
     'codex-review',
+    'codex-cleanse',
     'context7-mcp',
     'copilot-finding-triage',
     'copilot-review',

package/bin/install.mjs

@@ -52,7 +52,11 @@ import {
     shouldInstallPstackPlugin,
 } from './install-pstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
-import { writeCodexAgentsGuidance } from './codex-skill-load-block.mjs';
+import {
+    removeCodexQuestionGuidance,
+    writeCodexAgentsGuidance,
+    writeCodexQuestionGuidance,
+} from './codex-skill-load-block.mjs';
 import {
     continuityHostConfigurationPaths,
     removeContinuityHooks,
@@ -193,6 +197,7 @@ export const CORE_INCLUDE_DIRECTORIES = [
 export const CORE_SKILLS = [
     'orchestrator', 'orchestrator-refresh', 'team-advisor',
     'grok-spawn',
+    'codex-cleanse',
     'everything-search',
     'test-runner',
     'privacy-hygiene',
@@ -2504,15 +2509,6 @@ function install(selectedGroups, options = {}) {
     executeInstallPlan(plan);
 }
 
-/**
- * Apply one preflighted installation plan inside a snapshot/restore transaction.
- *
- * Captures the prior managed installation before any purge or write, then
- * restores settings, manifest, managed files, and core.hooksPath on failure.
- *
- * @param {ReturnType<typeof buildInstallPlan>} plan
- * @returns {void}
- */
 function executeInstallPlan(plan) {
     const faultPhase = resolveFaultPhaseFromEnvironment(process.env);
     const snapshot = capturePriorInstallSnapshot({
@@ -2520,7 +2516,10 @@ function executeInstallPlan(plan) {
         manifestFilePath: MANIFEST_FILE,
         settingsPath: plan.settingsPath,
         additionalSettingsPaths: [CODEX_HOOKS_CONFIGURATION_PATH],
-        priorManifestFiles: plan.priorManifest.files,
+        priorManifestFiles: [
+            ...(plan.priorManifest.files || []),
+            join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
+        ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });
 
@@ -2547,16 +2546,6 @@ function executeInstallPlan(plan) {
     }
 }
 
-/**
- * Mutation body for one preflighted plan. Invoked inside the transaction wrapper.
- *
- * @param {ReturnType<typeof buildInstallPlan>} plan
- * @param {{
- *   throwIfFault: (phase: string) => void,
- *   syncWrittenPaths: (allPaths: string[]) => void,
- * }} transactionHelpers
- * @returns {void}
- */
 function executeInstallPlanMutations(plan, transactionHelpers) {
     const { throwIfFault, syncWrittenPaths } = transactionHelpers;
     const priorSettingsHookCommands = [
@@ -2617,6 +2606,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     ];
 
     const allInstalledFiles = [];
+    const allQuestionGuidancePaths = [];
     const allUserOwnedPreferencePaths = new Set();
     const summary = {};
     for (const directory of CONTENT_DIRECTORIES) {
@@ -2796,7 +2786,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
                 : `  Pstack (${eachHost.host}): ${eachHost.status}`);
         }
     }
-    syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
+    if (!selectedGroups) {
+        const questionGuidancePath = writeCodexQuestionGuidance(
+            INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+            readFileSync(join(PACKAGE_ROOT, 'rules', 'question-presentation.md'), 'utf8'),
+        );
+        if (questionGuidancePath) allQuestionGuidancePaths.push(questionGuidancePath);
+    }
+    syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
     throwIfFault(FAULT_PHASES.BEFORE_DURABLE_PROMOTION);
     const shouldInstallAnyHooks = shouldInstallAllHooks || (allowedHookFiles && allowedHookFiles.size > 0);
@@ -2837,7 +2834,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         summary.hookGroups = totalHookGroups;
         summary.codexHookGroups = totalCodexHookGroups;
         console.log(`  Hook groups: ${totalHookGroups} merged into settings.json, ${totalCodexHookGroups} merged into hooks.json`);
-        syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
+        syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
 
         console.warn(
@@ -2859,7 +2856,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.warn(`  Git hooks: ${gitHookInstallationResult.hooksPathConfigurationResult.reason}`);
         }
         console.log(`  Git hook shims: ${gitHookInstallationResult.createdShimPaths.length} files (${KNOWN_GIT_HOOK_NAMES.join(', ')})`);
-        syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
+        syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
         throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
 
@@ -2879,7 +2876,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.warn(`      ${mypyIniInstallResult.expectedLine}`);
         }
     } else {
-        syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
+        syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
         throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
         throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
@@ -2967,7 +2964,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         ? manifestFilesWithFailedPrunes(allManagedInstalledFiles, failedPrunePaths)
         : unionOnComparisonKey(priorManifestFiles || [], allManagedInstalledFiles);
     writeManifest(manifestFiles, manifestSkillNames, summary.managedPermissions.managedPermissions);
-    syncWrittenPaths([...allInstalledFiles, MANIFEST_FILE, plan.settingsPath, ...publishedPointerPaths]);
+    syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, MANIFEST_FILE, plan.settingsPath, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_MANIFEST_WRITE);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
@@ -3146,6 +3143,7 @@ function executeUninstallPlan(plan, helpers = {}) {
             `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME}, outside ${MYPY_INI_INSTALL_PATH}, outside ${INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory}, outside ${INSTALL_ROOT_RESOLUTION.cursorInstallDirectory}, and outside ${AGENTS_HOME}`,
         );
     }
+    removeCodexQuestionGuidance(INSTALL_ROOT_RESOLUTION.codexHomeDirectory);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
 
     if (existsSync(plan.settingsPath)) {
@@ -3258,7 +3256,10 @@ function uninstall() {
         manifestFilePath: MANIFEST_FILE,
         settingsPath: plan.settingsPath,
         additionalSettingsPaths: [CODEX_HOOKS_CONFIGURATION_PATH],
-        priorManifestFiles: plan.removableFiles,
+        priorManifestFiles: [
+            ...plan.removableFiles,
+            join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
+        ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });
 

package/bin/install.question-presentation.test.mjs

@@ -0,0 +1,264 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageDirectory = fileURLToPath(new URL('..', import.meta.url));
+const installerPath = join(packageDirectory, 'bin', 'install.mjs');
+const policyPath = join(packageDirectory, 'rules', 'question-presentation.md');
+
+function makeScratchHome(context) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-question-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    return homeDirectory;
+}
+
+function installInScratchHome(homeDirectory, argumentsList = [], extraEnvironment = {}) {
+    return spawnSync(process.execPath, [installerPath, ...argumentsList], {
+        cwd: packageDirectory,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CDE_INSTALL_PSTACK: '0',
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            ...extraEnvironment,
+        },
+    });
+}
+
+test('full install with pstack disabled delivers one question policy to Claude and Codex', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    const codexHooksPath = join(homeDirectory, '.codex', 'config.toml');
+    const hooksConfiguration = '[features]\nhooks = false\n';
+    mkdirSync(dirname(codexHooksPath), { recursive: true });
+    writeFileSync(codexHooksPath, hooksConfiguration);
+
+    const installation = installInScratchHome(homeDirectory, ['--no-pstack']);
+
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    const policyText = readFileSync(policyPath, 'utf8');
+    assert.equal(readFileSync(join(homeDirectory, '.claude', 'rules', 'question-presentation.md'), 'utf8'), policyText);
+    assert.match(readFileSync(codexGuidancePath, 'utf8'), /<!-- claude-dev-env question presentation: start -->/);
+    assert.ok(readFileSync(codexGuidancePath, 'utf8').includes(policyText));
+    assert.equal(readFileSync(codexHooksPath, 'utf8'), hooksConfiguration);
+    const manifestPath = join(homeDirectory, '.claude', '.claude-dev-env-manifest.json');
+    assert.equal(JSON.parse(readFileSync(manifestPath, 'utf8')).files.includes(codexGuidancePath), false);
+});
+
+test('full install preserves custom Codex notes and keeps the question block stable on repeat', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    mkdirSync(dirname(codexGuidancePath), { recursive: true });
+    writeFileSync(codexGuidancePath, '# My notes\n\nKeep this line.\n');
+
+    const firstInstallation = installInScratchHome(homeDirectory);
+    assert.equal(firstInstallation.status, 0, firstInstallation.stdout + firstInstallation.stderr);
+    const firstGuidance = readFileSync(codexGuidancePath, 'utf8');
+    assert.ok(firstGuidance.startsWith('# My notes\n\nKeep this line.\n'));
+    assert.ok(firstGuidance.includes(readFileSync(policyPath, 'utf8')));
+
+    const secondInstallation = installInScratchHome(homeDirectory);
+    assert.equal(secondInstallation.status, 0, secondInstallation.stdout + secondInstallation.stderr);
+    assert.equal(readFileSync(codexGuidancePath, 'utf8'), firstGuidance);
+});
+
+test('uninstall removes question-only Codex guidance', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+
+    const removal = installInScratchHome(homeDirectory, ['--uninstall']);
+
+    assert.equal(removal.status, 0, removal.stdout + removal.stderr);
+    assert.equal(existsSync(codexGuidancePath), false);
+});
+
+test('uninstall removes the question block and preserves surrounding custom guidance', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    mkdirSync(dirname(codexGuidancePath), { recursive: true });
+    const customGuidance = '# My notes\n\nKeep this line.\n';
+    writeFileSync(codexGuidancePath, customGuidance);
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    writeFileSync(codexGuidancePath, `${readFileSync(codexGuidancePath, 'utf8')}Trailing notes\n`);
+
+    const removal = installInScratchHome(homeDirectory, ['--uninstall']);
+
+    assert.equal(removal.status, 0, removal.stdout + removal.stderr);
+    assert.equal(readFileSync(codexGuidancePath, 'utf8'), `${customGuidance}\nTrailing notes\n`);
+});
+
+for (const eachPriorGuidance of [null, '# Personal guidance\n']) {
+    test(`an uninstall staging fault restores ${eachPriorGuidance ? 'custom' : 'question-only'} Codex guidance`, (context) => {
+        const homeDirectory = makeScratchHome(context);
+        const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+        if (eachPriorGuidance !== null) {
+            mkdirSync(dirname(codexGuidancePath), { recursive: true });
+            writeFileSync(codexGuidancePath, eachPriorGuidance);
+        }
+        const installation = installInScratchHome(homeDirectory);
+        assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+        const installedGuidance = readFileSync(codexGuidancePath, 'utf8');
+
+        const failedRemoval = installInScratchHome(homeDirectory, ['--uninstall'], {
+            CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+        });
+
+        assert.notEqual(failedRemoval.status, 0, failedRemoval.stdout + failedRemoval.stderr);
+        assert.match(failedRemoval.stderr, /after_file_staging/);
+        assert.equal(readFileSync(codexGuidancePath, 'utf8'), installedGuidance);
+    });
+}
+
+test('full install leaves linked Codex guidance and its target unchanged', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    const userGuidancePath = join(homeDirectory, 'my-guidance.md');
+    mkdirSync(dirname(codexGuidancePath), { recursive: true });
+    writeFileSync(userGuidancePath, 'My linked notes\n');
+    symlinkSync(userGuidancePath, codexGuidancePath);
+
+    const installation = installInScratchHome(homeDirectory);
+
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    assert.equal(lstatSync(codexGuidancePath).isSymbolicLink(), true);
+    assert.equal(readFileSync(userGuidancePath, 'utf8'), 'My linked notes\n');
+});
+
+test('full install with pstack disabled preserves an AGENTS.md directory and delivers Claude policy', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    mkdirSync(codexGuidancePath, { recursive: true });
+    const notesPath = join(codexGuidancePath, 'notes.md');
+    writeFileSync(notesPath, 'Directory notes\n');
+
+    const installation = installInScratchHome(homeDirectory, ['--no-pstack']);
+
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    assert.equal(lstatSync(codexGuidancePath).isDirectory(), true);
+    assert.equal(readFileSync(notesPath, 'utf8'), 'Directory notes\n');
+    assert.equal(
+        readFileSync(join(homeDirectory, '.claude', 'rules', 'question-presentation.md'), 'utf8'),
+        readFileSync(policyPath, 'utf8'),
+    );
+});
+
+test('a selected Claude profile receives the source rule and its Codex guidance', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const profileDirectory = join(homeDirectory, 'profile');
+
+    const installation = installInScratchHome(homeDirectory, ['--target', profileDirectory]);
+
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    assert.equal(
+        readFileSync(join(profileDirectory, 'rules', 'question-presentation.md'), 'utf8'),
+        readFileSync(policyPath, 'utf8'),
+    );
+    assert.ok(readFileSync(join(profileDirectory, '.codex', 'AGENTS.md'), 'utf8').includes(readFileSync(policyPath, 'utf8')));
+});
+
+test('a successful pstack install retains its skill block and gains the question block', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const commandPath = join(homeDirectory, process.platform === 'win32' ? 'codex.cmd' : 'codex');
+    writeFileSync(
+        commandPath,
+        process.platform === 'win32' ? '@echo off\r\nexit /b 0\r\n' : '#!/bin/sh\nexit 0\n',
+        { mode: 0o755 },
+    );
+
+    const installation = installInScratchHome(homeDirectory, [], {
+        CDE_INSTALL_PSTACK: '1',
+        CDE_CODEX_EXECUTABLE: commandPath,
+        CDE_CLAUDE_EXECUTABLE: commandPath,
+    });
+
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    const guidanceText = readFileSync(join(homeDirectory, '.codex', 'AGENTS.md'), 'utf8');
+    assert.match(guidanceText, /<!-- claude-dev-env skill load: start -->/);
+    assert.match(guidanceText, /<!-- claude-dev-env question presentation: start -->/);
+    assert.ok(guidanceText.includes(readFileSync(policyPath, 'utf8')));
+});
+
+test('enabling pstack after a pstack-off install preserves question guidance', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const commandPath = join(homeDirectory, process.platform === 'win32' ? 'codex.cmd' : 'codex');
+    writeFileSync(
+        commandPath,
+        process.platform === 'win32' ? '@echo off\r\nexit /b 0\r\n' : '#!/bin/sh\nexit 0\n',
+        { mode: 0o755 },
+    );
+    const firstInstallation = installInScratchHome(homeDirectory);
+    assert.equal(firstInstallation.status, 0, firstInstallation.stdout + firstInstallation.stderr);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    const firstGuidance = readFileSync(codexGuidancePath, 'utf8');
+
+    const secondInstallation = installInScratchHome(homeDirectory, [], {
+        CDE_INSTALL_PSTACK: '1',
+        CDE_CODEX_EXECUTABLE: commandPath,
+        CDE_CLAUDE_EXECUTABLE: commandPath,
+    });
+
+    assert.equal(secondInstallation.status, 0, secondInstallation.stdout + secondInstallation.stderr);
+    const updatedGuidance = readFileSync(codexGuidancePath, 'utf8');
+    assert.ok(updatedGuidance.includes(firstGuidance));
+    assert.match(updatedGuidance, /<!-- claude-dev-env skill load: start -->/);
+    assert.match(updatedGuidance, /^feature, refactoring: gpt-6-sol$/m);
+    assert.match(readFileSync(join(homeDirectory, '.codex', 'pstack-models.md'), 'utf8'), /^session hook: on$/m);
+});
+
+test('a failed pstack transition restores question-only guidance and removes its new model sheet', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const commandPath = join(homeDirectory, process.platform === 'win32' ? 'codex.cmd' : 'codex');
+    writeFileSync(
+        commandPath,
+        process.platform === 'win32' ? '@echo off\r\nexit /b 0\r\n' : '#!/bin/sh\nexit 0\n',
+        { mode: 0o755 },
+    );
+    const firstInstallation = installInScratchHome(homeDirectory);
+    assert.equal(firstInstallation.status, 0, firstInstallation.stdout + firstInstallation.stderr);
+    const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+    const priorGuidance = readFileSync(codexGuidancePath, 'utf8');
+
+    const failedInstallation = installInScratchHome(homeDirectory, [], {
+        CDE_INSTALL_PSTACK: '1',
+        CDE_CODEX_EXECUTABLE: commandPath,
+        CDE_CLAUDE_EXECUTABLE: commandPath,
+        CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+    });
+
+    assert.notEqual(failedInstallation.status, 0, failedInstallation.stdout + failedInstallation.stderr);
+    assert.equal(readFileSync(codexGuidancePath, 'utf8'), priorGuidance);
+    assert.equal(existsSync(join(homeDirectory, '.codex', 'pstack-models.md')), false);
+});
+
+for (const priorGuidance of [null, '# Personal guidance\n']) {
+    test(`a staging fault restores ${priorGuidance ? 'existing' : 'missing'} Codex guidance`, (context) => {
+        const homeDirectory = makeScratchHome(context);
+        const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
+        if (priorGuidance !== null) {
+            mkdirSync(dirname(codexGuidancePath), { recursive: true });
+            writeFileSync(codexGuidancePath, priorGuidance);
+        }
+
+        const installation = installInScratchHome(homeDirectory, [], {
+            CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+        });
+
+        assert.notEqual(installation.status, 0, installation.stdout + installation.stderr);
+        assert.match(installation.stderr, /after_file_staging/);
+        if (priorGuidance === null) {
+            assert.equal(existsSync(codexGuidancePath), false);
+        } else {
+            assert.equal(readFileSync(codexGuidancePath, 'utf8'), priorGuidance);
+        }
+    });
+}