claude-dev-env 8.28.0 → 8.28.1

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/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,
@@ -2504,15 +2508,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 +2515,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 +2545,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 +2605,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     ];
 
     const allInstalledFiles = [];
+    const allQuestionGuidancePaths = [];
     const allUserOwnedPreferencePaths = new Set();
     const summary = {};
     for (const directory of CONTENT_DIRECTORIES) {
@@ -2796,7 +2785,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 +2833,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 +2855,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 +2875,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 +2963,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 +3142,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 +3255,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);
+        }
+    });
+}

package/bin/install.test.mjs

@@ -56,6 +56,7 @@ import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
     SKILL_LOAD_BLOCK_START,
     SKILL_LOAD_INSTRUCTION,
+    QUESTION_PRESENTATION_BLOCK_START,
     withSkillLoadBlock,
 } from './codex-skill-load-block.mjs';
 
@@ -3094,10 +3095,9 @@ test('a repeat install preserves Codex pstack configuration', t => {
 
     runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
 
-    assert.equal(
-        readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'),
-        withSkillLoadBlock('Custom Codex guidance\n'),
-    );
+    const codexGuidance = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.ok(codexGuidance.startsWith(withSkillLoadBlock('Custom Codex guidance\n')));
+    assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
     assert.equal(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), 'session hook: off\n');
 });
 
@@ -3140,10 +3140,13 @@ test('an absent host command is reported and leaves the other host installed', t
         [],
     );
     assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'pstack-models.md')), false);
-    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md')), false);
+    assert.match(
+        readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8'),
+        /<!-- claude-dev-env question presentation: start -->/,
+    );
 });
 
-test('--no-pstack leaves both hosts untouched', t => {
+test('--no-pstack skips the plugin and delivers Codex question guidance', t => {
     const sandbox = pstackPluginSandbox(t);
 
     const installerOutput = runPstackInstaller(
@@ -3153,7 +3156,10 @@ test('--no-pstack leaves both hosts untouched', t => {
     assert.deepEqual(sandbox.recordedCommands(), []);
     assert.doesNotMatch(installerOutput, /Pstack \(/);
     assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'pstack-models.md')), false);
-    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md')), false);
+    assert.match(
+        readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8'),
+        /<!-- claude-dev-env question presentation: start -->/,
+    );
 });
 
 function continuityCommandCount(configurationPath) {

package/bin/seed-codex-pstack-models.mjs

@@ -1,6 +1,7 @@
 import { copyFileSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, constants as filesystemConstants } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { hasOnlyQuestionPresentationBlock } from './codex-skill-load-block.mjs';
 
 const CODEX_PRESET_PATH = fileURLToPath(new URL('../pstack-codex-models.md', import.meta.url));
 
@@ -11,14 +12,24 @@ function pathExists(path) {
 export function seedCodexPstackModels(codexHome, writeAgentGuidance = writeFileSync) {
     const sheetPath = join(codexHome, 'pstack-models.md');
     const agentsPath = join(codexHome, 'AGENTS.md');
-    if (pathExists(sheetPath) || pathExists(agentsPath)) return null;
+    if (pathExists(sheetPath)) return null;
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    if (agentsEntry && !agentsEntry.isFile()) return null;
+    const existingGuidance = agentsEntry ? readFileSync(agentsPath, 'utf8') : '';
+    if (agentsEntry && !hasOnlyQuestionPresentationBlock(existingGuidance)) return null;
 
     const preset = readFileSync(CODEX_PRESET_PATH, 'utf8');
     const agentGuidance = preset.replace(/^session hook: on\n?$/m, '');
+    const separator = agentGuidance.endsWith('\n') ? '\n' : '\n\n';
+    const combinedGuidance = existingGuidance
+        ? `${agentGuidance}${separator}${existingGuidance}`
+        : agentGuidance;
     mkdirSync(codexHome, { recursive: true });
     copyFileSync(CODEX_PRESET_PATH, sheetPath, filesystemConstants.COPYFILE_EXCL);
     try {
-        writeAgentGuidance(agentsPath, agentGuidance, { encoding: 'utf8', flag: 'wx' });
+        writeAgentGuidance(agentsPath, combinedGuidance, {
+            encoding: 'utf8', flag: agentsEntry ? 'w' : 'wx',
+        });
     } catch (writeError) {
         unlinkSync(sheetPath);
         throw writeError;

package/bin/seed-codex-pstack-models.test.mjs

@@ -1,9 +1,12 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
+import { QUESTION_PRESENTATION_BLOCK_END, QUESTION_PRESENTATION_BLOCK_START } from './codex-skill-load-block.mjs';
+
+const QUESTION_GUIDANCE = `${QUESTION_PRESENTATION_BLOCK_START}\nAsk one question.\n${QUESTION_PRESENTATION_BLOCK_END}\n`;
 
 test('fresh Codex home gets the selected roles and hook setting', (context) => {
     const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
@@ -70,3 +73,44 @@ for (const existingFile of ['AGENTS.md', 'pstack-models.md']) {
         assert.equal(existsSync(join(codexHome, existingFile === 'AGENTS.md' ? 'pstack-models.md' : 'AGENTS.md')), false);
     });
 }
+
+test('a question-only Codex file receives model defaults and keeps its block', (context) => {
+    const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    const codexHome = join(root, '.codex');
+    mkdirSync(codexHome);
+    writeFileSync(join(codexHome, 'AGENTS.md'), QUESTION_GUIDANCE);
+
+    const paths = seedCodexPstackModels(codexHome);
+
+    assert.deepEqual(paths, [join(codexHome, 'pstack-models.md'), join(codexHome, 'AGENTS.md')]);
+    assert.match(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), /^session hook: on$/m);
+    const agents = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.match(agents, /^feature, refactoring: gpt-6-sol$/m);
+    assert.ok(agents.endsWith(QUESTION_GUIDANCE));
+});
+
+test('a question block with personal notes does not trigger model seeding', (context) => {
+    const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    const codexHome = join(root, '.codex');
+    mkdirSync(codexHome);
+    writeFileSync(join(codexHome, 'AGENTS.md'), `${QUESTION_GUIDANCE}My notes\n`);
+
+    assert.equal(seedCodexPstackModels(codexHome), null);
+    assert.equal(existsSync(join(codexHome, 'pstack-models.md')), false);
+});
+
+test('a linked question-only Codex file does not trigger model seeding', (context) => {
+    const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    const codexHome = join(root, '.codex');
+    const linkedGuidancePath = join(root, 'linked-guidance.md');
+    mkdirSync(codexHome);
+    writeFileSync(linkedGuidancePath, QUESTION_GUIDANCE);
+    symlinkSync(linkedGuidancePath, join(codexHome, 'AGENTS.md'));
+
+    assert.equal(seedCodexPstackModels(codexHome), null);
+    assert.equal(lstatSync(join(codexHome, 'AGENTS.md')).isSymbolicLink(), true);
+    assert.equal(readFileSync(linkedGuidancePath, 'utf8'), QUESTION_GUIDANCE);
+});

package/package.json

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

package/rules/question-presentation.md

@@ -0,0 +1,12 @@
+# Present questions clearly
+
+Before asking for input, give a short formatted brief in chat. Put the context and the effect of each choice there. Add a visual or artifact only when it helps the decision.
+
+For Codex, when a visual comparison helps, discover callable tools for Page creation, visualization upload, and Page opening. Create the comparison, upload its visualization, and open its Page in the current task before asking. If a tool is unavailable, creation, upload, or opening fails, or opening queues, put the comparison in chat before asking. Inline Visualize references appear only in final replies. Use the user's submitted answer for the decision. An async dispatch acknowledgement or saved visual supplies context only. Wait for the answer before work that depends on it.
+
+Ask one short, self-contained question with two or three clear choices. Use short labels, and keep each supported choice description to one short sentence. Use the same labels in the chat brief, comparison, and picker.
+
+Discover the current session's native question tool and its schema. Claude may expose `AskUserQuestion`.
+Codex may expose `request_user_input_async` or `request_user_input`. Follow the tool's mode restrictions.
+Put the question in its declared title or question field and choices in its declared string or object fields.
+When no native tool is usable, ask the short question and choices in chat.

package/rules/verify-before-asking.md

@@ -8,7 +8,7 @@ If a question can be answered by inspecting files, running a command, querying a
 
 ## Decision Checklist
 
-Before writing any AskUserQuestion or asking a clarifying question in chat, evaluate:
+Before using the current session's native question tool or asking a clarifying question in chat, evaluate:
 
 | Check | Action |
 |---|---|
@@ -21,14 +21,14 @@ Before writing any AskUserQuestion or asking a clarifying question in chat, eval
 | Is the answer retrievable from any available MCP tool? | Use the tool. |
 | Did the user already state a criterion, standard, or line that decides this? | Apply it, state the call and the reason, and keep going. |
 
-Only after confirming the answer cannot be obtained through any available tool, ask the user.
+Only after confirming the answer cannot be obtained through any available tool, ask the user. Present the question using [Present questions clearly](question-presentation.md).
 
 ## Prior-session facts expire
 
 A path, port, branch name, or config value you recall from an earlier session counts as unanswered until a tool re-checks it this session. Memory records what was true when it was written; the file may have moved, the port may be down, the branch may have merged. Treat every recalled fact as a claim to re-ground, not an answer to reuse.
 
 - When a tool can settle it, re-check in silence and act on the fresh result — no question to the user.
-- When no tool can settle it and the user has a stake in the answer, ask through `AskUserQuestion`.
+- When no tool can settle it and the user has a stake in the answer, use the current session's native question tool when available.
 
 ## Questions That Belong to the User