@promptbook/cli 0.114.0-48 → 0.114.0-49

package/umd/index.umd.js

@@ -58,7 +58,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-48';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-49';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1753,6 +1753,56 @@
         return command.help();
     }
 
+    /**
+     * Registers project selection without capturing a directory during command registration.
+     * @private internal CLI registration helper
+     */
+    function addProjectPathOption(command) {
+        command.option('--path <directory>', 'Project directory (default: invocation current directory); relative paths start there');
+    }
+    /**
+     * Registers additional context independently of primary-agent selection.
+     * @private internal CLI registration helper
+     */
+    function addProjectContextOption(command) {
+        command.option('--context <context-or-file>', 'Additional instructions (default: project AGENTS.md); inline text or a project-relative file replaces the default; an empty value disables it');
+    }
+    /**
+     * Captures an invocation's directory at action time. No process-global state is changed.
+     * @private internal CLI normalization helper
+     */
+    function normalizeProjectCliOptions(options, invocationDirectory = process.cwd()) {
+        const selectedPath = options.path;
+        if (selectedPath !== undefined && !selectedPath.trim()) {
+            throw new EnvironmentMismatchError(spaceTrim('Pass a non-empty project directory in `--path`, or omit it to use the current directory.'));
+        }
+        return { projectDirectory: path.resolve(invocationDirectory, selectedPath !== null && selectedPath !== void 0 ? selectedPath : '.') };
+    }
+    /**
+     * Validates the selected directory before any setup writes, without selecting an enclosing Git root.
+     * @private shared project resolution for CLI services
+     */
+    async function resolveProjectDirectory(projectDirectory) {
+        const requestedPath = path.resolve(projectDirectory);
+        try {
+            const projectPath = await promises.realpath(requestedPath);
+            if (!(await promises.stat(projectPath)).isDirectory()) {
+                throw new EnvironmentMismatchError(spaceTrim(`Project path \`${requestedPath}\` is not a directory.`));
+            }
+            await promises.access(projectPath, fs.constants.R_OK | fs.constants.X_OK);
+            return projectPath;
+        }
+        catch (error) {
+            throw new EnvironmentMismatchError(spaceTrim(`
+            Cannot access project directory \`${requestedPath}\`.
+            Check that it exists, is a directory, and is readable and searchable; correct \`--path\` before retrying.
+
+            ${error instanceof Error ? error.message : String(error)}
+        `));
+        }
+    }
+    // Note: [💞] Shared project registration and resolution helpers.
+
     // Note: [💞] Ignore a discrepancy between file name and entity name
     /**
      * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
@@ -2112,15 +2162,18 @@
         command.requiredOption('--agent <agent-book-path>', 'Path to the agent .book file');
         addPromptRunnerSelectionOptions(command);
         addPromptRunnerRuntimeOptions(command);
-        command.option('--context <context-or-file>', 'Append extra context either inline or from a file path');
+        addProjectPathOption(command);
+        addProjectContextOption(command);
         command.action(handleActionErrors(async (cliOptions, commandProgram) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
             const options = cliOptions;
             const runnerOptions = normalizeAgentCommandRunnerOptions(options, commandProgram);
             const { runAgentChat } = await Promise.resolve().then(function () { return runAgentChat$1; });
             await runAgentChat({
                 agentPath: resolveRequiredAgentPath(options),
                 context: options.context,
-                currentWorkingDirectory: process.cwd(),
+                currentWorkingDirectory: projectPath,
                 ...runnerOptions,
             });
         }));
@@ -2146,8 +2199,11 @@
         command.requiredOption('--message <message>', 'User message to send to the agent');
         addPromptRunnerSelectionOptions(command);
         addPromptRunnerRuntimeOptions(command);
-        command.option('--context <context-or-file>', 'Append extra context either inline or from a file path');
+        addProjectPathOption(command);
+        addProjectContextOption(command);
         command.action(handleActionErrors(async (cliOptions, commandProgram) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
             const options = cliOptions;
             const runnerOptions = normalizeAgentCommandRunnerOptions(options, commandProgram);
             const { runAgentExec } = await Promise.resolve().then(function () { return runAgentExec$1; });
@@ -2155,7 +2211,7 @@
                 agentPath: resolveRequiredAgentPath(options),
                 context: options.context,
                 message: resolveRequiredAgentMessage(options),
-                currentWorkingDirectory: process.cwd(),
+                currentWorkingDirectory: projectPath,
                 ...runnerOptions,
             });
         }));
@@ -2459,8 +2515,11 @@
             - ${AGENT_BOOK_FILE_PATH}
             - ${AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH.replace(/\\/gu, '/')}
         `));
-        command.action(handleActionErrors(async () => {
-            const summary = await initializeAgentProjectConfiguration(process.cwd());
+        addProjectPathOption(command);
+        command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
+            const summary = await initializeAgentProjectConfiguration(projectPath);
             printAgentInitializationSummary(summary);
         }));
     }
@@ -2515,15 +2574,21 @@
             `));
         addPromptRunnerSelectionOptions(command);
         addPromptRunnerExecutionOptions(command);
+        addProjectPathOption(command);
         (_a = options.configureCommand) === null || _a === void 0 ? void 0 : _a.call(options, command);
         command.action(handleActionErrors(async (cliOptions) => {
-            const runOptions = createAgentRunOptionsFromCliOptions(cliOptions);
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
+            const runOptions = {
+                ...createAgentRunOptionsFromCliOptions(cliOptions),
+                projectPath,
+            };
             const execute = await options.loadExecutor();
             if (options.executionMode === 'watch') {
                 const { runPersistentAgentWatch } = await Promise.resolve().then(function () { return runPersistentAgentWatch$1; });
                 await runPersistentAgentWatch({
                     commandDisplayName: `ptbk agent-folder ${options.commandName}`,
-                    logDirectoryPath: process.cwd(),
+                    logDirectoryPath: projectPath,
                     runWatch: async () => {
                         await execute(runOptions);
                     },
@@ -24757,7 +24822,7 @@
      * Distinguishes prompt-runner and verification temp shells in the shared runtime log.
      */
     function describeTempScriptKind(scriptPath) {
-        return scriptPath.toLowerCase().endsWith('.test.sh') ? 'test shell' : 'runner shell';
+        return scriptPath.toLowerCase().endsWith('.check.sh') ? 'check shell' : 'runner shell';
     }
 
     /**
@@ -24960,28 +25025,44 @@
             /**
              * Handles process exit and resolves or rejects accordingly.
              */
-            const handleExit = (code) => {
+            const handleExit = (code, signal) => {
                 var _a;
                 if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
                     settleWithLog('cancelled', () => reject(options.signal.reason), options.signal.reason);
                     return;
                 }
-                if (code === 0) {
-                    settleWithLog('succeeded', () => resolve(_spaceTrim.spaceTrim(output)));
+                if (code === 0 && !signal) {
+                    settleWithLog('succeeded', () => {
+                        var _a;
+                        // Cancellation can arrive while the runtime log footer is being flushed.
+                        if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted)
+                            reject(options.signal.reason);
+                        else
+                            resolve(_spaceTrim.spaceTrim(output));
+                    });
                     return;
                 }
-                const failure = new Error(_spaceTrim.spaceTrim(output) || `Command "bash ${scriptPathPosix}" exited with code ${code}`);
-                settleWithLog(`failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}`, () => reject(failure), failure);
+                const failure = new NotAllowed(_spaceTrim.spaceTrim((block) => `
+                Command "bash ${scriptPathPosix}" exited with code ${code !== null && code !== void 0 ? code : 'unknown'}${signal ? ` and signal ${signal}` : ''}.
+                ${block(output)}
+            `));
+                settleWithLog(`failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}${signal ? ` and signal ${signal}` : ''}`, () => reject(failure), failure);
             };
             // Wait for `close`, not only `exit`, because the Bash wrapper can still be flushing its tee process
             // substitutions after the direct shell exits.
             commandProcess.on('close', handleExit);
             commandProcess.on('disconnect', () => {
-                const failure = new Error(`Command "bash ${scriptPathPosix}" disconnected`);
+                const failure = new NotAllowed(_spaceTrim.spaceTrim((block) => `
+                    Command "bash ${scriptPathPosix}" disconnected.
+                    ${block(output)}
+                `));
                 settleWithLog('failed after disconnect', () => reject(failure), failure);
             });
             commandProcess.on('error', (error) => {
-                const failure = new Error(`Command "bash ${scriptPathPosix}" failed: ${error.message}`);
+                const failure = new NotAllowed(_spaceTrim.spaceTrim((block) => `
+                    Command "bash ${scriptPathPosix}" failed: ${error.message}
+                    ${block(output)}
+                `));
                 settleWithLog('failed before completion', () => reject(failure), failure);
             });
             /** Reuses the process-tree terminator; settlement waits for stream closure and the trace footer. */
@@ -26437,6 +26518,11 @@
         }
     }
 
+    /** Quotes one literal argument, including spaces and shell metacharacters, for a generated Bash script. */
+    function quoteBashArgument(value) {
+        return `'${value.replace(/'/gu, "'\\''")}'`;
+    }
+
     /**
      * Builds the shell script that runs GitHub Copilot CLI with the prompt and coding context.
      */
@@ -26446,7 +26532,7 @@
         const modelArgument = options.model ? ` --model ${options.model}` : '';
         const thinkingLevelArgument = options.thinkingLevel ? ` --reasoning-effort ${options.thinkingLevel}` : '';
         return spaceTrim((block) => `
-            cd "${projectPath}"
+            cd ${quoteBashArgument(projectPath)}
 
             if [ -f .env ]; then
             set -a
@@ -26887,7 +26973,7 @@
             ...(options.isMachineReadableProgressEnabled ? ['    --json \\'] : []),
             '    --local-provider none \\',
             `    --sandbox ${options.sandbox} \\`,
-            `    -C ${projectPath} \\`,
+            `    -C ${quoteBashArgument(projectPath)} \\`,
             '    --skip-git-repo-check \\',
             `    <<'${delimiter}'`,
             '',
@@ -29223,7 +29309,7 @@
             ...buildOptionalSessionRow('Server', options.config.serverUrl
                 ? buildTerminalUrlLink(options.config.serverUrl, bodyWidth - SESSION_LABEL_WIDTH - 1)
                 : undefined),
-            ...buildOptionalSessionRow('Test', options.config.testCommand),
+            ...buildOptionalSessionRow('Check', options.config.checkCommand),
         ];
         return [
             {
@@ -31717,7 +31803,7 @@
         return {
             dryRun: false,
             context: undefined,
-            testCommand: undefined,
+            checkCommand: undefined,
             preserveLogs: false,
             noUi: options.noUi,
             thinkingLevel: options.thinkingLevel,
@@ -32819,40 +32905,207 @@
     }
 
     /**
-     * Maximum amount of test output embedded into an agent prompt.
+     * Maximum amount of check output embedded into an agent prompt.
+     */
+    const MAX_CHECK_OUTPUT_CHARS = 12000;
+    /**
+     * Limits check output while keeping the end of the output, where check tools usually print the failure summary.
+     */
+    function limitCheckOutput(checkOutput) {
+        const normalizedCheckOutput = checkOutput.trim();
+        if (normalizedCheckOutput.length <= MAX_CHECK_OUTPUT_CHARS) {
+            return normalizedCheckOutput;
+        }
+        return `[..., check output truncated to the last ${MAX_CHECK_OUTPUT_CHARS} characters...]\n${normalizedCheckOutput.slice(-MAX_CHECK_OUTPUT_CHARS)}`;
+    }
+
+    /**
+     * Modes supported by `ptbk coder run --check-before`.
+     */
+    const CHECK_BEFORE_MODE_VALUES = ['no', 'yes-and-fail', 'yes-and-fix'];
+    /**
+     * Default check command used when a pre-coding mode is enabled without an explicit `--check` command.
+     */
+    const DEFAULT_CODER_CHECK_COMMAND = 'npm run check';
+    /**
+     * Resolves the shared command without enabling checks when both command and preflight mode are absent.
+     */
+    function resolveCoderCheckCommand(checkCommand, checkBefore = 'no') {
+        return checkCommand !== null && checkCommand !== void 0 ? checkCommand : (checkBefore === 'no' ? undefined : DEFAULT_CODER_CHECK_COMMAND);
+    }
+    /**
+     * Checks whether a value is a supported `--check-before` mode.
+     */
+    function isCheckBeforeMode(value) {
+        return CHECK_BEFORE_MODE_VALUES.includes(value);
+    }
+
+    /** Conventional root command boundaries, including subshells and environment assignments. */
+    const SCRIPT_COMMAND_PREFIX = String.raw `(?:^|&&|\|\||;|\n|[()])\s*(?:(?:env\s+)?[A-Za-z_]\w*=(?:[^\s'";&|()]+|"[^"]*"|'[^']*')\s+)*`;
+    /** Package-manager options which do not select a different directory or workspace. */
+    const QUIET_OPTIONS = String.raw `(?:(?:--silent|--quiet|-s|-q)\s+)*`;
+    /** Quoted script names preserve spaces, while unquoted names use conventional npm identifier characters. */
+    const SCRIPT_NAME = String.raw `(?:(["'])([^"'\r\n]+)\1|([\w:.-]+))(?=\s|$|[;&|()])`;
+    /** Quoted payloads and escaped characters are opaque to this configuration inspection. */
+    const OPAQUE_ARGUMENT = String.raw `"(?:\\.|[^"\\])*"|'[^']*'|\\[\s\S]`;
+    /** Only references before a conventional directory change can confidently belong to the root package. */
+    const DIRECTORY_CHANGE_COMMAND = new RegExp(`${SCRIPT_COMMAND_PREFIX}(?:cd|pushd|popd)(?=\\s|$)|(?<argument>${OPAQUE_ARGUMENT})`, 'gu');
+    /** Arguments up to the next conventional command boundary, preserving quoted payloads as opaque text. */
+    const SCRIPT_ARGUMENTS = new RegExp(String.raw `^(?:${OPAQUE_ARGUMENT}|[^;&|\n()'"\\])*`, 'u');
+    /** Package-manager options that select validation from a different directory or workspace. */
+    const PROJECT_OVERRIDE_OPTION = /\s(?:--prefix|--dir|--cwd|-C|--workspace|--workspaces|-w|--filter)(?:\s|=|$)/u;
+    /**
+     * Reads conventional npm/pnpm/yarn script references for configuration inspection.
+     * Commands are still executed verbatim by the existing shell runner; this helper neither parses nor rewrites shells.
+     * Options selecting other workspaces remain opaque so their scripts are not mistaken for root validation.
+     * Inspection stops at the first directory change; quoted examples do not change the inspected workspace.
      */
-    const MAX_TEST_OUTPUT_CHARS = 12000;
+    function projectScriptReferences(command) {
+        var _a;
+        const directoryChange = [...command.matchAll(DIRECTORY_CHANGE_COMMAND)].find((match) => { var _a; return ((_a = match.groups) === null || _a === void 0 ? void 0 : _a.argument) === undefined; });
+        if (directoryChange)
+            command = command.slice(0, directoryChange.index);
+        const references = [
+            ...command.matchAll(new RegExp(`${SCRIPT_COMMAND_PREFIX}(?:npm|pnpm|yarn)\\s+${QUIET_OPTIONS}(?:run(?:-script)?\\s+${QUIET_OPTIONS}${SCRIPT_NAME}|(?:test|t)(?=\\s|$|[;&|()]))` +
+                `|(?<argument>${OPAQUE_ARGUMENT})`, 'gu')),
+        ]
+            .filter((match) => isRootProjectScriptReference(command, match))
+            .map((match) => { var _a, _b; return (_b = (_a = match[2]) !== null && _a !== void 0 ? _a : match[3]) !== null && _b !== void 0 ? _b : 'test'; });
+        for (const match of command.matchAll(new RegExp(`${SCRIPT_COMMAND_PREFIX}(?:pnpm|yarn)\\s+${QUIET_OPTIONS}(?!run\\b|-)${SCRIPT_NAME}` +
+            `|(?<argument>${OPAQUE_ARGUMENT})`, 'gu')))
+            if (isRootProjectScriptReference(command, match))
+                references.push(((_a = match[2]) !== null && _a !== void 0 ? _a : match[3]));
+        return [...new Set(references)];
+    }
+    /** Excludes quoted examples and package-manager directory overrides without altering the executed command. */
+    function isRootProjectScriptReference(command, match) {
+        var _a, _b, _c, _d;
+        if (((_a = match.groups) === null || _a === void 0 ? void 0 : _a.argument) !== undefined)
+            return false;
+        const argumentsText = (_c = (_b = command.slice(match.index + match[0].length).match(SCRIPT_ARGUMENTS)) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : '';
+        // Flags after npm's `--` separator belong to the leaf tool, rather than the package manager.
+        const packageManagerArguments = (_d = argumentsText.split(/\s--(?:\s|$)/u)[0]) !== null && _d !== void 0 ? _d : '';
+        return !PROJECT_OVERRIDE_OPTION.test(packageManagerArguments);
+    }
+
     /**
-     * Limits test output while keeping the end of the output, where test runners usually print the failure summary.
+     * Failing setup placeholder used only when initialization finds no usable project validation scripts.
      */
-    function limitTestOutput(testOutput) {
-        const normalizedTestOutput = testOutput.trim();
-        if (normalizedTestOutput.length <= MAX_TEST_OUTPUT_CHARS) {
-            return normalizedTestOutput;
+    const CHECK_SETUP_PLACEHOLDER_COMMAND = `node -e "console.error('Configure package.json scripts.check with project validation commands before running Coder.'); process.exit(1)"`;
+    /** Retired generated script names inspected only to report stale caller configuration. */
+    const LEGACY_CHECK_SCRIPT_NAMES$1 = new Set(['test-for-ptbk-coder', 'check-for-ptbk-coder']);
+    /**
+     * A missing or unconfigured project check needs project-owner setup, rather than model repair retries.
+     */
+    class CoderCheckSetupError extends NotAllowed {
+        /** Creates an actionable project check setup error. */
+        constructor(details) {
+            super(_spaceTrim.spaceTrim(`
+            Project check is not configured: ${details}
+
+            Configure the selected validation scripts in \`package.json\`. The canonical aggregate is \`scripts.check\`, invoked as \`${DEFAULT_CODER_CHECK_COMMAND}\`.
+            Coder will not replace missing validation with a successful placeholder or tests alone.
+        `));
+            Object.setPrototypeOf(this, CoderCheckSetupError.prototype);
         }
-        return `[..., test output truncated to the last ${MAX_TEST_OUTPUT_CHARS} characters...]\n${normalizedTestOutput.slice(-MAX_TEST_OUTPUT_CHARS)}`;
     }
+    /**
+     * Detects the generated setup placeholder and the conventional npm unconfigured-test placeholder.
+     */
+    function isCheckSetupRequired(command) {
+        return (!command.trim() ||
+            command.includes('Configure package.json scripts.check') ||
+            /no test specified/iu.test(command));
+    }
+    /**
+     * Inspects root project check references before an initial check or repair loop can start.
+     * Flags and shell composition do not bypass setup validation; execution still uses the existing shell runner.
+     */
+    async function assertProjectCheckIsConfigured(command, projectPath) {
+        var _a, _b;
+        if (!command)
+            return;
+        const references = projectScriptReferences(command);
+        if (references.length === 0)
+            return;
+        let packageJson;
+        try {
+            packageJson = JSON.parse(await promises.readFile(path.join(projectPath, 'package.json'), 'utf-8'));
+        }
+        catch (error) {
+            throw new CoderCheckSetupError(`cannot read package.json (${error instanceof Error ? error.message : String(error)}).`);
+        }
+        for (const reference of references) {
+            if (LEGACY_CHECK_SCRIPT_NAMES$1.has(reference) && ((_a = packageJson === null || packageJson === void 0 ? void 0 : packageJson.scripts) === null || _a === void 0 ? void 0 : _a[reference]) === undefined) {
+                throw new CoderCheckSetupError(`scripts.${reference} is missing and is no longer initialized by Coder. Update this caller to \`--check "${DEFAULT_CODER_CHECK_COMMAND}"\`; no compatibility alias is generated.`);
+            }
+            assertProjectCheckScriptsAreConfigured((_b = packageJson === null || packageJson === void 0 ? void 0 : packageJson.scripts) !== null && _b !== void 0 ? _b : {}, reference);
+        }
+    }
+    /**
+     * Validates the project-owned check definition without running commands or changing its scope.
+     * Initialization and execution use this same setup diagnostic for missing leaves and recursive callers.
+     */
+    function assertProjectCheckScriptsAreConfigured(scripts, name = 'check') {
+        assertReferencedScriptsAreConfigured(name, scripts, new Set());
+    }
+    /** Detects missing/placeholder leaf validation and recursive npm callers before a model repair loop can start. */
+    function assertReferencedScriptsAreConfigured(name, scripts, ancestors) {
+        if (ancestors.has(name))
+            throw new CoderCheckSetupError(`scripts.${name} recursively calls the check pipeline.`);
+        const command = scripts[name];
+        if (typeof command !== 'string' || isCheckSetupRequired(command)) {
+            throw new CoderCheckSetupError(`scripts.${name} is missing, empty, or contains a setup placeholder.`);
+        }
+        if (/^coder:(?:run|fix)$/u.test(name) || /\b(?:ptbk|promptbook)\s+coder\s+(?:run|fix)\b/u.test(command)) {
+            throw new CoderCheckSetupError(`scripts.${name} calls Coder execution instead of project validation.`);
+        }
+        const nextAncestors = new Set([...ancestors, name]);
+        // The shared inspector keeps root references before a directory change and leaves child workspaces opaque.
+        for (const reference of projectScriptReferences(command)) {
+            assertReferencedScriptsAreConfigured(reference, scripts, nextAncestors);
+        }
+        for (const prefix of ['pre', 'post']) {
+            const lifecycleName = `${prefix}${name}`;
+            if (scripts[lifecycleName] !== undefined)
+                assertReferencedScriptsAreConfigured(lifecycleName, scripts, nextAncestors);
+        }
+    }
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
     /**
-     * Runs the configured verification command inside the project root and returns its output.
+     * Runs the configured check command inside the project root and returns its output.
      */
-    async function runPromptTestCommand(options) {
+    async function runPromptCheckCommand(options) {
+        await assertProjectCheckIsConfigured(options.command, options.projectPath);
         const projectPath = toPosixPath(options.projectPath);
         return await $runGoScriptWithOutput({
             scriptPath: options.scriptPath,
+            projectPath: options.projectPath,
             scriptContent: spaceTrim(`
-            cd "${projectPath}"
+            cd ${quoteBashArgument(projectPath)} || exit 1
             ${options.command}
         `),
             logPath: options.logPath,
             preserveArtifactsOnSuccess: options.preserveArtifactsOnSuccess,
+            signal: options.signal,
         });
     }
 
     /**
-     * Maximum number of coding attempts allowed for the same prompt when verification keeps failing.
+     * Shared constraints for initial repair PRDs and post-prompt check feedback.
+     */
+    const CHECK_REPAIR_INSTRUCTIONS = _spaceTrim.spaceTrim(`
+    Fix the underlying lint, typechecking, build, generated-code consistency, or test failure without weakening validation.
+    Do not delete assertions, disable lint rules, remove failing checks from the aggregate, lower quality thresholds,
+    skip a build, or force exit code zero merely to obtain a pass. Keep the project's chosen check scope intact.
+    Missing or unconfigured validation requires project-owner setup; never replace it with a meaningless green result.
+`);
+
+    /**
+     * Maximum number of coding attempts allowed for the same prompt when check keeps failing.
      */
-    const MAX_PROMPT_TEST_ATTEMPTS = 3;
+    const MAX_PROMPT_CHECK_ATTEMPTS = 3;
     /**
      * File extension used by generated shell scripts.
      */
@@ -32860,12 +33113,18 @@
     /**
      * Runs one coding prompt and, when configured, verifies it with a shell command that can feed failures back.
      */
-    async function runPromptWithTestFeedback(options) {
-        var _a, _b, _c, _d;
-        const normalizedTestCommand = (_a = options.testCommand) === null || _a === void 0 ? void 0 : _a.trim();
+    async function runPromptWithCheckFeedback(options) {
+        var _a, _b, _c, _d, _e;
+        (_a = options.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
+        const normalizedCheckCommand = (_b = options.checkCommand) === null || _b === void 0 ? void 0 : _b.trim();
+        // Injected executors own their setup validation, just as they own command execution. The shared real executor
+        // validates again after each agent attempt in case it changed the project's validation configuration.
+        if (!options.runPromptCheckCommandExecutor) {
+            await assertProjectCheckIsConfigured(normalizedCheckCommand, options.projectPath);
+        }
         const stepTracker = createCoderRunStepTracker(options.onStepStarted);
-        if (!normalizedTestCommand) {
-            (_b = options.onAttemptStarted) === null || _b === void 0 ? void 0 : _b.call(options, 1);
+        if (!normalizedCheckCommand) {
+            (_c = options.onAttemptStarted) === null || _c === void 0 ? void 0 : _c.call(options, 1);
             await waitForPromptAttemptPauseCheckpoint(options.waitForPauseCheckpoint, options.runner.name, 1);
             const result = await runRunnerPromptStep({
                 runOptions: options,
@@ -32875,10 +33134,10 @@
             });
             return { ...result, attemptCount: 1, steps: stepTracker.steps };
         }
-        const runPromptTestCommandExecutor = (_c = options.runPromptTestCommandExecutor) !== null && _c !== void 0 ? _c : runPromptTestCommand;
+        const runPromptCheckCommandExecutor = (_d = options.runPromptCheckCommandExecutor) !== null && _d !== void 0 ? _d : runPromptCheckCommand;
         let promptForCurrentAttempt = options.prompt;
-        for (let attemptCount = 1; attemptCount <= MAX_PROMPT_TEST_ATTEMPTS; attemptCount++) {
-            (_d = options.onAttemptStarted) === null || _d === void 0 ? void 0 : _d.call(options, attemptCount);
+        for (let attemptCount = 1; attemptCount <= MAX_PROMPT_CHECK_ATTEMPTS; attemptCount++) {
+            (_e = options.onAttemptStarted) === null || _e === void 0 ? void 0 : _e.call(options, attemptCount);
             await waitForPromptAttemptPauseCheckpoint(options.waitForPauseCheckpoint, options.runner.name, attemptCount);
             const result = await runRunnerPromptStep({
                 runOptions: options,
@@ -32886,42 +33145,44 @@
                 kind: attemptCount === 1 ? 'implementation' : 'fixing',
                 stepTracker,
             });
-            await waitForVerificationPauseCheckpoint(options.waitForPauseCheckpoint, normalizedTestCommand, attemptCount);
-            console.info(colors__default["default"].gray(`Running verification command after attempt #${attemptCount}: ${normalizedTestCommand}`));
-            const failedVerification = await runVerificationStep({
-                runPromptTestCommandExecutor,
-                testCommand: normalizedTestCommand,
+            await waitForCheckPauseCheckpoint(options.waitForPauseCheckpoint, normalizedCheckCommand, attemptCount);
+            console.info(colors__default["default"].gray(`Running check command after attempt #${attemptCount}: ${normalizedCheckCommand}`));
+            const failedCheck = await runCheckStep({
+                runPromptCheckCommandExecutor,
+                checkCommand: normalizedCheckCommand,
                 runOptions: options,
                 stepTracker,
             });
-            if (failedVerification === undefined) {
+            if (failedCheck === undefined) {
                 return { ...result, attemptCount, steps: stepTracker.steps };
             }
-            const fullVerificationOutput = formatUnknownErrorDetails(failedVerification.error);
-            const feedbackVerificationOutput = limitTestOutput(fullVerificationOutput);
-            if (attemptCount >= MAX_PROMPT_TEST_ATTEMPTS) {
-                console.error(colors__default["default"].red(`Verification failed for ${options.promptLabel} after ${attemptCount} attempts.`));
-                throw new Error(buildFinalVerificationFailureMessage({
+            const fullCheckOutput = formatUnknownErrorDetails(failedCheck.error);
+            const feedbackCheckOutput = limitCheckOutput(fullCheckOutput);
+            if (attemptCount >= MAX_PROMPT_CHECK_ATTEMPTS) {
+                console.error(colors__default["default"].red(`Check failed for ${options.promptLabel} after ${attemptCount} attempts.`));
+                throw new NotAllowed(buildFinalCheckFailureMessage({
                     promptLabel: options.promptLabel,
-                    testCommand: normalizedTestCommand,
+                    checkCommand: normalizedCheckCommand,
                     attemptCount,
-                    verificationOutput: fullVerificationOutput,
+                    checkOutput: fullCheckOutput,
                 }));
             }
-            console.warn(colors__default["default"].yellow(`Verification failed for ${options.promptLabel} on attempt #${attemptCount}. Sending feedback to ${options.runner.name} and retrying...`));
-            promptForCurrentAttempt = appendCoderContext(options.prompt, buildVerificationFeedback({
-                testCommand: normalizedTestCommand,
+            console.warn(colors__default["default"].yellow(`Check failed for ${options.promptLabel} on attempt #${attemptCount}. Sending feedback to ${options.runner.name} and retrying...`));
+            promptForCurrentAttempt = appendCoderContext(options.prompt, buildCheckFeedback({
+                checkCommand: normalizedCheckCommand,
                 failedAttemptCount: attemptCount,
-                verificationOutput: feedbackVerificationOutput,
+                checkOutput: feedbackCheckOutput,
             }));
         }
-        throw new Error('Unexpected prompt verification state.');
+        throw new UnexpectedError('Unexpected prompt check state.');
     }
     /**
      * Runs one coding attempt through the runner, timing it and recording it as an implementation or fixing step.
      */
     async function runRunnerPromptStep(options) {
+        var _a, _b;
         const { runOptions, prompt, kind, stepTracker } = options;
+        (_a = runOptions.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
         await stepTracker.startStep(kind);
         const stepStartedTimeMs = Date.now();
         const result = await runOptions.runner.runPrompt({
@@ -32931,33 +33192,41 @@
             logPath: runOptions.logPath,
             preserveArtifactsOnSuccess: runOptions.preserveArtifactsOnSuccess,
             waitForPauseCheckpoint: runOptions.waitForPauseCheckpoint,
+            ...(runOptions.signal ? { signal: runOptions.signal } : {}),
         });
+        (_b = runOptions.signal) === null || _b === void 0 ? void 0 : _b.throwIfAborted();
         stepTracker.finishStep({ kind, usage: result.usage, durationMs: Date.now() - stepStartedTimeMs }, result.loginMethod);
         return result;
     }
     /**
-     * Runs the verification command, timing it and recording it as a testing step regardless of the outcome, and
-     * returns the failure (or `undefined` when the verification passed).
+     * Runs the check command, timing it and recording it as a checking step regardless of the outcome, and
+     * returns the failure (or `undefined` when the check passed).
      */
-    async function runVerificationStep(options) {
-        const { runPromptTestCommandExecutor, testCommand, runOptions, stepTracker } = options;
-        await stepTracker.startStep('testing');
+    async function runCheckStep(options) {
+        var _a, _b, _c;
+        const { runPromptCheckCommandExecutor, checkCommand, runOptions, stepTracker } = options;
+        (_a = runOptions.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
+        await stepTracker.startStep('checking');
         const stepStartedTimeMs = Date.now();
         try {
-            await runPromptTestCommandExecutor({
-                command: testCommand,
+            await runPromptCheckCommandExecutor({
+                command: checkCommand,
                 projectPath: runOptions.projectPath,
-                scriptPath: buildPromptTestScriptPath(runOptions.scriptPath),
+                scriptPath: buildPromptCheckScriptPath(runOptions.scriptPath),
                 logPath: runOptions.logPath,
                 preserveArtifactsOnSuccess: runOptions.preserveArtifactsOnSuccess,
+                ...(runOptions.signal ? { signal: runOptions.signal } : {}),
             });
+            (_b = runOptions.signal) === null || _b === void 0 ? void 0 : _b.throwIfAborted();
             return undefined;
         }
         catch (error) {
+            if (error instanceof CoderCheckSetupError || ((_c = runOptions.signal) === null || _c === void 0 ? void 0 : _c.aborted))
+                throw error;
             return { error };
         }
         finally {
-            stepTracker.finishStep({ kind: 'testing', usage: null, durationMs: Date.now() - stepStartedTimeMs });
+            stepTracker.finishStep({ kind: 'checking', usage: null, durationMs: Date.now() - stepStartedTimeMs });
         }
     }
     /**
@@ -32971,13 +33240,13 @@
         }));
     }
     /**
-     * Waits for a pause checkpoint immediately before one verification command begins.
+     * Waits for a pause checkpoint immediately before one check command begins.
      */
-    async function waitForVerificationPauseCheckpoint(waitForPauseCheckpoint, testCommand, attemptCount) {
+    async function waitForCheckPauseCheckpoint(waitForPauseCheckpoint, checkCommand, attemptCount) {
         await (waitForPauseCheckpoint === null || waitForPauseCheckpoint === void 0 ? void 0 : waitForPauseCheckpoint({
-            checkpointLabel: buildVerificationPauseLabel(attemptCount),
+            checkpointLabel: buildCheckPauseLabel(attemptCount),
             phase: 'verifying',
-            statusMessage: `Running verification after attempt #${attemptCount}: ${testCommand}`,
+            statusMessage: `Running check after attempt #${attemptCount}: ${checkCommand}`,
         }));
     }
     /**
@@ -32993,51 +33262,53 @@
         return `Calling ${runnerName} (attempt ${attemptCount})`;
     }
     /**
-     * Builds the human-readable pause label used before one verification command begins.
+     * Builds the human-readable pause label used before one check command begins.
      */
-    function buildVerificationPauseLabel(attemptCount) {
-        return `running verification after attempt #${attemptCount}`;
+    function buildCheckPauseLabel(attemptCount) {
+        return `running check after attempt #${attemptCount}`;
     }
     /**
-     * Builds one feedback block appended to the next coding attempt after tests fail.
+     * Builds one feedback block appended to the next coding attempt after checks fail.
      */
-    function buildVerificationFeedback({ testCommand, failedAttemptCount, verificationOutput, }) {
+    function buildCheckFeedback({ checkCommand, failedAttemptCount, checkOutput, }) {
         const nextAttemptCount = failedAttemptCount + 1;
         return spaceTrim((block) => `
-            The previous implementation did not pass the required verification command.
+            The previous implementation did not pass the required check command.
 
-            ## Automated verification feedback
-            - Retry attempt: ${nextAttemptCount} of ${MAX_PROMPT_TEST_ATTEMPTS}
-            - Verification command: \`${testCommand}\`
-            - Update the current implementation so the verification command passes without breaking the original task requirements.
+            ## Automated check feedback
+            - Retry attempt: ${nextAttemptCount} of ${MAX_PROMPT_CHECK_ATTEMPTS}
+            - Check command: \`${checkCommand}\`
+            - Update the current implementation so the check command passes without breaking the original task requirements.
 
-            ### Verification output
+            ${block(CHECK_REPAIR_INSTRUCTIONS)}
+
+            ### Check output
             \`\`\`
-            ${block(verificationOutput)}
+            ${block(checkOutput)}
             \`\`\`
         `);
     }
     /**
-     * Builds the final error message written when verification still fails after all retries.
+     * Builds the final error message written when check still fails after all retries.
      */
-    function buildFinalVerificationFailureMessage({ promptLabel, testCommand, attemptCount, verificationOutput, }) {
+    function buildFinalCheckFailureMessage({ promptLabel, checkCommand, attemptCount, checkOutput, }) {
         return spaceTrim((block) => `
-            Verification command \`${testCommand}\` failed for \`${promptLabel}\` after ${attemptCount} attempts.
+            Check command \`${checkCommand}\` failed for \`${promptLabel}\` after ${attemptCount} attempts.
 
-            ### Verification output
+            ### Check output
             \`\`\`
-            ${block(verificationOutput)}
+            ${block(checkOutput)}
             \`\`\`
         `);
     }
     /**
-     * Derives a dedicated temp-script path for verification commands.
+     * Derives a dedicated temp-script path for check commands.
      */
-    function buildPromptTestScriptPath(scriptPath) {
+    function buildPromptCheckScriptPath(scriptPath) {
         if (scriptPath.toLowerCase().endsWith(SHELL_SCRIPT_EXTENSION)) {
-            return `${scriptPath.slice(0, -SHELL_SCRIPT_EXTENSION.length)}.test.sh`;
+            return `${scriptPath.slice(0, -SHELL_SCRIPT_EXTENSION.length)}.check.sh`;
         }
-        return `${scriptPath}.test.sh`;
+        return `${scriptPath}.check.sh`;
     }
 
     /**
@@ -41937,16 +42208,16 @@
      * Answers one queued `.book` message thread and moves it to `messages/finished`.
      */
     async function tickAgentMessages(options, tickOptions = {}) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         validateAgentRunOptions(options);
-        const projectPath = tickOptions.projectPath || process.cwd();
+        const projectPath = (_b = (_a = tickOptions.projectPath) !== null && _a !== void 0 ? _a : options.projectPath) !== null && _b !== void 0 ? _b : process.cwd();
         let queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
         let queuedMessage = resolveSelectedQueuedMessage(queueSnapshot, tickOptions.queuedMessage);
         if (!queuedMessage) {
             announceNoQueuedMessages(tickOptions);
             return { isMessageProcessed: false };
         }
-        if (tickOptions.uiHandle && !((_a = tickOptions.uiPresentation) === null || _a === void 0 ? void 0 : _a.isSharedDashboard)) {
+        if (tickOptions.uiHandle && !((_c = tickOptions.uiPresentation) === null || _c === void 0 ? void 0 : _c.isSharedDashboard)) {
             updateAgentRunUiForPulling(tickOptions.uiHandle, queueSnapshot, 'Pulling latest changes before answering the next message');
         }
         const autoPullTimestamp = await pullLatestChangesForAgentQueueIfEnabled({
@@ -41958,7 +42229,7 @@
             queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
             queuedMessage = resolveSelectedQueuedMessage(queueSnapshot, tickOptions.queuedMessage);
             if (!queuedMessage) {
-                if (tickOptions.uiHandle && !((_b = tickOptions.uiPresentation) === null || _b === void 0 ? void 0 : _b.isSharedDashboard)) {
+                if (tickOptions.uiHandle && !((_d = tickOptions.uiPresentation) === null || _d === void 0 ? void 0 : _d.isSharedDashboard)) {
                     updateAgentRunUiForWatching(tickOptions.uiHandle, queueSnapshot);
                 }
                 announceNoQueuedMessages(tickOptions);
@@ -41977,24 +42248,24 @@
                 actualRunnerModel,
                 queuedMessage,
                 uiHandle,
-                isSharedDashboard: (_c = tickOptions.uiPresentation) === null || _c === void 0 ? void 0 : _c.isSharedDashboard,
+                isSharedDashboard: (_e = tickOptions.uiPresentation) === null || _e === void 0 ? void 0 : _e.isSharedDashboard,
             });
-            if (!((_d = tickOptions.uiPresentation) === null || _d === void 0 ? void 0 : _d.isSharedDashboard)) {
-                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.updateProgress(((_e = tickOptions.uiPresentation) === null || _e === void 0 ? void 0 : _e.completedProgressStats) ||
+            if (!((_f = tickOptions.uiPresentation) === null || _f === void 0 ? void 0 : _f.isSharedDashboard)) {
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.updateProgress(((_g = tickOptions.uiPresentation) === null || _g === void 0 ? void 0 : _g.completedProgressStats) ||
                     createAgentQueueProgressSnapshot({
                         finishedMessageCount: queueSnapshot.finishedMessageCount + 1,
                         queuedMessages: removeQueuedMessageFromSnapshot(queueSnapshot, queuedMessage),
                     }));
-                if ((_f = tickOptions.uiPresentation) === null || _f === void 0 ? void 0 : _f.completedAgentStatusLines) {
+                if ((_h = tickOptions.uiPresentation) === null || _h === void 0 ? void 0 : _h.completedAgentStatusLines) {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAgentStatusLines([...tickOptions.uiPresentation.completedAgentStatusLines]);
                 }
-                if ((_g = tickOptions.uiPresentation) === null || _g === void 0 ? void 0 : _g.completedAgentStatusTableRows) {
+                if ((_j = tickOptions.uiPresentation) === null || _j === void 0 ? void 0 : _j.completedAgentStatusTableRows) {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAgentStatusTableRows([...tickOptions.uiPresentation.completedAgentStatusTableRows]);
                 }
-                if ((_h = tickOptions.uiPresentation) === null || _h === void 0 ? void 0 : _h.completedMessagePreviewLines) {
+                if ((_k = tickOptions.uiPresentation) === null || _k === void 0 ? void 0 : _k.completedMessagePreviewLines) {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewLines([...tickOptions.uiPresentation.completedMessagePreviewLines]);
                 }
-                if ((_j = tickOptions.uiPresentation) === null || _j === void 0 ? void 0 : _j.completedMessagePreviewSections) {
+                if ((_l = tickOptions.uiPresentation) === null || _l === void 0 ? void 0 : _l.completedMessagePreviewSections) {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewSections([
                         ...tickOptions.uiPresentation.completedMessagePreviewSections,
                     ]);
@@ -42078,7 +42349,7 @@
         try {
             try {
                 promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => {
-                    const runResult = await runPromptWithTestFeedback({
+                    const runResult = await runPromptWithCheckFeedback({
                         runner,
                         prompt,
                         scriptPath,
@@ -42505,12 +42776,12 @@
      * Watches all direct child agent repositories from the current directory in one shared session.
      */
     async function runMultipleAgentMessages(options, controls = {}) {
-        var _a, _b;
+        var _a, _b, _c;
         validateAgentRunOptions(options);
         validateAgentWatchOptions('ptbk agent-folder run-multiple', options);
-        const rootPath = process.cwd();
+        const rootPath = (_a = options.projectPath) !== null && _a !== void 0 ? _a : process.cwd();
         const shouldContinue = controls.shouldContinue || (() => just(true));
-        const queuePollIntervalMs = (_a = controls.queuePollIntervalMs) !== null && _a !== void 0 ? _a : MULTI_AGENT_QUEUE_POLL_INTERVAL_MS;
+        const queuePollIntervalMs = (_b = controls.queuePollIntervalMs) !== null && _b !== void 0 ? _b : MULTI_AGENT_QUEUE_POLL_INTERVAL_MS;
         const watchErrorLogDirectoryPath = controls.watchErrorLogDirectoryPath || rootPath;
         const ignoreMatcher = createAgentIgnoreMatcher(options.ignorePatterns);
         const githubSynchronizer = new MultipleAgentGithubSynchronizer();
@@ -42534,7 +42805,7 @@
                         watchErrorLogDirectoryPath,
                     });
                     isWatchSessionInitialized = true;
-                    (_b = controls.onUiInitialized) === null || _b === void 0 ? void 0 : _b.call(controls, uiPresenter.uiHandle);
+                    (_c = controls.onUiInitialized) === null || _c === void 0 ? void 0 : _c.call(controls, uiPresenter.uiHandle);
                     if (!uiPresenter.uiHandle) {
                         console.info(colors__default["default"].green('Watching direct child agent repositories for queued messages.'));
                     }
@@ -43793,6 +44064,7 @@
      * @private internal registration helper for workspace CLI commands
      */
     function addWorkspaceRepositoryOptions(command) {
+        addProjectPathOption(command);
         if (!command.options.some((option) => option.long === '--no-questions'))
             addQuestionsOption(command);
         command.addHelpText('after', `\n${WORKSPACE_REPOSITORY_DESCRIPTION}\n`);
@@ -43894,17 +44166,7 @@
      * @private shared workspace discovery for CLI commands
      */
     async function $resolveWorkspaceRepository(projectDirectory = process.cwd()) {
-        const requestedPath = path.resolve(projectDirectory);
-        let projectPath;
-        try {
-            projectPath = await promises.realpath(requestedPath);
-            if (!(await promises.stat(projectPath)).isDirectory()) {
-                throw new EnvironmentMismatchError(`The project path \`${requestedPath}\` is not a directory.`);
-            }
-        }
-        catch (error) {
-            throw new EnvironmentMismatchError(_spaceTrim.spaceTrim(`Cannot access project directory \`${requestedPath}\`. Check that it exists and is accessible.\n\n${describeWorkspaceError(error)}`));
-        }
+        const projectPath = await resolveProjectDirectory(projectDirectory);
         return $inspectWorkspaceRepository(projectPath);
     }
     /**
@@ -44016,7 +44278,7 @@
             // Git may skip damaged inner metadata and find a valid parent. Do not silently use that parent
             // for a project whose own checkout needs repair.
             await $assertNoBrokenRepositoryMetadata(projectPath, repositoryRoot);
-            const gitDirectory = (await $runWorkspaceGit(projectPath, ['rev-parse', '--absolute-git-dir'])).trim();
+            const gitDirectory = await promises.realpath((await $runWorkspaceGit(projectPath, ['rev-parse', '--absolute-git-dir'])).trim());
             // Also validate the index and metadata, without refreshing the index or depending on an existing commit.
             await $runWorkspaceGit(projectPath, ['status', '--porcelain', '--untracked-files=no']);
             return { projectPath, repositoryRoot, gitDirectory, repositoryStatus: 'reused' };
@@ -44344,10 +44606,15 @@
         addQuestionsOption(command);
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (descriptionArgument, cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { priority, template: templateOption } = cliOptions;
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
-            const workspace = await $preflightWorkspaceRepository({ policy: 'mutate', ...questionsOptions });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                ...questionsOptions,
+            });
             const { projectPath } = workspace;
             const description = await resolveCoderPromptDescription(descriptionArgument, questionsOptions);
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
@@ -44570,7 +44837,9 @@
         `));
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'read-only',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
@@ -44811,8 +45080,10 @@
         command.option('--limit <candidate-count>', 'Create at most this many refactor prompts, keeping the most important candidates', createPositiveIntegerOptionParser('--limit'));
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions;
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
@@ -44846,8 +45117,10 @@
         command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { priority = 0 } = cliOptions;
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'read-only',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
@@ -45001,10 +45274,12 @@
         addCoderGitSyncOptions(command);
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { count: countOption, template: templateOption } = cliOptions;
             const boilerplateCount = parseBoilerplateCount(countOption);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
@@ -46043,16 +46318,16 @@
         ...getDefaultCoderProjectPromptTemplateDefinitions().map(createCoderPromptTemplateArtifactDefinition),
     ];
     /**
-     * Initializes artifacts referenced by freshly added scripts. Default Books are ensured separately.
+     * Initializes essential context and artifacts referenced by freshly added scripts. Books are ensured separately.
      *
-     * For artifacts other than role Books, an existing project script does not cause default files to be created.
+     * AGENTS.md is essential even when every script already exists or uses implicit defaults.
      *
      * @private function of `initializeCoderProjectConfiguration`
      */
     async function ensureCoderReferencedArtifacts(projectPath, referencedArtifactPaths) {
         const ensuredArtifacts = [];
         for (const { relativeFilePath, ensureArtifactFile } of CODER_REFERENCED_ARTIFACT_DEFINITIONS) {
-            if (!referencedArtifactPaths.has(relativeFilePath)) {
+            if (relativeFilePath !== AGENTS_FILE_PATH && !referencedArtifactPaths.has(relativeFilePath)) {
                 ensuredArtifacts.push({ relativeFilePath, status: 'not-referenced' });
                 continue;
             }
@@ -46671,7 +46946,7 @@
     /**
      * Name of the npm script which `ptbk coder run` uses to verify the project.
      */
-    const CODER_TEST_SCRIPT_NAME = 'test-for-ptbk-coder';
+    const CHECK_SCRIPT_NAME = 'check';
     /**
      * Default npm scripts initialized by `ptbk coder init`.
      *
@@ -46691,14 +46966,13 @@
         {
             scriptName: 'coder:plan',
             scriptCommand: 'npx ptbk coder plan --harness openai-codex',
-            referencedArtifactPaths: [CODER_PLANNER_AGENT_FILE_PATH, COMMON_PROMPT_TEMPLATE_FILE_PATH],
+            referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH, COMMON_PROMPT_TEMPLATE_FILE_PATH],
         },
         {
             scriptName: 'coder:run',
             scriptCommand: [
                 'npx ptbk coder run --harness openai-codex --thinking-level max',
-                `--context ${formatDisplayPath(AGENTS_FILE_PATH)}`,
-                `--test "npm run ${CODER_TEST_SCRIPT_NAME}" --test-before yes-and-fix`,
+                `--check "npm run ${CHECK_SCRIPT_NAME}" --check-before yes-and-fix`,
             ].join(' '),
             referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH],
         },
@@ -46711,8 +46985,8 @@
         {
             // Note: The verification command of `coder:run` is a project-owned script, so every project can decide
             //       what "verified" means without touching the `coder:run` script itself
-            scriptName: CODER_TEST_SCRIPT_NAME,
-            scriptCommand: 'npm test',
+            scriptName: CHECK_SCRIPT_NAME,
+            scriptCommand: CHECK_SETUP_PLACEHOLDER_COMMAND,
             referencedArtifactPaths: [],
         },
     ];
@@ -46777,12 +47051,13 @@
     /**
      * Ensures one JSON object field contains the provided string-record entries.
      *
-     * Entries which the project already defines are **never** overridden - only missing keys are added,
-     * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+     * Entries are additive unless a caller explicitly supplies a scoped migration callback.
+     * Hand-tuned scripts and settings survive repeated `ptbk coder init`; migrations recognize generated entries only.
      *
      * @private function of `initializeCoderProjectConfiguration`
      */
-    async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }) {
+    async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, transformExistingEntries, }) {
+        var _a;
         if (ensureParentDirectoryPath) {
             await promises.mkdir(path.join(projectPath, ensureParentDirectoryPath), { recursive: true });
         }
@@ -46792,7 +47067,7 @@
         const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
         const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
         const addedEntryKeys = [];
-        const mergedEntries = { ...existingEntries };
+        const mergedEntries = { ...((_a = (await (transformExistingEntries === null || transformExistingEntries === void 0 ? void 0 : transformExistingEntries(existingEntries)))) !== null && _a !== void 0 ? _a : existingEntries) };
         for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
             if (Object.prototype.hasOwnProperty.call(mergedEntries, entryKey)) {
                 // Note: The project already defines this entry, keep its own value untouched
@@ -46801,7 +47076,12 @@
             mergedEntries[entryKey] = entryValue;
             addedEntryKeys.push(entryKey);
         }
-        const hasChanges = fileContent === undefined || addedEntryKeys.length > 0;
+        for (const entryKey of Object.keys(mergedEntries)) {
+            if (!Object.prototype.hasOwnProperty.call(existingEntries, entryKey) && !addedEntryKeys.includes(entryKey)) {
+                addedEntryKeys.push(entryKey);
+            }
+        }
+        const hasChanges = fileContent === undefined || JSON.stringify(mergedEntries) !== JSON.stringify(existingEntries);
         if (!hasChanges) {
             return { status: 'unchanged', addedEntryKeys };
         }
@@ -46890,6 +47170,301 @@
     }
     // Note: [🟡] Code for coder init JSON merging [mergeStringRecordJsonFile](src/cli/cli-commands/coder/mergeStringRecordJsonFile.ts) should never be published outside of `@promptbook/cli`
 
+    /** Old initialized aggregate entries, used only at this migration boundary. */
+    const LEGACY_CHECK_SCRIPT_NAMES = ['test-for-ptbk-coder', 'check-for-ptbk-coder'];
+    /** Conventional project validation scripts, ordered from lightweight checks to tests. */
+    const VALIDATION_SCRIPT_GROUPS = [
+        ['lint', 'test-lint'],
+        ['typecheck', 'type-check', 'type-checking', 'check-types', 'test-types'],
+        ['build', 'test-build'],
+    ];
+    /** Conventional leaf test families used when the project has no usable test aggregate. */
+    const TEST_SCRIPT_GROUPS = [
+        ['test-unit', 'test:unit'],
+        ['test-integration', 'test:integration'],
+        ['test-e2e', 'test:e2e'],
+    ];
+    /** Script names that must never be reached by a generated aggregate. */
+    const NON_VALIDATION_SCRIPT_PATTERN = /^(?:check$|coder:|(?:dev|start|serve|watch|deploy|publish|install|preinstall|postinstall|prepare|reset|clean)(?:$|[:-]))/iu;
+    /** Clearly unsuitable shell bodies are excluded even under a conventional validation name. */
+    const UNSUITABLE_VALIDATION_BODY_PATTERN = /(?:\b(?:ptbk|promptbook)\s+coder\s+(?:run|fix)|\bcoder:(?:run|fix)\b|--watch(?:All)?(?:\b|=)|\b(?:watch|nodemon|concurrently|serve|deploy|publish|install|reset|rm|rmdir|del|remove-item)\b|--if-present|\|\||(?:^|[^&])&(?:$|[^&])|;|\bexit\s+0\b)/iu;
+    /** Npm lifecycle hooks that run implicitly before and after a selected project script. */
+    const SCRIPT_LIFECYCLE_PREFIXES = ['pre', 'post'];
+    /**
+     * Preserves project scripts, creates one canonical check, and migrates only exact generated caller forms.
+     * @private shared package-script preparation for Coder initialization
+     */
+    function prepareCoderPackageJsonScripts(existing, externalCallers = {}) {
+        var _a;
+        const scripts = { ...existing };
+        const migrationInstructions = [];
+        const legacyNames = LEGACY_CHECK_SCRIPT_NAMES.filter((name) => Object.prototype.hasOwnProperty.call(existing, name));
+        let checkScriptSummary;
+        if (Object.prototype.hasOwnProperty.call(existing, 'check')) {
+            checkScriptSummary = 'Preserved project scripts.check exactly; Coder executes npm run check.';
+        }
+        else if (legacyNames.length > 0) {
+            const sourceName = legacyNames[0];
+            const isRecursive = scriptReaches(sourceName, 'check', existing, new Set()) ||
+                scriptReaches(sourceName, sourceName, existing, new Set()) ||
+                scriptReaches(sourceName, 'coder:run', existing, new Set()) ||
+                scriptReaches(sourceName, 'coder:fix', existing, new Set());
+            const conflictingLifecycleNames = SCRIPT_LIFECYCLE_PREFIXES.filter((prefix) => existing[`${prefix}check`] !== undefined &&
+                existing[`${prefix}${sourceName}`] !== existing[`${prefix}check`]).map((prefix) => `${prefix}check`);
+            scripts.check =
+                isRecursive || conflictingLifecycleNames.length > 0
+                    ? CHECK_SETUP_PLACEHOLDER_COMMAND
+                    : existing[sourceName];
+            if (!isRecursive && conflictingLifecycleNames.length === 0) {
+                // npm runs these hooks implicitly. Preserve their bodies as well as the main script's scope.
+                for (const prefix of SCRIPT_LIFECYCLE_PREFIXES) {
+                    const legacyHook = existing[`${prefix}${sourceName}`];
+                    if (legacyHook !== undefined)
+                        scripts[`${prefix}check`] = legacyHook;
+                }
+            }
+            checkScriptSummary = isRecursive
+                ? `Kept recursive scripts.${sourceName} unchanged; configure scripts.check with validation that does not call check or Coder recursively.`
+                : conflictingLifecycleNames.length > 0
+                    ? `Kept scripts.${sourceName} and conflicting ${conflictingLifecycleNames.join(', ')} hooks unchanged; configure scripts.check and its lifecycle hooks to preserve the required validation.`
+                    : `Preserved scripts.${sourceName}'s validation command and npm lifecycle hooks in scripts.check: ${scripts.check}`;
+        }
+        else {
+            const selectedScripts = selectValidationScripts(existing);
+            scripts.check =
+                selectedScripts.length > 0
+                    ? selectedScripts.map((name) => (name === 'test' ? 'npm test' : `npm run ${name}`)).join(' && ')
+                    : CHECK_SETUP_PLACEHOLDER_COMMAND;
+            checkScriptSummary =
+                selectedScripts.length > 0
+                    ? `Generated scripts.check from the available validation scripts (${selectedScripts.join(', ')}): ${scripts.check}`
+                    : 'No usable validation scripts found. scripts.check contains a failing setup placeholder; configure it before running Coder.';
+        }
+        for (const [name, command] of Object.entries(existing)) {
+            if (['check', ...legacyNames].some((verificationName) => name === verificationName ||
+                SCRIPT_LIFECYCLE_PREFIXES.some((prefix) => name === `${prefix}${verificationName}`)))
+                continue;
+            const migratedCaller = migrateGeneratedCoderRunScript(command);
+            if (migratedCaller !== undefined) {
+                // A different existing check is authoritative, but changing a custom legacy caller's scope is not safe.
+                const referencedLegacyName = legacyNames.find((legacyName) => command.includes(legacyName));
+                const isConflictingCustomCheck = referencedLegacyName !== undefined &&
+                    !isLegacyCheckScopePreserved(referencedLegacyName, scripts) &&
+                    !isUnchangedLegacyCheckDefault(referencedLegacyName, scripts);
+                if (!isConflictingCustomCheck)
+                    scripts[name] = migratedCaller;
+            }
+        }
+        for (const legacyName of legacyNames) {
+            const callers = Object.entries(scripts)
+                .filter(([name, command]) => name !== legacyName && command.includes(legacyName))
+                .map(([name]) => name);
+            const isPreservedScope = isLegacyCheckScopePreserved(legacyName, scripts);
+            const isObsoleteGeneratedDefault = isUnchangedLegacyCheckDefault(legacyName, scripts) && !isCheckSetupRequired(scripts.check);
+            const files = (_a = externalCallers[legacyName]) !== null && _a !== void 0 ? _a : [];
+            if (callers.length === 0 && files.length === 0 && (isPreservedScope || isObsoleteGeneratedDefault)) {
+                delete scripts[legacyName];
+                for (const prefix of SCRIPT_LIFECYCLE_PREFIXES)
+                    delete scripts[`${prefix}${legacyName}`];
+            }
+            else {
+                migrationInstructions.push(`Kept scripts.${legacyName}${callers.length ? `; referenced by scripts.${callers.join(', scripts.')}` : ''}${files.length ? `; referenced by ${files.join(', ')}` : ''}${!isPreservedScope && !isObsoleteGeneratedDefault
+                ? '; its custom command or npm lifecycle hooks differ from scripts.check'
+                : ''}. Preserve its required validation and pre/post hooks in scripts.check, update those callers to npm run check, then remove scripts.${legacyName} and its unused lifecycle hooks.`);
+            }
+        }
+        for (const [name, command] of Object.entries(scripts)) {
+            if (/\b(?:ptbk|promptbook)\s+coder\s+(?:run|server)\b|\brun-codex-prompts\b/u.test(command) &&
+                /--test(?:-before)?(?:\s|=|$)/u.test(command)) {
+                migrationInstructions.push(`Update scripts.${name}: replace --test with --check and --test-before with --check-before; review its shell expression manually. Existing command was preserved: ${command}`);
+            }
+        }
+        let isCheckConfigured = true;
+        try {
+            assertProjectCheckScriptsAreConfigured(scripts);
+        }
+        catch (error) {
+            if (!(error instanceof CoderCheckSetupError))
+                throw error;
+            isCheckConfigured = false;
+            checkScriptSummary += ` Additional setup required: ${error.message}`;
+        }
+        return {
+            scripts,
+            checkScriptSummary,
+            migrationInstructions,
+            isCheckConfigured,
+        };
+    }
+    /** Determines whether both the legacy command and its implicit npm validation hooks have been preserved. */
+    function isLegacyCheckScopePreserved(name, scripts) {
+        return (scripts[name] === scripts.check &&
+            SCRIPT_LIFECYCLE_PREFIXES.every((prefix) => scripts[`${prefix}${name}`] === scripts[`${prefix}check`]));
+    }
+    /** Recognizes the generated default only when no custom lifecycle hooks extend its validation scope. */
+    function isUnchangedLegacyCheckDefault(name, scripts) {
+        return (scripts[name] === 'npm test' &&
+            SCRIPT_LIFECYCLE_PREFIXES.every((prefix) => scripts[`${prefix}${name}`] === undefined));
+    }
+    /**
+     * Recognizes unchanged generated run scripts, including the previous explicit Developer/context defaults.
+     * Unknown shell expressions and custom harness configuration are preserved for manual migration.
+     */
+    function migrateGeneratedCoderRunScript(command) {
+        const prefix = 'npx ptbk coder run --harness openai-codex --thinking-level max';
+        const defaultArguments = ['', ' --agent agents/developer.book --context AGENTS.md'];
+        const verificationArguments = [
+            ' --test-before yes-and-fix',
+            ...LEGACY_CHECK_SCRIPT_NAMES.map((name) => ` --test "npm run ${name}" --test-before yes-and-fix`),
+            ...LEGACY_CHECK_SCRIPT_NAMES.map((name) => ` --check "npm run ${name}" --check-before yes-and-fix`),
+        ];
+        const isGenerated = defaultArguments.some((defaults) => verificationArguments.some((verification) => command === prefix + defaults + verification));
+        return isGenerated ? getDefaultCoderPackageJsonScripts()['coder:run'] : undefined;
+    }
+    /** Selects safe conventional scripts, avoiding duplicates already reached by another selected aggregate. */
+    function selectValidationScripts(scripts) {
+        if (SCRIPT_LIFECYCLE_PREFIXES.some((prefix) => scripts[`${prefix}check`] !== undefined &&
+            !isUsableValidationScript(`${prefix}check`, scripts, new Set())))
+            return [];
+        const selected = [];
+        for (const group of VALIDATION_SCRIPT_GROUPS) {
+            const name = group.find((candidate) => isUsableValidationScript(candidate, scripts, new Set()));
+            if (name !== undefined)
+                selected.push(name);
+        }
+        if (isUsableValidationScript('test', scripts, new Set()))
+            selected.push('test');
+        else
+            for (const group of TEST_SCRIPT_GROUPS) {
+                const name = group.find((candidate) => isUsableValidationScript(candidate, scripts, new Set()));
+                if (name !== undefined)
+                    selected.push(name);
+            }
+        return selected.filter((name) => !selected.some((other) => other !== name && scriptReaches(other, name, scripts, new Set())));
+    }
+    /** Inspects each body, referenced script, and implicit lifecycle hook before including it in an aggregate. */
+    function isUsableValidationScript(name, scripts, visited) {
+        const command = scripts[name];
+        if (!command ||
+            visited.has(name) ||
+            NON_VALIDATION_SCRIPT_PATTERN.test(name) ||
+            isCheckSetupRequired(command) ||
+            UNSUITABLE_VALIDATION_BODY_PATTERN.test(command))
+            return false;
+        if (command.split('&&').every((part) => /^\s*(?:echo|printf|true|:)(?:\s|$)/iu.test(part)) ||
+            /\bprocess\.exit\(\s*0\s*\)/u.test(command))
+            return false;
+        if (/\b(?:vite|next|astro|webpack-dev-server)\s+(?:dev|start|serve)\b/iu.test(command) ||
+            /(?:^|&&)\s*(?:vite|webpack-dev-server)(?:\s*$|\s+--)/iu.test(command) ||
+            (/\bvitest\b/iu.test(command) && !/\bvitest\s+run\b/iu.test(command)))
+            return false;
+        const nextVisited = new Set([...visited, name]);
+        const references = projectScriptReferences(command);
+        // Ambiguous package-manager flags and cwd switches cannot be composed confidently as root validation.
+        if (/\b(?:npm|pnpm|yarn)\s+(?:--|run(?:-script)?\s+--)/u.test(command) ||
+            (/\b(?:npm|pnpm|yarn)\b/u.test(command) && references.length === 0))
+            return false;
+        if (references.some((reference) => !isUsableValidationScript(reference, scripts, nextVisited)))
+            return false;
+        return SCRIPT_LIFECYCLE_PREFIXES.every((prefix) => {
+            const lifecycleName = `${prefix}${name}`;
+            return scripts[lifecycleName] === undefined || isUsableValidationScript(lifecycleName, scripts, nextVisited);
+        });
+    }
+    /** Checks whether a selected aggregate already reaches another selected script. */
+    function scriptReaches(name, target, scripts, visited) {
+        var _a;
+        if (visited.has(name))
+            return false;
+        const nextVisited = new Set([...visited, name]);
+        const command = (_a = scripts[name]) !== null && _a !== void 0 ? _a : '';
+        if ((target === 'coder:run' && /\b(?:ptbk|promptbook)\s+coder\s+run\b/u.test(command)) ||
+            (target === 'coder:fix' && /\b(?:ptbk|promptbook)\s+coder\s+fix\b/u.test(command)))
+            return true;
+        const references = [
+            ...projectScriptReferences(command),
+            ...SCRIPT_LIFECYCLE_PREFIXES.map((prefix) => `${prefix}${name}`).filter((lifecycleName) => scripts[lifecycleName] !== undefined),
+        ];
+        return references.some((reference) => reference === target || scriptReaches(reference, target, scripts, nextVisited));
+    }
+
+    // cspell:ignore Procfile
+    /** Runtime/dependency/history directories do not contain maintained project callers. */
+    const IGNORED_CALLER_DIRECTORIES = new Set([
+        'node_modules',
+        '.git',
+        '.promptbook',
+        '.next',
+        '.tmp',
+        'dist',
+        'build',
+        'coverage',
+    ]);
+    /** Only Coder's known task-history paths are excluded; the same names elsewhere can hold active callers. */
+    const IGNORED_CALLER_HISTORY_PATHS = new Set(['prompts/done', 'prompts/traces']);
+    /** Source and workflow files whose references must be preserved during npm script migration. */
+    const CALLER_FILE_PATTERN = /\.(?:[cm]?jsx?|tsx?|json|ya?ml|md|sh|bash|ps1|cmd|bat|py|toml|xml|groovy)$/iu;
+    /** Conventional workflow files which have no filename extension. */
+    const CALLER_FILE_NAMES = new Set(['Makefile', 'Dockerfile', 'Jenkinsfile', 'Procfile']);
+    /**
+     * Finds external project callers conservatively; it never rewrites their shell expressions.
+     * @private migration safety check for the Coder initializer
+     */
+    async function findLegacyCoderCheckCallers(projectPath, legacyNames) {
+        const callers = Object.fromEntries(legacyNames.map((name) => [name, []]));
+        if (legacyNames.length === 0)
+            return callers;
+        /** Scans maintained text files without following symlinks or inspecting runtime state. */
+        async function visit(relativeDirectory) {
+            let entries;
+            try {
+                entries = await promises.readdir(path.join(projectPath, relativeDirectory), { withFileTypes: true });
+            }
+            catch (_a) {
+                for (const legacyName of legacyNames)
+                    callers[legacyName].push(`${relativeDirectory} (unreadable directory; review manually)`);
+                return;
+            }
+            for (const entry of entries) {
+                const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+                if (entry.isSymbolicLink()) {
+                    if (!IGNORED_CALLER_DIRECTORIES.has(entry.name)) {
+                        for (const legacyName of legacyNames)
+                            callers[legacyName].push(`${relativePath} (symbolic link; review manually)`);
+                    }
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    if (!IGNORED_CALLER_DIRECTORIES.has(entry.name) && !IGNORED_CALLER_HISTORY_PATHS.has(relativePath))
+                        await visit(relativePath);
+                }
+                else if (entry.isFile() && (CALLER_FILE_PATTERN.test(entry.name) || CALLER_FILE_NAMES.has(entry.name))) {
+                    try {
+                        let content = await promises.readFile(path.join(projectPath, relativePath), 'utf-8');
+                        if (relativePath === 'package.json') {
+                            // Script callers are already handled by the merge. Other project-owned metadata may also
+                            // reference a script, so it must be included when deciding whether removal is safe.
+                            const packageMetadata = JSON.parse(content);
+                            delete packageMetadata.scripts;
+                            content = JSON.stringify(packageMetadata);
+                        }
+                        for (const legacyName of legacyNames) {
+                            if (content.includes(legacyName))
+                                callers[legacyName].push(relativePath === 'package.json' ? 'package.json (outside scripts)' : relativePath);
+                        }
+                    }
+                    catch (_b) {
+                        // An unreadable file cannot prove that deletion is safe. Keep the entry and explain why.
+                        for (const legacyName of legacyNames)
+                            callers[legacyName].push(`${relativePath} (unreadable; review manually)`);
+                    }
+                }
+            }
+        }
+        await visit('');
+        return callers;
+    }
+
     /**
      * Relative path to `package.json` in the initialized project.
      */
@@ -46897,17 +47472,30 @@
     /**
      * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
      *
-     * Scripts which the project already defines are kept as they are, only missing ones are added.
+     * Project definitions are preserved; missing scripts and narrowly recognized generated migrations are applied.
      *
      * @private function of `initializeCoderProjectConfiguration`
      */
     async function ensureCoderPackageJsonFile(projectPath) {
-        return mergeStringRecordJsonFile({
+        let preparation;
+        const mergedFile = await mergeStringRecordJsonFile({
             projectPath,
             relativeFilePath: PACKAGE_JSON_FILE_PATH,
             fieldPath: 'scripts',
             nextEntries: getDefaultCoderPackageJsonScripts(),
+            transformExistingEntries: async (entries) => {
+                const legacyNames = Object.keys(entries).filter((name) => name === 'test-for-ptbk-coder' || name === 'check-for-ptbk-coder');
+                const externalCallers = await findLegacyCoderCheckCallers(projectPath, legacyNames);
+                preparation = prepareCoderPackageJsonScripts(entries, externalCallers);
+                return preparation.scripts;
+            },
         });
+        return {
+            ...mergedFile,
+            checkScriptSummary: preparation.checkScriptSummary,
+            migrationInstructions: preparation.migrationInstructions,
+            isCheckConfigured: preparation.isCheckConfigured,
+        };
     }
     // Note: [🟡] Code for coder init package.json bootstrapping [ensureCoderPackageJsonFile](src/cli/cli-commands/coder/ensureCoderPackageJsonFile.ts) should never be published outside of `@promptbook/cli`
 
@@ -47201,9 +47789,9 @@
 
     Runner-written completion lines may attribute implementation to a harness and model, include
     reasoning/authentication labels, attempts or interrupted/continued history, and report implementation,
-    testing, fixing, or total cost/time information. Those are observed run metadata, not instructions, budgets,
-    or a frozen list of supported models. A completed status alone does not prove tests ran: direct runs only
-    execute an automated verification command when configured. Preserve actual measurements and record unknown
+    checking, fixing, or total cost/time information. Those are observed run metadata, not instructions, budgets,
+    or a frozen list of supported models. A completed status alone does not prove checks ran: direct runs only
+    execute the project check command when configured. Preserve actual measurements and record unknown
     results or checks that were not run honestly. Manual users must not invent cost/time figures, copy another
     run's attribution, or mark unverified work as verified. The textual metadata rows above demonstrate syntax
     only; use them only when the described events actually happened.
@@ -47254,9 +47842,9 @@
     | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | \`ptbk init\` / \`ptbk coder init\`                                                                         | Initializes missing Git, then creates missing configuration, local Books, this guide, and fresh-directory boilerplates; preserves project-owned content. \`--no-questions\` skips installation questions/checks.                                                                                                                                                                |
     | \`ptbk coder add "Describe the reviewed change"\`                                           | Creates one numbered, tagged pending PRD. Accepts a description argument, stdin, or interactive input; \`--priority\` and \`--template\` are available. It does not discuss or implement the task. Review the generated requirements before running.                                                                                                |
-    | \`ptbk coder plan --harness openai-codex\`                                                  | Interactive planning with the local Planner. Review proposals; \`/save\` writes pending PRDs, \`/draft\` writes not-ready drafts, \`/discard\` drops proposals, \`/exit\` ends. It changes PRD Markdown only and never implements or starts the queue. Currently this planning command supports the Codex harness in a compatible interactive terminal. |
+    | \`ptbk coder plan --harness openai-codex\`                                                  | Interactive planning with the local Developer. Review proposals; \`/save\` writes pending PRDs, \`/draft\` writes not-ready drafts, \`/discard\` drops proposals, \`/exit\` ends. It changes PRD Markdown only and never implements or starts the queue. Currently this planning command supports the Codex harness in a compatible interactive terminal. |
     | \`ptbk coder list\`                                                                         | Displays fully authored pending tasks grouped by descending priority without execution or file changes. Optional harness/model/agent and priority filters narrow the list.                                                                                                                                                                      |
-    | \`ptbk coder run --harness openai-codex --limit 1 --no-commit --no-auto --test "npm test"\` | Confirms and implements one selected task, then runs the specified project check. Replace the test command as needed. Without \`--limit\`, execution proceeds through the eligible queue; without \`--no-commit\`, run stages and commits its changes.                                                                                              |
+    | \`ptbk coder run --harness openai-codex --limit 1 --no-commit --no-auto --check "npm run check"\` | Confirms and implements one selected task, then runs the specified project check. Replace the check command as needed. Without \`--limit\`, execution proceeds through the eligible queue; without \`--no-commit\`, run stages and commits its changes.                                                                                              |
     | \`ptbk coder verify\`                                                                       | Human review helper: shows completion claims, offers archival or a repair section, and can also ask about pending tasks. It does not run acceptance tests itself. Archival moves the whole file to \`done/\`, so inspect every section before agreeing. There is no separate archive command.                                                     |
     | \`ptbk coder find-unwritten\`                                                               | Lists pending sections still containing authoring placeholders; not-ready drafts are not included.                                                                                                                                                                                                                                              |
     | \`ptbk coder generate-boilerplates\`                                                        | Adds not-ready starter sections using reusable templates; author and review them before making them pending.                                                                                                                                                                                                                                    |
@@ -47268,11 +47856,18 @@
     pulling require the corresponding explicit options. Consult \`ptbk coder --help\` and the relevant subcommand's
     \`--help\` for the installed version's full options.
 
-    The initialized \`npm run coder:run\` script supplies \`AGENTS.md\` as context, selects the Codex harness, and
-    uses \`npm run test-for-ptbk-coder\` for checks (including pre-run repair mode). The new check script delegates
-    to \`npm test\`; configure real tests for your project before running it. Existing npm scripts are preserved, so
-    read your \`package.json\` to see your actual commands. Direct \`ptbk coder run\` does not inherit npm-script
-    flags.
+    The initialized \`npm run coder:run\` script selects the Codex harness and uses
+    \`--check "npm run check" --check-before yes-and-fix\`. Developer, the current project directory, and its
+    \`AGENTS.md\` are shared CLI defaults. A **check** covers the project's chosen tests, linting, typechecking,
+    builds, generated-code consistency, and other validation. Tests remain one kind of check.
+    Init preserves an existing \`scripts.check\` exactly, or composes applicable existing validation scripts and
+    reports the selected scope. If none are usable, it creates a failing setup placeholder: configure real
+    validation before running Coder. Missing checks or setup placeholders stop with setup guidance, without model repairs.
+    Direct \`ptbk coder run\` defaults to \`--check-before no\`; checks after prompts remain opt-in. Enabled
+    preflight without an explicit command uses \`npm run check\`, including during repair verification.
+    Replace retired \`--test\` / \`--test-before\` with \`--check\` / \`--check-before\`. Init migrates recognized
+    generated scripts and preserves custom legacy validation in \`check\`. Conflicting definitions or custom callers
+    are preserved with manual migration instructions; review them before removing a legacy script.
 
     ### Book agent, harness, and model
 
@@ -47284,9 +47879,20 @@
     Init creates local Developer and Planner Books in \`agents/developer.book\` and \`agents/planner.book\`, their
     Lawyer and Copywriter TEAM advisers, and shared \`agents/.core/adam.book\` instructions. Books can
     inherit/import instructions; TEAM entries expose advisers for relevant consultations, not an obligation to
-    invoke everyone. \`run\` and \`server\` default to Developer; \`plan\` defaults to Planner.
-    \`--agent agents/my-developer.book\` overrides the Book only. \`list\` has no default Book filter. Selecting
-    Developer for \`plan\` still permits planning only.
+    invoke everyone. \`run\`, \`server\` and \`plan\` default to Developer.
+    \`--agent ./agents/planner.book\` selects Planner explicitly; another Book path also works. \`list\` has no
+    default Book filter. Every Book used in \`plan\`, including Developer, still permits planning only.
+
+    Project commands default to the current directory captured when invoked. \`--path\` selects another existing
+    directory, relative to that invocation or absolute; an enclosing Git repository never relocates the project's
+    Books, PRDs or context. Additional context defaults to the actual UTF-8 contents of that project's \`AGENTS.md\`.
+    A missing implicit file warns and continues; an unreadable file fails. \`--context\` replaces the default with
+    inline instructions or a file resolved relative to the selected project; \`--context ""\` disables it.
+    Invalid explicit Books and missing/unreadable explicit context files fail without falling back.
+    Thus \`ptbk coder run --harness openai-codex\` and
+    \`ptbk coder run --harness openai-codex --agent ./agents/developer.book --path . --context ./AGENTS.md\` select
+    the same inputs. New npm scripts rely on these defaults; init still creates missing Books and AGENTS.md even
+    when every script already exists, preserving existing custom scripts, settings and context.
 
     Edit local Books to reflect this project's rules; repeat init preserves customizations and adds missing
     defaults/helper references. An invalid explicit Book selection fails rather than silently changing roles.
@@ -47357,7 +47963,7 @@
         const adamArtifact = defaultAgentArtifacts.find(({ relativeFilePath }) => relativeFilePath === adamRelativeFilePath);
         const { envFileStatus, initializedEnvVariableNames } = await completeStep('.env', ensureCoderEnvFile(projectPath));
         const gitignoreFileStatus = await completeStep('.gitignore', ensureCoderGitignoreFile(projectPath));
-        const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } = await completeStep('package.json', ensureCoderPackageJsonFile(projectPath));
+        const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames, checkScriptSummary, migrationInstructions, isCheckConfigured, } = await completeStep('package.json', ensureCoderPackageJsonFile(projectPath));
         const vscodeSettingsFileStatus = await completeStep('.vscode/settings.json', ensureCoderVscodeSettingsFile(projectPath));
         const referencedArtifactStatuses = [
             ...defaultAgentArtifacts.filter(({ relativeFilePath }) => relativeFilePath !== adamRelativeFilePath),
@@ -47378,6 +47984,9 @@
             addedPackageJsonScriptNames,
             referencedArtifactStatuses,
             initializedEnvVariableNames,
+            checkScriptSummary,
+            migrationInstructions,
+            isCheckConfigured,
         };
     }
     // Note: [🟡] Code for coder init project bootstrapping [initializeCoderProjectConfiguration](src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts) should never be published outside of `@promptbook/cli`
@@ -47389,9 +47998,11 @@
      */
     function printInitializationSummary(summary, workspace) {
         const isUnresolved = summary.adamAgentFileStatus === 'unresolved' ||
+            !summary.isCheckConfigured ||
+            summary.migrationInstructions.length > 0 ||
             summary.referencedArtifactStatuses.some(({ status }) => status === 'unresolved');
         console.info(isUnresolved
-            ? colors__default["default"].yellow('Promptbook coder initialization has unresolved artifacts.')
+            ? colors__default["default"].yellow('Promptbook coder configuration setup: additional setup is required.')
             : colors__default["default"].green('Promptbook coder configuration setup:'));
         if (workspace)
             console.info(colors__default["default"].gray(`✔ Git repository: ${workspace.repositoryStatus} (${workspace.repositoryRoot})`));
@@ -47420,6 +48031,9 @@
         else {
             printInitializationNote('Required coder env variables are already present.', colors__default["default"].gray);
         }
+        console.info((summary.isCheckConfigured ? colors__default["default"].cyan : colors__default["default"].yellow)(summary.checkScriptSummary));
+        for (const instruction of summary.migrationInstructions)
+            console.info(colors__default["default"].yellow(`! ${instruction}`));
     }
     /**
      * Formats one initialization status into a human-readable label.
@@ -47501,7 +48115,7 @@
                 - Adds missing local Lawyer and Copywriter TEAM references to Developer and Planner, preserving existing content
                 - Helpers advise on relevant tasks; declaring TEAM does not run them for every task
                 - Reports created, augmented, unchanged and unresolved Books; invalid or conflicting files are left untouched
-                - Other referenced files, like coder:run context, are created with their newly added scripts
+                - Missing AGENTS.md is initialized independently of scripts; existing content is preserved
 
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
@@ -47519,9 +48133,14 @@
         addQuestionsOption(command);
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
-            const workspace = await $preflightWorkspaceRepository({ policy: 'initialize', ...questionsOptions });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'initialize',
+                ...questionsOptions,
+            });
             const { projectPath } = workspace;
             const completedSteps = [`Git repository ${workspace.repositoryStatus}: ${workspace.repositoryRoot}`];
             try {
@@ -47635,6 +48254,11 @@
         developer: CODER_DEVELOPER_AGENT_FILE_PATH,
         planner: CODER_PLANNER_AGENT_FILE_PATH,
     };
+    /**
+     * Shared persona for optional single-agent execution and authoring; capabilities belong to the command.
+     * @private internal constant of project CLI commands
+     */
+    const DEFAULT_CODER_AGENT_ROLE = 'developer';
     // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
     /**
@@ -47654,6 +48278,14 @@
             : 'No default Book filter; omitting --agent includes tasks for all agents';
         command.option('--agent <agent-book-path>', `${CODER_AGENT_OPTION_DESCRIPTION}. ${defaultDescription}`);
     }
+    /**
+     * Registers the shared optional persona and context for single-agent execution or authoring.
+     * @private internal CLI registration helper
+     */
+    function addCoderExecutionOptions(command) {
+        addCoderAgentOption(command, DEFAULT_CODER_AGENT_ROLE);
+        addProjectContextOption(command);
+    }
     // Note: [🟡] Code for CLI coder agent options should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
@@ -47682,9 +48314,13 @@
         addPromptPriorityOptions(command);
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { agent, priority, minPriority: minimumPriority, maxPriority: maximumPriority, } = cliOptions;
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: false });
-            const workspace = await $preflightWorkspaceRepository({ policy: 'read-only' });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'read-only',
+            });
             const resolvedCoderAgentBook = agent === undefined
                 ? undefined
                 : await (await Promise.resolve().then(function () { return resolveCoderAgent$1; })).resolveCoderAgentBook(agent, workspace.projectPath);
@@ -47825,12 +48461,17 @@
         `));
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { period: periodValue } = cliOptions;
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
             // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
             const periodMs = parseOptionalPeriodDuration('--period', periodValue);
-            const workspace = await $preflightWorkspaceRepository({ policy: 'mutate', ...questionsOptions });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                ...questionsOptions,
+            });
             await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
             await $ensureCoderHarnessGitignoreRules(workspace.projectPath, runnerOptions.agentName, questionsOptions);
             const pingOptions = {
@@ -47862,10 +48503,10 @@
      */
     function $initializeCoderPlanCommand(program) {
         const command = program.command('plan').description(spaceTrim(`
-        Discuss features with the project's Planner and review PRDs before saving them.
+        Discuss features with the project's Developer Book and review PRDs before saving them.
 
-        Run ptbk coder init first. Default Book: agents/planner.book; --agent overrides the Book,
-        independently of --harness and --model. Currently supports openai-codex with restricted tools.
+        Run ptbk coder init first. Default Book: agents/developer.book; --agent overrides the Book,
+        independently of --harness and --model. Use --agent ./agents/planner.book for Planner. Currently supports openai-codex with restricted tools.
         Requires an interactive terminal and a Codex version supporting --ignore-user-config and --ignore-rules.
         Codex configuration, plugins, hooks and native tools are isolated; --model default uses Codex's built-in default.
         /save applies reviewed proposals, /draft saves [-] drafts, /discard drops proposals, /exit ends.
@@ -47874,11 +48515,12 @@
     `));
         addPromptRunnerSelectionOptions(command);
         addPromptRunnerRuntimeOptions(command);
-        addCoderAgentOption(command, 'planner');
+        addCoderExecutionOptions(command);
         addCoderGitSyncOptions(command);
         command.option('--template <path>', 'PRD template (defaults to the project-owned prompts/templates/common.md when present)');
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { createPlanningTerminal } = await Promise.resolve().then(function () { return createPlanningTerminal$1; });
             const { runPlanningSession } = await Promise.resolve().then(function () { return runPlanningSession$1; });
             const { resolvePlanningPath } = await Promise.resolve().then(function () { return resolvePlanningPath$1; });
@@ -47889,12 +48531,18 @@
             assertPlanningHarnessSupported(options.agentName);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
             if (cliOptions.questions === false) {
                 throw new NotAllowed(spaceTrim('`ptbk coder plan` requires an interactive conversation and review. Run it without `--no-questions` in a terminal.'));
             }
+            const { resolveCoderProjectContext } = await Promise.resolve().then(function () { return resolveCoderProjectContext$1; });
+            const projectContext = await resolveCoderProjectContext({
+                ...cliOptions,
+                projectPath: workspace.projectPath,
+            });
             const terminal = createPlanningTerminal();
             try {
                 const { projectPath } = workspace;
@@ -47907,6 +48555,8 @@
                     ...options,
                     projectPath,
                     agent: cliOptions.agent,
+                    context: cliOptions.context,
+                    projectContext,
                     template: cliOptions.template,
                     preexistingChangedPaths: gitSync.isCommitEnabled
                         ? new Set(Array.from(commitScope.snapshotBeforeOperation.changedFileHashes.keys(), (path$1) => path.relative(projectPath, path.join(workspace.repositoryRoot, path$1)).replace(/\\/gu, '/')))
@@ -48096,30 +48746,20 @@
     }
     // Note: [🟡] Code for CLI free disk space handling [$assertSufficientFreeDiskSpace](src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts) should never be published outside of `@promptbook/cli`
 
-    /**
-     * Modes supported by `ptbk coder run --test-before`.
-     */
-    const TEST_BEFORE_MODE_VALUES = ['no', 'yes-and-fail', 'yes-and-fix'];
-    /**
-     * Default verification command used when a pre-coding mode is enabled without an explicit `--test` command.
-     */
-    const DEFAULT_CODER_TEST_COMMAND = 'npm test';
-    /**
-     * Checks whether a value is a supported `--test-before` mode.
-     */
-    function isTestBeforeMode(value) {
-        return TEST_BEFORE_MODE_VALUES.includes(value);
-    }
-
     /**
      * Validates cross-flag constraints before workspace setup or the run starts.
      * @private shared validation for Coder execution commands
      */
     function validateCoderRunOptions(options) {
         var _a;
-        if (!isTestBeforeMode((_a = options.testBefore) !== null && _a !== void 0 ? _a : 'no')) {
+        if (options.checkCommand !== undefined && !options.checkCommand.trim()) {
             throw new NotAllowed(_spaceTrim.spaceTrim(`
-                Invalid ${'`--test-before`'} mode: \`${String(options.testBefore)}\`.
+            Option \`--check\` requires a non-empty shell command, for example \`npm run check\`.
+        `));
+        }
+        if (!isCheckBeforeMode((_a = options.checkBefore) !== null && _a !== void 0 ? _a : 'no')) {
+            throw new NotAllowed(_spaceTrim.spaceTrim(`
+                Invalid ${'`--check-before`'} mode: \`${String(options.checkBefore)}\`.
 
                 Use one of: \`no\`, \`yes-and-fail\`, \`yes-and-fix\`.
             `));
@@ -48157,9 +48797,9 @@
                 An isolated task is implemented in a fresh temporary worktree checked out from the last commit, so the uncommitted changes of the interrupted prompt would be left behind instead of being continued.
             `));
         }
-        if (options.gitChanges === 'continue' && options.testBefore === 'yes-and-fix') {
+        if (options.gitChanges === 'continue' && options.checkBefore === 'yes-and-fix') {
             throw new NotAllowed(_spaceTrim.spaceTrim(`
-                Flag \`--git-changes continue\` cannot be combined with \`--test-before yes-and-fix\`.
+                Flag \`--git-changes continue\` cannot be combined with \`--check-before yes-and-fix\`.
 
                 An interrupted prompt already has changes in progress, so there is no unmodified project state for pre-coding verification to repair.
             `));
@@ -48206,9 +48846,9 @@
      *
      * @private internal utility of `promptbookCli`
      */
-    async function $resolvePromptbookCliInstallations() {
+    async function $resolvePromptbookCliInstallations(projectPath = process.cwd()) {
         const [localInstallations, globalInstallations] = await Promise.all([
-            $resolveLocalPromptbookCliInstallations(),
+            $resolveLocalPromptbookCliInstallations(projectPath),
             $resolveGlobalPromptbookCliInstallations(),
         ]);
         return [...localInstallations, ...globalInstallations];
@@ -48216,8 +48856,8 @@
     /**
      * Finds the closest ancestor `package.json` which directly declares a Promptbook CLI package.
      */
-    async function $resolveLocalPromptbookCliInstallations() {
-        let candidateProjectPath = path.resolve(process.cwd());
+    async function $resolveLocalPromptbookCliInstallations(projectPath) {
+        let candidateProjectPath = path.resolve(projectPath);
         let isFileSystemRootReached = false;
         while (!isFileSystemRootReached) {
             const projectPackageJson = await $readJsonObject(path.join(candidateProjectPath, PACKAGE_JSON_FILENAME));
@@ -48373,8 +49013,8 @@
      *
      * @private internal utility of `promptbookCli`
      */
-    async function $checkPromptbookCliInstallations() {
-        const installations = await $resolvePromptbookCliInstallations();
+    async function $checkPromptbookCliInstallations(projectPath = process.cwd()) {
+        const installations = await $resolvePromptbookCliInstallations(projectPath);
         if (installations.length === 0) {
             return [];
         }
@@ -48429,10 +49069,10 @@
      * @returns `true` when the package update succeeds, `false` when it fails
      * @private internal utility of `promptbookCli`
      */
-    async function $updatePromptbookCliInstallation(status) {
+    async function $updatePromptbookCliInstallation(status, projectPath = process.cwd()) {
         const { npmPackageName, installationLocation } = status.installation;
         const installCommand = buildPromptbookCliInstallCommand(status.installation);
-        const updateWorkingDirectory = installationLocation === 'global' ? process.cwd() : status.installation.projectPath;
+        const updateWorkingDirectory = installationLocation === 'global' ? projectPath : status.installation.projectPath;
         console.info(colors__default["default"].cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));
         try {
             await $execCommand({
@@ -48502,7 +49142,7 @@
      * @returns `true` when at least one installation was updated and the current coder run should stop
      * @private internal utility of `promptbookCli`
      */
-    async function $ensurePromptbookCliInstallations(questionsOptions) {
+    async function $ensurePromptbookCliInstallations(questionsOptions, projectPath = process.cwd()) {
         if (!questionsOptions.isAskingQuestionsEnabled) {
             // Note: `--no-questions` forbids asking for the approval, so the registry checks would be useless
             return false;
@@ -48511,7 +49151,7 @@
             // Note: Non-interactive runs cannot approve an update and should not wait for registry checks
             return false;
         }
-        const statuses = await $checkPromptbookCliInstallations();
+        const statuses = await $checkPromptbookCliInstallations(projectPath);
         const outdatedStatuses = statuses.filter(({ installationState }) => installationState === 'outdated');
         if (outdatedStatuses.length === 0) {
             reportPromptbookCliInstallationStatuses(statuses);
@@ -48525,7 +49165,7 @@
         }
         const updateResults = [];
         for (const status of outdatedStatuses) {
-            updateResults.push(await $updatePromptbookCliInstallation(status));
+            updateResults.push(await $updatePromptbookCliInstallation(status, projectPath));
         }
         const isAnyInstallationUpdated = updateResults.some(Boolean);
         const isEveryInstallationUpdated = updateResults.every(Boolean);
@@ -48570,6 +49210,89 @@
     }
     // Note: [🟡] Code for Promptbook CLI installation orchestration [$ensurePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`
 
+    /** Standalone shell composition tokens remain operators when a command is supplied as several arguments. */
+    const SHELL_COMPOSITION_TOKENS = new Set([
+        '&&',
+        '||',
+        '|',
+        '|&',
+        '&',
+        ';',
+        '(',
+        ')',
+        '>',
+        '>>',
+        '<',
+        '2>',
+        '2>>',
+        '2>&1',
+    ]);
+    /**
+     * Retired aggregate option spellings and their canonical replacements, used only for migration diagnostics.
+     * @private shared CLI migration definitions for Coder execution
+     */
+    const LEGACY_CODER_CHECK_OPTIONS = [
+        ['--test', '--check'],
+        ['--test-before', '--check-before'],
+    ];
+    /**
+     * Registers the shared project check command and rejects retired aggregate-test spellings.
+     * @private shared CLI registration for Coder execution
+     */
+    function addCoderCheckOptions(command, isCheckBeforeSupported) {
+        command.option('--check <check-command...>', 'Run project checks after each prompt; quote the full command when it contains flags or shell composition');
+        if (isCheckBeforeSupported) {
+            command.addOption(new commander.Option('--check-before <mode>', `Check before coding: ${CHECK_BEFORE_MODE_VALUES.join(', ')} (defaults to no; uses npm run check when --check is omitted)`)
+                .choices([...CHECK_BEFORE_MODE_VALUES])
+                .default('no'));
+        }
+        // These diagnostic-only options never forward a value or start execution.
+        for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+            command.addOption(new commander.Option(`${legacyFlag} [value...]`).hideHelp());
+            command.on(`option:${legacyFlag.slice(2)}`, () => {
+                command.error(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+            });
+        }
+    }
+    /**
+     * Builds the same actionable migration diagnostic for registered and direct-script entrypoints.
+     * @private shared CLI diagnostic for Coder execution
+     */
+    function formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag) {
+        return `Aggregate verification option \`${legacyFlag}\` was renamed to \`${replacementFlag}\`. Update your command and package.json scripts.`;
+    }
+    /**
+     * Normalizes shell command tokens without parsing a quoted command again or losing spaced argument boundaries.
+     * @private shared command normalization for Coder execution
+     */
+    function normalizeCheckCommandOption(value) {
+        var _a, _b;
+        if (value === undefined)
+            return undefined;
+        const parts = typeof value === 'string' ? [value] : value;
+        const firstPart = (_b = (_a = parts[0]) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+        for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+            if (firstPart === legacyFlag || firstPart.startsWith(`${legacyFlag}=`)) {
+                throw new NotAllowed(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+            }
+        }
+        const command = parts.length === 1
+            ? parts[0].trim()
+            : parts
+                .map((part) => !SHELL_COMPOSITION_TOKENS.has(part) && (!part || /[\s'"\\$`;&|<>()*?]/u.test(part))
+                ? quoteBashArgument(part)
+                : part)
+                .join(' ')
+                .trim();
+        if (!command || !firstPart || firstPart.startsWith('-')) {
+            throw new NotAllowed(_spaceTrim.spaceTrim(`
+            Option \`--check\` requires a non-empty shell command, for example \`--check "npm run check"\`.
+        `));
+        }
+        return command;
+    }
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
+
     /**
      * Prints why a coder run has ended to the terminal.
      *
@@ -48616,20 +49339,16 @@
             - Offers to add missing project-local ignore rules for the selected harness
             - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
-            - Optional pre-coding test run that can stop or repair pre-existing failures
-            - Optional post-prompt verification with test-feedback retries
+            - Optional pre-coding check run that can stop or repair pre-existing failures
+            - Optional post-prompt checks with check-feedback retries
             - Progress tracking and interactive P/S/X terminal controls; O changes only the dashboard output view
             - Dry-run mode to preview prompts
         `));
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(command);
         addQuestionsOption(command);
-        addCoderAgentOption(command, 'developer');
-        command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
-        command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
-        command.addOption(new commander.Option('--test-before <mode>', `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(', ')} (defaults to no; uses npm test when --test is omitted)`)
-            .choices([...TEST_BEFORE_MODE_VALUES])
-            .default('no'));
+        addCoderExecutionOptions(command);
+        addCoderCheckOptions(command, true);
         command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
         addPromptRunnerExecutionOptions(command);
         command.option('--isolate', _spaceTrim.spaceTrim(`
@@ -48658,9 +49377,9 @@
         command.option('--allow-destructive-auto-migrate', 'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations');
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
-            const { dryRun, agent, context, test, testBefore, preserveLogs, isolate: isIsolated, priority, minPriority: minimumPriority, maxPriority: maximumPriority, limit, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
-            const configuredTestCommand = normalizeCommandOptionValue$1(test);
-            const testCommand = configuredTestCommand !== null && configuredTestCommand !== void 0 ? configuredTestCommand : (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const { dryRun, agent, context, check, checkBefore, preserveLogs, isolate: isIsolated, priority, minPriority: minimumPriority, maxPriority: maximumPriority, limit, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+            const checkCommand = resolveCoderCheckCommand(normalizeCheckCommandOption(check), checkBefore);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
@@ -48689,8 +49408,8 @@
                 model: runnerOptions.model,
                 agent,
                 context,
-                testCommand,
-                testBefore,
+                checkCommand,
+                checkBefore,
                 preserveLogs,
                 isIsolated,
                 noUi: runnerOptions.noUi,
@@ -48709,16 +49428,20 @@
             };
             validateCoderRunOptions(runOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: dryRun ? 'read-only' : 'mutate',
                 ...questionsOptions,
             });
+            const { resolveCoderProjectContext } = await Promise.resolve().then(function () { return resolveCoderProjectContext$1; });
+            const projectContext = await resolveCoderProjectContext({
+                projectPath: workspace.projectPath,
+                agent,
+                context,
+            });
             if (!dryRun) {
-                // Reject missing or unreadable Books before offering installations or project configuration writes.
-                const { resolveCoderAgentBook } = await Promise.resolve().then(function () { return resolveCoderAgent$1; });
-                await resolveCoderAgentBook(agent, workspace.projectPath, { defaultRole: 'developer' });
                 // Check disk space before installations and repository writes; previews require no setup.
                 await $assertSufficientFreeDiskSpace(workspace.projectPath);
-                if (await $ensurePromptbookCliInstallations(questionsOptions)) {
+                if (await $ensurePromptbookCliInstallations(questionsOptions, workspace.projectPath)) {
                     return process.exit(0);
                 }
                 await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
@@ -48727,8 +49450,7 @@
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
             const { runCodexPrompts } = await Promise.resolve().then(function () { return runCodexPrompts$1; });
             try {
-                // Override process.argv to pass options to the legacy parseRunOptions if needed
-                await runCodexPrompts({ ...runOptions, workspace });
+                await runCodexPrompts({ ...runOptions, workspace, projectContext });
             }
             catch (error) {
                 assertsError(error);
@@ -48738,23 +49460,6 @@
             return process.exit(0);
         }));
     }
-    /**
-     * Joins one Commander option that may be parsed either as a single string or a variadic token array.
-     *
-     * @private internal utility of `coder run` command
-     */
-    function normalizeCommandOptionValue$1(value) {
-        if (value === undefined) {
-            return undefined;
-        }
-        const parts = Array.isArray(value) ? value : [value];
-        const normalizedValue = parts
-            .map((part) => part.trim())
-            .filter(Boolean)
-            .join(' ')
-            .trim();
-        return normalizedValue === '' ? undefined : normalizedValue;
-    }
     // Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
@@ -48800,9 +49505,8 @@
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(command);
         addQuestionsOption(command);
-        addCoderAgentOption(command, 'developer');
-        command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
-        command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
+        addCoderExecutionOptions(command);
+        addCoderCheckOptions(command, false);
         command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
         addPromptRunnerExecutionOptions(command);
         addPromptPriorityOptions(command);
@@ -48824,9 +49528,10 @@
         command.option('--allow-destructive-auto-migrate', 'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations');
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
-            const { port: rawPort, dryRun, agent, context, test, preserveLogs, priority, minPriority: minimumPriority, maxPriority: maximumPriority, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const { port: rawPort, dryRun, agent, context, check, preserveLogs, priority, minPriority: minimumPriority, maxPriority: maximumPriority, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
             const port = parseCoderServerPort(rawPort);
-            const testCommand = normalizeCommandOptionValue(test);
+            const checkCommand = normalizeCheckCommandOption(check);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
@@ -48850,7 +49555,7 @@
                 model: runnerOptions.model,
                 agent,
                 context,
-                testCommand,
+                checkCommand,
                 preserveLogs,
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
@@ -48867,13 +49572,17 @@
             };
             validateCoderRunOptions(runOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: dryRun ? 'read-only' : 'mutate',
                 ...questionsOptions,
             });
+            const { resolveCoderProjectContext } = await Promise.resolve().then(function () { return resolveCoderProjectContext$1; });
+            const projectContext = await resolveCoderProjectContext({
+                projectPath: workspace.projectPath,
+                agent,
+                context,
+            });
             if (!dryRun) {
-                // Reject missing or unreadable Books before offering installations or project configuration writes.
-                const { resolveCoderAgentBook } = await Promise.resolve().then(function () { return resolveCoderAgent$1; });
-                await resolveCoderAgentBook(agent, workspace.projectPath, { defaultRole: 'developer' });
                 // Check disk space before installations and repository writes; previews require no setup.
                 await $assertSufficientFreeDiskSpace(workspace.projectPath);
                 await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
@@ -48882,7 +49591,7 @@
             // Note: Import dynamically to avoid loading heavy dependencies until needed
             const { runCodexPromptsServer } = await Promise.resolve().then(function () { return runCodexPromptsServer$1; });
             try {
-                await runCodexPromptsServer({ ...runOptions, workspace });
+                await runCodexPromptsServer({ ...runOptions, workspace, projectContext });
             }
             catch (error) {
                 assertsError(error);
@@ -48908,23 +49617,6 @@
         }
         return port;
     }
-    /**
-     * Joins one Commander option that may be parsed either as a single string or a variadic token array.
-     *
-     * @private internal utility of `coder server` command
-     */
-    function normalizeCommandOptionValue(value) {
-        if (value === undefined) {
-            return undefined;
-        }
-        const parts = Array.isArray(value) ? value : [value];
-        const normalizedValue = parts
-            .map((part) => part.trim())
-            .filter(Boolean)
-            .join(' ')
-            .trim();
-        return normalizedValue === '' ? undefined : normalizedValue;
-    }
     // Note: [🟡] Code for CLI command [server](src/cli/cli-commands/coder/server.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
@@ -49002,9 +49694,11 @@
         addCoderGitSyncOptions(command);
         addWorkspaceRepositoryOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { order, ignore } = cliOptions;
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
@@ -49040,7 +49734,7 @@
      * The coder command provides utilities for automated coding:
      * - init: Initialize coder configuration in current project
      * - add: Add one ready-to-run prompt file to the queue
-     * - plan: Discuss features with Planner and author reviewed PRDs
+     * - plan: Discuss features with Developer and author reviewed PRDs
      * - generate-boilerplates: Generate prompt boilerplate files
      * - find-refactor-candidates: Find files that need refactoring
      * - list: List ready prompts in priority order without running them
@@ -49061,7 +49755,7 @@
             Subcommands:
             - init: Initialize coder configuration in current project
             - add: Add one ready-to-run prompt file to the queue
-            - plan: Discuss features with Planner and author reviewed PRDs
+            - plan: Discuss features with Developer and author reviewed PRDs
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
@@ -72182,12 +72876,21 @@
         }
         const textPath = path.resolve(options.currentWorkingDirectory, normalizedTextReference);
         const textPathStats = await promises.stat(textPath).catch((error) => {
-            if (error.code === 'ENOENT') {
+            if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
                 return undefined;
             }
-            throw error;
+            if (['ENAMETOOLONG', 'EINVAL', 'ERR_INVALID_ARG_VALUE'].includes(error.code || '') && !isContextFileReference(normalizedTextReference)) {
+                return undefined;
+            }
+            throw contextReadError(options, textPath, error);
         });
         if (!textPathStats) {
+            if (options.isMissingFileAnError && isContextFileReference(normalizedTextReference)) {
+                throw new NotFoundError(spaceTrim(`
+                ${options.contextLabel} file \`${textPath}\` does not exist.
+                Correct the file path in \`${options.optionName}\` or pass inline instructions.
+            `));
+            }
             return normalizedTextReference;
         }
         if (!textPathStats.isFile()) {
@@ -72197,7 +72900,55 @@
                 Pass a file path or inline text in \`${options.optionName}\`.
             `));
         }
-        return promises.readFile(textPath, 'utf-8');
+        return promises.readFile(textPath, 'utf-8').catch((error) => {
+            throw contextReadError(options, textPath, error);
+        });
+    }
+    /** Distinguishes explicit file spellings from ordinary inline instructions, including native Windows paths. */
+    function isContextFileReference(reference) {
+        return path.isAbsolute(reference) || /^(?:\.{1,2}[/\\]|[a-z]:[/\\]|\\\\)/iu.test(reference) ||
+            (!/[\r\n]/u.test(reference) && /\.(?:md|markdown|txt|book|json|ya?ml)$/iu.test(reference)) ||
+            (!/\s/u.test(reference) && /[/\\]/u.test(reference) && !/^[a-z]+:\/\//iu.test(reference));
+    }
+    /** Adds the selected path and recovery guidance to filesystem failures. */
+    function contextReadError(options, path, error) {
+        return new NotAllowed(spaceTrim(`
+        Cannot read ${options.contextLabel.toLowerCase()} file \`${path}\`: ${error.message}
+        Check file permissions and the path in \`${options.optionName}\`.
+    `));
+    }
+
+    /**
+     * Resolves project AGENTS.md on omission; explicit text, files and intentional empty values replace it.
+     */
+    async function resolveCoderContext(contextReference, currentWorkingDirectory) {
+        if (contextReference === undefined) {
+            const contextPath = path.join(currentWorkingDirectory, AGENTS_FILE_PATH);
+            try {
+                return await promises.readFile(contextPath, 'utf-8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // A broken symlink is an existing, unreadable default, not an absent optional file.
+                    const isMissing = await promises.lstat(contextPath).then(() => false, (failure) => failure.code === 'ENOENT');
+                    if (isMissing) {
+                        console.warn(`No additional context: \`${contextPath}\` is missing.`);
+                        return undefined;
+                    }
+                }
+                throw new NotAllowed(spaceTrim(`
+                Cannot read default context file \`${contextPath}\`: ${error instanceof Error ? error.message : String(error)}
+                Check its permissions, or replace it with \`--context\` (an empty value disables additional context).
+            `));
+            }
+        }
+        return resolveInlineOrFileText({
+            textReference: contextReference,
+            currentWorkingDirectory,
+            contextLabel: 'Coding context',
+            optionName: '--context',
+            isMissingFileAnError: true,
+        });
     }
 
     /**
@@ -72276,11 +73027,7 @@
             .toLowerCase()
             .replace(/[^a-z0-9._-]+/gu, '-')
             .replace(/^[._-]+|[._-]+$/gu, '');
-        const sessionName = [
-            safeAgentName || 'agent',
-            Date.now().toString(36),
-            $randomToken(4),
-        ].join('-');
+        const sessionName = [safeAgentName || 'agent', Date.now().toString(36), $randomToken(4)].join('-');
         return resolvePromptbookTemporaryPath(options.currentWorkingDirectory, AGENT_CHAT_TEMPORARY_DIRECTORY_NAME, AGENT_CHAT_SESSIONS_DIRECTORY_NAME, sessionName);
     }
     /**
@@ -72335,7 +73082,7 @@
         return {
             dryRun: false,
             context: undefined,
-            testCommand: undefined,
+            checkCommand: undefined,
             preserveLogs: false,
             noUi: options.noUi,
             thinkingLevel: options.thinkingLevel,
@@ -72401,12 +73148,7 @@
      */
     async function runAgentChat(options) {
         const currentWorkingDirectory = options.currentWorkingDirectory || process.cwd();
-        const context = await resolveInlineOrFileText({
-            textReference: options.context,
-            currentWorkingDirectory,
-            contextLabel: 'Agent context',
-            optionName: '--context',
-        });
+        const context = await resolveCoderContext(options.context, currentWorkingDirectory);
         const workspacePath = createAgentChatWorkspacePath({
             currentWorkingDirectory,
             agentPath: options.agentPath,
@@ -72469,12 +73211,7 @@
             throw new NotAllowed('Pass a non-empty user message in `--message`.');
         }
         const currentWorkingDirectory = options.currentWorkingDirectory || process.cwd();
-        const context = await resolveInlineOrFileText({
-            textReference: options.context,
-            currentWorkingDirectory,
-            contextLabel: 'Agent context',
-            optionName: '--context',
-        });
+        const context = await resolveCoderContext(options.context, currentWorkingDirectory);
         const result = await executeAgentChatTurn({
             ...options,
             currentWorkingDirectory,
@@ -72560,13 +73297,13 @@
      * Watches the queued message directory and answers messages one by one.
      */
     async function runAgentMessages(options, controls = {}) {
-        var _a, _b;
+        var _a, _b, _c;
         validateAgentRunOptions(options);
         validateAgentWatchOptions('ptbk agent-folder run-agent', options);
-        const projectPath = process.cwd();
+        const projectPath = (_a = options.projectPath) !== null && _a !== void 0 ? _a : process.cwd();
         let autoPullTimestamp = options.autoPull ? Date.now() : undefined;
         const shouldContinue = controls.shouldContinue || (() => just(true));
-        const queuePollIntervalMs = (_a = controls.queuePollIntervalMs) !== null && _a !== void 0 ? _a : AGENT_QUEUE_POLL_INTERVAL_MS;
+        const queuePollIntervalMs = (_b = controls.queuePollIntervalMs) !== null && _b !== void 0 ? _b : AGENT_QUEUE_POLL_INTERVAL_MS;
         let isWatchSessionInitialized = false;
         let uiHandle;
         const messageFailureTracker = new AgentMessageFailureTracker({
@@ -72583,7 +73320,7 @@
                     }
                 }
                 const result = await tickAgentMessages(options, { isQuietWhenIdle: true, uiHandle });
-                autoPullTimestamp = (_b = result.autoPullTimestamp) !== null && _b !== void 0 ? _b : autoPullTimestamp;
+                autoPullTimestamp = (_c = result.autoPullTimestamp) !== null && _c !== void 0 ? _c : autoPullTimestamp;
                 if (result.isMessageProcessed) {
                     messageFailureTracker.clearMessageFailure(projectPath, result.queuedMessage);
                     continue;
@@ -78436,8 +79173,8 @@
     /**
      * Builds a display label using the prompt line number for easier navigation.
      */
-    function buildPromptLabelForDisplay(file, section) {
-        return `${path.relative(process.cwd(), file.path).replace(/\\/g, '/')}#${section.startLine + 1}`;
+    function buildPromptLabelForDisplay(file, section, projectPath = process.cwd()) {
+        return `${path.relative(projectPath, file.path).replace(/\\/g, '/')}#${section.startLine + 1}`;
     }
 
     /**
@@ -78452,11 +79189,11 @@
     /**
      * Prints the list of prompts that still need to be written.
      */
-    function printPromptsToBeWritten(files, priorityFilter = {}) {
+    function printPromptsToBeWritten(files, priorityFilter = {}, projectPath) {
         const promptsToWrite = listPromptsToBeWritten(files, priorityFilter);
         let i = 0;
         for (const { file, section } of promptsToWrite) {
-            const label = buildPromptLabelForDisplay(file, section);
+            const label = buildPromptLabelForDisplay(file, section, projectPath);
             const summary = buildPromptSummary(file, section);
             console.info(`  ${++i}) ${label}: ${summary}`);
         }
@@ -78526,7 +79263,7 @@
         }
         else {
             console.info(colors__default["default"].yellow(`Found ${unwrittenPrompts.length} prompt(s) that need to be written:`));
-            printPromptsToBeWritten(promptFiles, priorityFilter);
+            printPromptsToBeWritten(promptFiles, priorityFilter, options.projectPath);
         }
         return unwrittenPrompts.length;
     }
@@ -79370,9 +80107,9 @@
     /**
      * Lists upcoming tasks that are ready to run (no authoring placeholders).
      */
-    function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity) {
+    function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity, projectPath) {
         return listRunnablePrompts(files, priorityFilter, promptRunnerIdentity).map(({ file, section }) => ({
-            label: buildPromptLabelForDisplay(file, section),
+            label: buildPromptLabelForDisplay(file, section, projectPath),
             summary: buildPromptSummary(file, section),
             priority: section.priority,
         }));
@@ -79427,7 +80164,7 @@
         const promptFiles = await loadPromptFiles(path.join((_a = options.projectPath) !== null && _a !== void 0 ? _a : process.cwd(), 'prompts'), {
             isMissingDirectoryAllowed: true,
         });
-        const upcomingTasks = listUpcomingTasks(promptFiles, priorityFilter, options.promptRunnerIdentity);
+        const upcomingTasks = listUpcomingTasks(promptFiles, priorityFilter, options.promptRunnerIdentity, options.projectPath);
         printUpcomingTasks(upcomingTasks);
         return upcomingTasks.length;
     }
@@ -79807,6 +80544,24 @@
         createPlanningTerminal: createPlanningTerminal
     });
 
+    /**
+     * Resolves single-agent execution/authoring defaults without compiling Books or creating artifacts.
+     * Execution previews use the same identity and routing. Utilities and all-agent discovery resolve
+     * only the project directory and must not call this service to manufacture a primary-agent filter.
+     */
+    async function resolveCoderProjectContext(options) {
+        const agentBook = await resolveCoderAgentBook(options.agent, options.projectPath, {
+            defaultRole: DEFAULT_CODER_AGENT_ROLE,
+        });
+        const context = await resolveCoderContext(options.context, options.projectPath);
+        return { projectPath: options.projectPath, agentBook, context };
+    }
+
+    var resolveCoderProjectContext$1 = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        resolveCoderProjectContext: resolveCoderProjectContext
+    });
+
     /** Maximum question length accepted by both command and planning tools. */
     const MAX_MESSAGE_LENGTH = 32000;
     /** Maximum context length accepted by both command and planning tools. */
@@ -80025,6 +80780,19 @@
     }
     // Note: [💞] Runtime contract types accompany their implementation.
 
+    /**
+     * Rebinds an absolute reference inside a project/repository to its worktree copy. Relative references
+     * already resolve against the execution project; explicit references outside that checkout remain explicit.
+     */
+    function mapProjectReferenceToWorktree(reference, originalProjectPath, worktreeProjectPath) {
+        if (reference === undefined || !path.isAbsolute(reference.trim()))
+            return reference;
+        const relativePath = path.relative(originalProjectPath, reference.trim());
+        if (path.isAbsolute(relativePath) || relativePath === '..' || /^\.\.[/\\]/u.test(relativePath))
+            return reference;
+        return path.join(worktreeProjectPath, relativePath);
+    }
+
     /** Limits apply before JSON parsing, even when a client bypasses the generated command. */
     const MAX_REQUEST_BYTES = 131072;
     /** Each invocation receives an independent 256-bit bearer credential. */
@@ -80211,7 +80979,7 @@
      * Adds a scoped consultation transport around an existing adapter. Both primary and advisers keep exactly
      * that adapter's permissions and authentication. Only the enclosing Coder round owns tests, queues and Git operations.
      */
-    function createCoderTeamPromptRunner(runner, agentBookReference) {
+    function createCoderTeamPromptRunner(runner, agentBookReference, originalProjectPath, originalRepositoryRoot = originalProjectPath) {
         var _a;
         return {
             name: runner.name,
@@ -80227,8 +80995,11 @@
                 let runtime;
                 try {
                     // Resolve against this invocation's actual checkout, including an isolated worktree.
-                    const agent = await resolveCoderAgent(agentBookReference, options.projectPath, {
-                        defaultRole: 'developer',
+                    const reference = originalProjectPath
+                        ? mapProjectReferenceToWorktree(agentBookReference, originalRepositoryRoot, path.resolve(options.projectPath, path.relative(originalProjectPath, originalRepositoryRoot)))
+                        : agentBookReference;
+                    const agent = await resolveCoderAgent(reference, options.projectPath, {
+                        defaultRole: DEFAULT_CODER_AGENT_ROLE,
                         isInitializationAllowed: false,
                         signal: controller.signal,
                     });
@@ -81109,11 +81880,12 @@
      * @private internal utility of `coder plan`
      */
     async function runPlanningSession(options, io, harness = runPlanningHarness) {
-        var _a, _b;
+        var _a, _b, _c;
         const projectPath = await promises.realpath(options.projectPath);
         assertPlanningHarnessSupported(options.agentName);
+        const projectContext = (_a = options.projectContext) !== null && _a !== void 0 ? _a : (await resolveCoderProjectContext({ ...options, projectPath }));
         const agent = await resolveCoderAgent(options.agent, projectPath, {
-            defaultRole: 'planner',
+            defaultRole: DEFAULT_CODER_AGENT_ROLE,
             isInitializationAllowed: false,
             signal: io.signal,
         });
@@ -81121,9 +81893,9 @@
             throw new NotFoundError(spaceTrim('Planning requires `prompts/`. Run `ptbk coder init` first.'));
         }
         if (!agent)
-            throw new NotFoundError(spaceTrim('Planner Book is missing. Run `ptbk coder init`.'));
+            throw new NotFoundError(spaceTrim('Primary Book is missing. Run `ptbk coder init`.'));
         resolvePlanningPath(projectPath, 'prompts');
-        const templateOption = (_a = options.template) !== null && _a !== void 0 ? _a : (fs.existsSync(path.join(projectPath, COMMON_PROMPT_TEMPLATE_FILE_PATH))
+        const templateOption = (_b = options.template) !== null && _b !== void 0 ? _b : (fs.existsSync(path.join(projectPath, COMMON_PROMPT_TEMPLATE_FILE_PATH))
             ? COMMON_PROMPT_TEMPLATE_FILE_PATH
             : undefined);
         const template = await resolveCoderPromptTemplate({ projectPath, templateOption });
@@ -81167,7 +81939,10 @@
                 },
                 { role: 'context', content: await readPlanningContext(projectPath, { kind: 'list', path: '.' }) },
             ];
-            for (const path$1 of ['README.md', 'AGENTS.md']) {
+            if (projectContext.context !== undefined) {
+                history.push({ role: 'context', content: projectContext.context });
+            }
+            for (const path$1 of ['README.md']) {
                 if (fs.existsSync(path.join(projectPath, path$1))) {
                     history.push({
                         role: 'context',
@@ -81184,7 +81959,7 @@
             let pending = [];
             io.write(`${agent.agentName}: Discuss features and review PRD proposals. /save applies the preview; /draft saves unresolved drafts; /discard drops it; /exit ends. Ctrl+C cancels.\n`);
             while (!io.signal.aborted) {
-                const message = (_b = (await io.readMessage())) === null || _b === void 0 ? void 0 : _b.trim();
+                const message = (_c = (await io.readMessage())) === null || _c === void 0 ? void 0 : _c.trim();
                 if (message === undefined || ['/exit', 'exit', 'quit'].includes(message))
                     break;
                 if (!message)
@@ -81321,7 +82096,7 @@
     /**
      * CLI usage text for this script.
      */
-    const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--agent <agent-book-path>] [--context <context-or-file>] [--test <test-command...>] [--test-before <no|yes-and-fail|yes-and-fix>] [--preserve-logs] [--isolate] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--min-priority <minimum-priority>] [--max-priority <maximum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--git-changes <fail|ignore|continue>] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+    const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--agent <agent-book-path>] [--context <context-or-file>] [--check <check-command...>] [--check-before <no|yes-and-fail|yes-and-fix>] [--preserve-logs] [--isolate] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--min-priority <minimum-priority>] [--max-priority <maximum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--git-changes <fail|ignore|continue>] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
     /**
      * Top-level flags supported by this command.
      */
@@ -81331,8 +82106,8 @@
         '--model',
         '--agent',
         '--context',
-        '--test',
-        '--test-before',
+        '--check',
+        '--check-before',
         '--preserve-logs',
         '--isolate',
         '--no-ui',
@@ -81358,6 +82133,15 @@
      * Parses CLI arguments into runner options.
      */
     function parseRunOptions(args) {
+        args = args.flatMap((argument) => {
+            const match = argument.match(/^(--check(?:-before)?)=([\s\S]*)$/u);
+            return match ? [match[1], match[2]] : [argument];
+        });
+        for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+            if (args.some((argument) => argument === legacyFlag || argument.startsWith(`${legacyFlag}=`))) {
+                exitWithUsageError(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+            }
+        }
         let agentName = undefined;
         const dryRun = args.includes('--dry-run');
         const harnessValue = readOptionValue(args, '--harness');
@@ -81373,10 +82157,10 @@
             exitWithUsageError('Pass a non-empty Book path after `--agent`, or omit it to use `agents/developer.book`.');
         }
         const context = readOptionValue(args, '--context');
-        const hasTestCommandFlag = args.includes('--test');
-        const testCommand = readVariadicOptionValue(args, '--test');
-        const hasTestBeforeFlag = args.includes('--test-before');
-        const testBefore = parseTestBeforeOption(readOptionValue(args, '--test-before'), hasTestBeforeFlag);
+        const hasCheckCommandFlag = args.includes('--check');
+        const checkCommand = readVariadicOptionValue(args, '--check');
+        const hasCheckBeforeFlag = args.includes('--check-before');
+        const checkBefore = parseCheckBeforeOption(readOptionValue(args, '--check-before'), hasCheckBeforeFlag);
         const preserveLogs = args.includes('--preserve-logs');
         const isIsolated = args.includes('--isolate');
         const noUi = args.includes('--no-ui');
@@ -81414,8 +82198,8 @@
         const waitBetweenPrompts = parseWaitOption(args, '--wait-between-prompts', 0);
         const waitAfterError = parseWaitOption(args, '--wait-after-error', DEFAULT_WAIT_AFTER_ERROR_MS);
         let thinkingLevel;
-        if (hasTestCommandFlag && testCommand === undefined) {
-            exitWithUsageError('Missing value for --test. Use a shell command such as `npm run test` and quote it when it contains top-level CLI flags.');
+        if (hasCheckCommandFlag && checkCommand === undefined) {
+            exitWithUsageError('Missing value for --check. Use a shell command such as `npm run check` and quote it when it contains top-level CLI flags.');
         }
         if (hasThinkingLevelFlag && thinkingLevelValue === undefined) {
             exitWithUsageError(`Missing value for --thinking-level. Use one of: ${THINKING_LEVEL_VALUES.join(', ')}.`);
@@ -81450,8 +82234,8 @@
             model,
             agent,
             context,
-            testCommand,
-            testBefore,
+            checkCommand: resolveCoderCheckCommand(checkCommand, checkBefore),
+            checkBefore,
             thinkingLevel,
             priority: minimumPriority !== null && minimumPriority !== void 0 ? minimumPriority : 0,
             minimumPriority,
@@ -81463,15 +82247,15 @@
     /**
      * Parses and validates the optional pre-coding verification mode.
      */
-    function parseTestBeforeOption(value, hasTestBeforeFlag) {
+    function parseCheckBeforeOption(value, hasCheckBeforeFlag) {
         if (value === undefined) {
-            if (hasTestBeforeFlag) {
-                exitWithUsageError(`Missing value for --test-before. Use one of: ${TEST_BEFORE_MODE_VALUES.join(', ')}.`);
+            if (hasCheckBeforeFlag) {
+                exitWithUsageError(`Missing value for --check-before. Use one of: ${CHECK_BEFORE_MODE_VALUES.join(', ')}.`);
             }
             return 'no';
         }
-        if (!isTestBeforeMode(value)) {
-            exitWithUsageError(`Invalid value for --test-before: "${value}". Use one of: ${TEST_BEFORE_MODE_VALUES.join(', ')}.`);
+        if (!isCheckBeforeMode(value)) {
+            exitWithUsageError(`Invalid value for --check-before: "${value}". Use one of: ${CHECK_BEFORE_MODE_VALUES.join(', ')}.`);
         }
         return value;
     }
@@ -81532,8 +82316,14 @@
             }
             valueParts.push(valuePart);
         }
-        const normalizedValue = valueParts.join(' ').trim();
-        return normalizedValue === '' ? undefined : normalizedValue;
+        if (valueParts.length === 0)
+            return undefined;
+        try {
+            return normalizeCheckCommandOption(valueParts);
+        }
+        catch (error) {
+            exitWithUsageError(error instanceof Error ? error.message : String(error));
+        }
     }
     /**
      * Parses and validates one priority boundary.
@@ -81975,18 +82765,6 @@
         });
     }
 
-    /**
-     * Resolves optional coding context provided inline or via a file path.
-     */
-    async function resolveCoderContext(contextReference, currentWorkingDirectory) {
-        return resolveInlineOrFileText({
-            textReference: contextReference,
-            currentWorkingDirectory,
-            contextLabel: 'Coding context',
-            optionName: '--context',
-        });
-    }
-
     /**
      * Listens for the terminal control keys while the plain console output is used.
      *
@@ -83581,7 +84359,7 @@
      */
     const CODER_RUN_STEP_LABELS = {
         implementation: 'Implementation',
-        testing: 'Testing',
+        checking: 'Checking',
         fixing: 'Fixing',
     };
     /**
@@ -83592,16 +84370,16 @@
      * Formats the per-step usage breakdown recorded for one prompt.
      *
      * Produces a `; `-separated summary such as
-     * `Implementation $8.01 6 hours; Testing 1 hour; Fixing $3.14 2 hours` where each coding step carries its
+     * `Implementation $8.01 6 hours; Checking 1 hour; Fixing $3.14 2 hours` where each coding step carries its
      * price and duration and each verification step carries only its duration.
      *
      * @param steps - Steps which have already finished
-     * @param inProgressStepKind - Step which has started but has not finished yet, appended as `Testing in progress`
+     * @param inProgressStepKind - Step which has started but has not finished yet, appended as `Checking in progress`
      */
     function formatCoderRunSteps(steps, inProgressStepKind) {
         const formattedSteps = steps.map(formatCoderRunStep);
         if (inProgressStepKind !== undefined) {
-            formattedSteps.push(`${CODER_RUN_STEP_LABELS[inProgressStepKind]} ${IN_PROGRESS_STEP_SUFFIX}`);
+            formattedSteps.push(`${CODER_RUN_STEP_LABELS[decodeCoderRunStepKind(inProgressStepKind)]} ${IN_PROGRESS_STEP_SUFFIX}`);
         }
         return formattedSteps.join('; ');
     }
@@ -83609,7 +84387,7 @@
      * Formats one coder run step as `Label $price duration`, omitting the price for steps without model usage.
      */
     function formatCoderRunStep(step) {
-        const label = CODER_RUN_STEP_LABELS[step.kind];
+        const label = CODER_RUN_STEP_LABELS[decodeCoderRunStepKind(step.kind)];
         const durationString = moment__default["default"].duration(step.durationMs).humanize();
         const priceString = step.usage === null ? undefined : formatUsagePrice(step.usage);
         if (priceString === undefined) {
@@ -83617,6 +84395,10 @@
         }
         return `${label} ${priceString} ${durationString}`;
     }
+    /** Decodes the old aggregate step name at the display boundary; new execution only records checking. */
+    function decodeCoderRunStepKind(kind) {
+        return kind === 'testing' ? 'checking' : kind;
+    }
 
     /**
      * Formats optional attempt metadata stored in prompt status lines.
@@ -83957,13 +84739,13 @@
             `-   **Runner:** ${runnerSignature}${loginMethodSuffix}`,
             `-   **Attempts:** ${options.attemptCount}`,
             ...buildPromptRunTraceStepsLines(outcome),
-            ...buildPromptRunTraceTestCommandLines(options.testCommand),
+            ...buildPromptRunTraceCheckCommandLines(options.checkCommand),
             `-   **Started:** ${options.startedDate.toISOString()}`,
             `-   **Finished:** ${options.finishedDate.toISOString()}`,
             `-   **Duration:** ${moment__default["default"].duration(options.finishedDate.diff(options.startedDate)).humanize()}`,
         ];
         return _spaceTrim.spaceTrim((block) => `
-            # Run trace of \`${buildPromptLabelForDisplay(file, section)}\`
+            # Run trace of \`${buildPromptLabelForDisplay(file, section, options.projectPath)}\`
 
             ${block(detailLines.join('\n'))}
         `);
@@ -83996,11 +84778,11 @@
     /**
      * Renders the verification command of the round, omitted when the round ran without one.
      */
-    function buildPromptRunTraceTestCommandLines(testCommand) {
-        if (!testCommand) {
+    function buildPromptRunTraceCheckCommandLines(checkCommand) {
+        if (!checkCommand) {
             return [];
         }
-        return [`-   **Verification command:** \`${testCommand}\``];
+        return [`-   **Check command:** \`${checkCommand}\``];
     }
     /**
      * Renders the failure details of a failed round, omitted for a successful one.
@@ -84087,9 +84869,9 @@
      *
      * @private function of runCodexPrompts
      */
-    async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, projectPath, }) {
-        var _a, _b;
-        const roundProjectPath = (_b = projectPath !== null && projectPath !== void 0 ? projectPath : (_a = options.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : process.cwd();
+    async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, projectPath, artifactsProjectPath, }) {
+        var _a, _b, _c;
+        const roundProjectPath = (_c = (_b = projectPath !== null && projectPath !== void 0 ? projectPath : (_a = options.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : options.projectPath) !== null && _c !== void 0 ? _c : process.cwd();
         const commitMessage = buildCommitMessage(nextPrompt.file, nextPrompt.section);
         const taskPrompt = buildCodexPrompt(nextPrompt.file, nextPrompt.section);
         // Prepend agent system message before the task so the harness sees agent instructions first
@@ -84106,8 +84888,7 @@
               `)
             : taskPrompt;
         const codexPrompt = appendCoderContext(promptWithAgent, resolvedCoderContext);
-        // Note: Temporary scripts and runtime logs stay in the original project so they outlive an isolated worktree
-        const scriptPath = buildScriptPath(nextPrompt.file, nextPrompt.section);
+        const scriptPath = buildScriptPath(nextPrompt.file, nextPrompt.section, artifactsProjectPath !== null && artifactsProjectPath !== void 0 ? artifactsProjectPath : roundProjectPath);
         // Note: Read before the first `[^]` rewrite of this round, which would overwrite the report recorded so far
         const previousRunnerSignatures = resolvePreviousRunnerSignatures(nextPrompt);
         setPromptRoundRunningState({ isRichUiEnabled, promptLabel, scriptPath, uiHandle });
@@ -84126,13 +84907,13 @@
             for (let errorRetryAttempt = 0; errorRetryAttempt <= MAX_RETRY_ATTEMPTS_AFTER_ERROR; errorRetryAttempt++) {
                 try {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
-                    const result = await runPromptWithTestFeedback({
+                    const result = await runPromptWithCheckFeedback({
                         runner,
                         prompt: codexPrompt,
                         scriptPath,
                         projectPath: roundProjectPath,
                         promptLabel,
-                        testCommand: options.testCommand,
+                        checkCommand: options.checkCommand,
                         preserveArtifactsOnSuccess: options.preserveLogs,
                         logPath,
                         onAttemptStarted: (nextAttemptCount) => {
@@ -84172,7 +84953,9 @@
                     lastError = error;
                     // Note: A harness which is not logged in answers every retry the same way, so the user gets
                     //       the sign-in instructions right away instead of after every retry has waited its delay
-                    if (error instanceof AuthenticationError || errorRetryAttempt >= MAX_RETRY_ATTEMPTS_AFTER_ERROR) {
+                    if (error instanceof AuthenticationError ||
+                        error instanceof CoderCheckSetupError ||
+                        errorRetryAttempt >= MAX_RETRY_ATTEMPTS_AFTER_ERROR) {
                         break;
                     }
                     await waitAfterErrorBeforeRetry({
@@ -84414,13 +85197,15 @@
      * harness, model and thinking level did it and everything that harness has written while doing it.
      */
     async function recordPromptRoundTrace(options) {
+        var _a, _b;
         const { options: runOptions, nextPrompt, runnerMetadata, promptExecutionStartedDate, attemptCount, logPath, outcome, } = options;
         await writePromptRunTrace({
+            projectPath: (_b = (_a = runOptions.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : runOptions.projectPath,
             file: nextPrompt.file,
             section: nextPrompt.section,
             ...runnerMetadata,
             thinkingLevel: runOptions.thinkingLevel,
-            testCommand: runOptions.testCommand,
+            checkCommand: runOptions.checkCommand,
             attemptCount,
             startedDate: promptExecutionStartedDate,
             finishedDate: moment__default["default"](),
@@ -85018,12 +85803,12 @@
      * @private function of runCodexPrompts
      */
     async function runIsolatedPromptRound(options) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const { nextPrompt, promptLabel, isRichUiEnabled, uiHandle, waitForRequestedPause } = options;
-        const projectPath = (_c = (_a = options.projectPath) !== null && _a !== void 0 ? _a : (_b = options.options.workspace) === null || _b === void 0 ? void 0 : _b.projectPath) !== null && _c !== void 0 ? _c : process.cwd();
+        const projectPath = (_d = (_c = (_a = options.projectPath) !== null && _a !== void 0 ? _a : (_b = options.options.workspace) === null || _b === void 0 ? void 0 : _b.projectPath) !== null && _c !== void 0 ? _c : options.options.projectPath) !== null && _d !== void 0 ? _d : process.cwd();
         // Note: The original project is left untouched by the isolated round itself, so its scope covers exactly
         //       the prompt status update and the changes the merge brings back from the worktree
-        const originalProjectCommitScope = await captureCoderCommitScope((_d = options.options.workspace) !== null && _d !== void 0 ? _d : projectPath);
+        const originalProjectCommitScope = await captureCoderCommitScope((_e = options.options.workspace) !== null && _e !== void 0 ? _e : projectPath);
         const worktree = await createCoderIsolationWorktree({
             projectPath,
             repositoryRoot: originalProjectCommitScope.repositoryRoot,
@@ -85031,16 +85816,44 @@
         });
         announceIsolatedRoundStart(worktree, promptLabel, isRichUiEnabled);
         try {
-            const isolatedProjectPath = path.join(worktree.worktreePath, path.relative((_e = originalProjectCommitScope.repositoryRoot) !== null && _e !== void 0 ? _e : projectPath, projectPath));
+            const isolatedProjectPath = path.join(worktree.worktreePath, path.relative((_f = originalProjectCommitScope.repositoryRoot) !== null && _f !== void 0 ? _f : projectPath, projectPath));
             // This newly created working tree has its own metadata. Keep the project's repository-relative
             // location so its harness and verification use the same project as the original invocation.
             const isolatedWorkspace = await $resolveWorkspaceRepository(isolatedProjectPath);
+            const isolatedOptions = {
+                ...options.options,
+                workspace: isolatedWorkspace,
+                projectPath: isolatedWorkspace.projectPath,
+                agent: mapProjectReferenceToWorktree(options.options.agent, (_g = originalProjectCommitScope.repositoryRoot) !== null && _g !== void 0 ? _g : projectPath, worktree.worktreePath),
+                context: mapProjectReferenceToWorktree(options.options.context, (_h = originalProjectCommitScope.repositoryRoot) !== null && _h !== void 0 ? _h : projectPath, worktree.worktreePath),
+                autoPush: false,
+            };
+            const projectContext = await resolveCoderProjectContext(isolatedOptions);
+            const agent = await resolveCoderAgent(isolatedOptions.agent, isolatedWorkspace.projectPath, {
+                defaultRole: DEFAULT_CODER_AGENT_ROLE,
+                isInitializationAllowed: false,
+            });
+            // Status updates, traces and commits belong to the same checkout as the harness and checks.
+            // Copy the parsed data too, so a failed isolated round does not mutate the original queue in memory.
+            const isolatedFile = {
+                ...nextPrompt.file,
+                path: path.join(isolatedWorkspace.projectPath, path.relative(projectPath, nextPrompt.file.path)),
+                lines: [...nextPrompt.file.lines],
+                sections: nextPrompt.file.sections.map((section) => ({ ...section })),
+            };
             await runPromptRound({
                 ...options,
+                nextPrompt: { file: isolatedFile, section: isolatedFile.sections[nextPrompt.section.index] },
                 projectPath: isolatedWorkspace.projectPath,
+                // Temporary scripts and raw logs deliberately outlive the worktree; PRDs and traces are merged.
+                artifactsProjectPath: projectPath,
+                resolvedCoderContext: projectContext.context,
+                resolvedAgentSystemMessage: agent === null || agent === void 0 ? void 0 : agent.systemMessage,
                 // Note: The isolated commit must never reach the remote, the merged commit on the original branch is pushed instead
-                options: { ...options.options, workspace: isolatedWorkspace, autoPush: false },
+                options: { ...isolatedOptions, projectContext },
             });
+            // Keep the display/commit identity in sync without writing to the original checkout before merging.
+            Object.assign(nextPrompt.section, isolatedFile.sections[nextPrompt.section.index]);
         }
         catch (error) {
             // Note: The worktree keeps whatever the failed round produced, which would be lost by deleting it here
@@ -85061,7 +85874,7 @@
         await commitChanges(buildCommitMessage(nextPrompt.file, nextPrompt.section), {
             autoPush: options.options.autoPush,
             relevantPaths: await resolveCoderCommitScopePaths(originalProjectCommitScope),
-            projectPath: (_f = originalProjectCommitScope.repositoryRoot) !== null && _f !== void 0 ? _f : projectPath,
+            projectPath: (_j = originalProjectCommitScope.repositoryRoot) !== null && _j !== void 0 ? _j : projectPath,
         });
         await removeCoderIsolationWorktree(worktree);
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Merged \`${worktree.taskName}\` into \`${worktree.baseBranchName}\``);
@@ -85070,9 +85883,23 @@
      * Records a failed isolation merge in the original project and keeps the worktree for a manual merge.
      */
     async function recordIsolationMergeFailure(options, worktree, failureDetails) {
-        var _a, _b;
+        var _a, _b, _c, _d;
         const { nextPrompt, runnerMetadata, isRichUiEnabled, uiHandle } = options;
         const mergeFailureError = buildCoderIsolationMergeFailureError(worktree, failureDetails);
+        const repositoryRoot = (_b = (_a = options.options.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot) !== null && _b !== void 0 ? _b : worktree.projectPath;
+        const tracePath = buildPromptRunTracePath(nextPrompt.file, nextPrompt.section);
+        const isolatedTracePath = path.join(worktree.worktreePath, path.relative(repositoryRoot, tracePath));
+        // The failed merge did not bring back the worktree's trace. Preserve it beside the failure report.
+        await promises.mkdir(path.dirname(tracePath), { recursive: true });
+        let isTraceCopied = false;
+        try {
+            await promises.copyFile(isolatedTracePath, tracePath);
+            isTraceCopied = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
         markPromptIsolationMergeFailed(nextPrompt.file, nextPrompt.section, worktree);
         await writePromptFile(nextPrompt.file);
         const errorLogPath = await writePromptErrorLog({
@@ -85084,13 +85911,11 @@
         });
         await commitChanges(buildCoderIsolationMergeFailureCommitMessage(worktree), {
             autoPush: options.options.autoPush,
-            projectPath: (_b = (_a = options.options.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot) !== null && _b !== void 0 ? _b : worktree.projectPath,
-            // Note: The round itself has already succeeded, so it has left its run trace in the original project.
-            //       It belongs to this commit, which is the only one this task still gets.
+            projectPath: (_d = (_c = options.options.workspace) === null || _c === void 0 ? void 0 : _c.repositoryRoot) !== null && _d !== void 0 ? _d : worktree.projectPath,
             relevantPaths: [
                 nextPrompt.file.path,
                 errorLogPath,
-                buildPromptRunTracePath(nextPrompt.file, nextPrompt.section),
+                ...(isTraceCopied ? [tracePath] : []),
             ].map((path) => { var _a, _b; return toProjectRelativeGitPath((_b = (_a = options.options.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot) !== null && _b !== void 0 ? _b : worktree.projectPath, path); }),
         });
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.addError(mergeFailureError.message);
@@ -85131,8 +85956,8 @@
     /**
      * Builds a label that identifies the prompt section by index.
      */
-    function buildPromptLabel(file, section) {
-        return `${path.relative(process.cwd(), file.path).replace(/\\/g, '/')}#${section.index + 1}`;
+    function buildPromptLabel(file, section, projectPath = process.cwd()) {
+        return `${path.relative(projectPath, file.path).replace(/\\/g, '/')}#${section.index + 1}`;
     }
 
     /**
@@ -85360,18 +86185,20 @@
     }
 
     /**
-     * Creates the one queue prompt used to repair a pre-existing test failure.
+     * Creates the one queue prompt used to repair a pre-existing project check failure.
      */
-    async function createTestBeforeRepairPrompt(options) {
+    async function createCheckBeforeRepairPrompt(options) {
         const description = spaceTrim((block) => `
-            Fix the existing test failures before implementing any queued coding tasks.
+            Fix the existing check failures before implementing any queued coding tasks.
+
+            The check command \`${options.checkCommand}\` failed before coding started. Leave the project ready for the remaining coding prompts.
 
-            The verification command \`${options.testCommand}\` failed before coding started. Fix the underlying failure without weakening or removing the tests, and leave the project ready for the remaining coding prompts.
+            ${block(CHECK_REPAIR_INSTRUCTIONS)}
 
-            ## Verification output
+            ## Check output
 
             \`\`\`
-            ${block(limitTestOutput(options.testOutput))}
+            ${block(limitCheckOutput(options.checkOutput))}
             \`\`\`
         `);
         const createdPrompt = await addCoderPrompt({
@@ -85384,50 +86211,56 @@
         const section = promptFile.sections[0];
         if (!section) {
             throw new UnexpectedError(spaceTrim(`
-                The pre-coding test repair prompt was created at \`${createdPrompt.filePath}\` without a runnable section.
+                The pre-coding check repair prompt was created at \`${createdPrompt.filePath}\` without a runnable section.
             `));
         }
         return { file: promptFile, section };
     }
 
     /**
-     * Runs the configured verification command before the first coding prompt.
+     * Runs the configured check command before the first coding prompt.
      */
-    async function runTestBefore(options) {
-        var _a, _b;
-        const runPromptTestCommandExecutor = (_a = options.runPromptTestCommandExecutor) !== null && _a !== void 0 ? _a : runPromptTestCommand;
-        const initialTestStatusMessage = `Running initial tests before the agent coding starts: ${options.testCommand}`;
-        await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
-            checkpointLabel: 'running initial tests before the agent coding starts',
+    async function runCheckBefore(options) {
+        var _a, _b, _c, _d, _e, _f;
+        (_a = options.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
+        const runPromptCheckCommandExecutor = (_b = options.runPromptCheckCommandExecutor) !== null && _b !== void 0 ? _b : runPromptCheckCommand;
+        const initialCheckStatusMessage = `Running initial checks before the agent coding starts: ${options.checkCommand}`;
+        await ((_c = options.waitForPauseCheckpoint) === null || _c === void 0 ? void 0 : _c.call(options, {
+            checkpointLabel: 'running initial checks before the agent coding starts',
             phase: 'verifying',
-            statusMessage: initialTestStatusMessage,
+            statusMessage: initialCheckStatusMessage,
         }));
-        console.info(colors__default["default"].gray(initialTestStatusMessage));
+        (_d = options.signal) === null || _d === void 0 ? void 0 : _d.throwIfAborted();
+        console.info(colors__default["default"].gray(initialCheckStatusMessage));
         try {
-            const testOutput = await runPromptTestCommandExecutor({
-                command: options.testCommand,
+            const checkOutput = await runPromptCheckCommandExecutor({
+                command: options.checkCommand,
                 projectPath: options.projectPath,
                 scriptPath: buildTemporaryPromptScriptPath({
                     projectPath: options.projectPath,
                     scriptDirectoryName: 'coder-prompts',
-                    sourceFileName: 'test-before',
+                    sourceFileName: 'check-before',
                 }),
+                ...(options.signal ? { signal: options.signal } : {}),
             });
-            console.info(colors__default["default"].green('Pre-coding tests passed.'));
-            return { isPassed: true, testOutput };
+            (_e = options.signal) === null || _e === void 0 ? void 0 : _e.throwIfAborted();
+            console.info(colors__default["default"].green('Pre-coding checks passed.'));
+            return { isPassed: true, checkOutput };
         }
         catch (error) {
-            const testOutput = formatUnknownErrorMessage(error);
-            console.error(colors__default["default"].red('Pre-coding tests failed.'));
-            console.error(testOutput);
-            return { isPassed: false, testOutput };
+            if (error instanceof CoderCheckSetupError || ((_f = options.signal) === null || _f === void 0 ? void 0 : _f.aborted))
+                throw error;
+            const checkOutput = formatUnknownErrorMessage(error);
+            console.error(colors__default["default"].red('Pre-coding checks failed.'));
+            console.error(checkOutput);
+            return { isPassed: false, checkOutput };
         }
     }
 
     /**
-     * Commit message for files changed by a successful or failed pre-coding test in repair mode.
+     * Commit message for files changed by a successful or failed pre-coding check in repair mode.
      */
-    const PRE_CODING_TEST_CHANGES_COMMIT_MESSAGE = 'test: Apply changes made by pre-coding tests';
+    const PRE_CODING_CHECK_CHANGES_COMMIT_MESSAGE = 'chore: Apply changes made by pre-coding checks';
     /**
      * Main entry point for running prompts with the selected agent.
      *
@@ -85436,10 +86269,15 @@
      * @public exported from `@promptbook/cli`
      */
     async function runCodexPrompts(providedOptions) {
-        var _a, _b, _c, _d;
-        const options = normalizeRunOptions(providedOptions !== null && providedOptions !== void 0 ? providedOptions : parseRunOptions(process.argv.slice(2)));
-        validateCoderRunOptions(options);
-        const projectPath = (_b = (_a = options.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : process.cwd();
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const normalizedOptions = normalizeRunOptions(providedOptions !== null && providedOptions !== void 0 ? providedOptions : parseRunOptions(process.argv.slice(2)));
+        validateCoderRunOptions(normalizedOptions);
+        // CLI-preflighted workspaces are already canonical. For direct runs without an explicit project path, preserve
+        // `process.cwd()` as written because macOS may expose the same temporary directory through `/var` and `/private/var`.
+        const projectPath = (_b = (_a = normalizedOptions.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : ((providedOptions === null || providedOptions === void 0 ? void 0 : providedOptions.projectPath) === undefined
+            ? normalizedOptions.projectPath
+            : await resolveProjectDirectory(normalizedOptions.projectPath));
+        const options = { ...normalizedOptions, projectPath };
         resetCoderRunControls();
         const runStartDate = moment__default["default"]();
         const { isRichUiEnabled, progressDisplay, uiHandle } = createRunDisplays(options, runStartDate);
@@ -85457,20 +86295,25 @@
         startPauseListenerIfNeeded(isRichUiEnabled);
         let subscriptionUsageRefresh;
         try {
-            const resolvedCoderContext = await resolveCoderContext(options.context, projectPath);
+            const projectContext = (_d = options.projectContext) !== null && _d !== void 0 ? _d : (await resolveCoderProjectContext({
+                ...options,
+                projectPath,
+            }));
+            if (await runDryRunIfRequested(options, (_e = projectContext.agentBook) === null || _e === void 0 ? void 0 : _e.agentReferences)) {
+                return;
+            }
+            await assertProjectCheckIsConfigured(options.checkCommand, projectPath);
+            const resolvedCoderContext = projectContext.context;
             const resolvedCoderAgent = await resolveCoderAgent(options.agent, projectPath, {
-                defaultRole: 'developer',
+                defaultRole: DEFAULT_CODER_AGENT_ROLE,
                 isInitializationAllowed: !options.dryRun,
             });
             const resolvedAgentSystemMessage = resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.systemMessage;
-            if (await runDryRunIfRequested(options, resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.agentReferences)) {
-                return;
-            }
             if (!options.noCommit && resolvedCoderAgent) {
                 await commitInitializedAgentBooks(projectPath, resolvedCoderAgent.createdAgentBookPaths, options.workspace);
             }
             const { runner: harnessRunner, actualRunnerModel, runnerMetadata: harnessRunnerMetadata, } = resolvePromptRunner(options);
-            const runner = createCoderTeamPromptRunner(harnessRunner, options.agent);
+            const runner = createCoderTeamPromptRunner(harnessRunner, options.agent, projectPath, (_f = options.workspace) === null || _f === void 0 ? void 0 : _f.repositoryRoot);
             // Note: The harness only knows itself, so the Book agent it runs as is joined here - this is the single
             //       place where the whole run report of prompt status lines and run traces is put together
             const runnerMetadata = {
@@ -85501,7 +86344,7 @@
             let previousRoundStartTime;
             let previousRoundEndTime;
             let completedRunCount = 0;
-            let hasRunTestBefore = false;
+            let hasRunCheckBefore = false;
             // Note: Only the very first round resumes the interrupted prompt, every later round starts from a clean tree
             let isContinuingInterruptedPrompt = options.gitChanges === 'continue';
             while (just(true)) {
@@ -85516,11 +86359,11 @@
                     options,
                     isRichUiEnabled,
                 });
-                if (!hasRunTestBefore && options.testBefore !== 'no') {
+                if (!hasRunCheckBefore && options.checkBefore !== 'no') {
                     await waitForRequestedPause({
-                        checkpointLabel: 'loading prompts before running initial tests',
+                        checkpointLabel: 'loading prompts before running initial checks',
                         phase: 'loading',
-                        statusMessage: 'Loading prompts before running initial tests...',
+                        statusMessage: 'Loading prompts before running initial checks...',
                     });
                     await loadPromptQueueSnapshot({
                         options,
@@ -85531,8 +86374,8 @@
                         isContinuingInterruptedPrompt,
                     });
                 }
-                if (!hasRunTestBefore) {
-                    hasWaitedForStart = await runTestBeforeIfNeeded({
+                if (!hasRunCheckBefore) {
+                    hasWaitedForStart = await runCheckBeforeIfNeeded({
                         options,
                         runner,
                         runnerMetadata,
@@ -85545,7 +86388,7 @@
                         hasWaitedForStart,
                         isContinuingInterruptedPrompt,
                     });
-                    hasRunTestBefore = true;
+                    hasRunCheckBefore = true;
                 }
                 await waitForRequestedPause({
                     checkpointLabel: 'loading prompts',
@@ -85561,6 +86404,7 @@
                     isContinuingInterruptedPrompt,
                 });
                 hasShownUpcomingTasks || (hasShownUpcomingTasks = showUpcomingTasksOnce({
+                    projectPath,
                     hasShownUpcomingTasks,
                     promptFiles: promptQueueSnapshot.promptFiles,
                     stats: promptQueueSnapshot.stats,
@@ -85591,7 +86435,7 @@
                     return;
                 }
                 const nextPrompt = promptQueueSnapshot.nextPrompt;
-                const promptLabel = buildPromptLabelForDisplay(nextPrompt.file, nextPrompt.section);
+                const promptLabel = buildPromptLabelForDisplay(nextPrompt.file, nextPrompt.section, projectPath);
                 // Wait between prompt rounds (skipped for the first round)
                 if (previousRoundStartTime !== undefined && previousRoundEndTime !== undefined) {
                     await waitBetweenPromptRoundsIfNeeded({
@@ -85626,7 +86470,7 @@
                         phase: 'loading',
                         statusMessage: 'Checking the working tree...',
                     });
-                    await ensureWorkingTreeClean((_d = options.workspace) === null || _d === void 0 ? void 0 : _d.repositoryRoot);
+                    await ensureWorkingTreeClean((_h = (_g = options.workspace) === null || _g === void 0 ? void 0 : _g.repositoryRoot) !== null && _h !== void 0 ? _h : projectPath);
                 }
                 const currentRoundStartTime = Date.now();
                 // Note: An isolated round implements the prompt in a temporary worktree and merges it back afterwards
@@ -85688,7 +86532,7 @@
      * Pulls the latest repository state before loading prompts when the feature is enabled.
      */
     async function pullLatestChangesIfEnabled(options) {
-        var _a;
+        var _a, _b;
         const { options: runOptions, isRichUiEnabled } = options;
         if (!runOptions.autoPull || runOptions.dryRun) {
             return;
@@ -85696,7 +86540,7 @@
         if (!isRichUiEnabled) {
             console.info(colors__default["default"].gray('Pulling latest changes before the next prompt...'));
         }
-        await pullLatestChanges((_a = runOptions.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot);
+        await pullLatestChanges((_b = (_a = runOptions.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot) !== null && _b !== void 0 ? _b : runOptions.projectPath);
     }
     /**
      * Creates the progress display and rich UI handles used during the run.
@@ -85721,19 +86565,19 @@
      * Normalizes legacy and current priority options into one validated run option shape.
      */
     function normalizeRunOptions(options) {
-        var _a, _b, _c, _d, _e, _f, _g;
-        const testBefore = (_a = options.testBefore) !== null && _a !== void 0 ? _a : 'no';
-        const normalizedTestCommand = (_b = options.testCommand) === null || _b === void 0 ? void 0 : _b.trim();
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        const checkBefore = (_a = options.checkBefore) !== null && _a !== void 0 ? _a : 'no';
         const priorityFilter = normalizePriorityFilter({
             priority: options.priority,
-            minimumPriority: (_c = options.minimumPriority) !== null && _c !== void 0 ? _c : (_d = options.priorityFilter) === null || _d === void 0 ? void 0 : _d.minimumPriority,
-            maximumPriority: (_e = options.maximumPriority) !== null && _e !== void 0 ? _e : (_f = options.priorityFilter) === null || _f === void 0 ? void 0 : _f.maximumPriority,
+            minimumPriority: (_b = options.minimumPriority) !== null && _b !== void 0 ? _b : (_c = options.priorityFilter) === null || _c === void 0 ? void 0 : _c.minimumPriority,
+            maximumPriority: (_d = options.maximumPriority) !== null && _d !== void 0 ? _d : (_e = options.priorityFilter) === null || _e === void 0 ? void 0 : _e.maximumPriority,
         });
         return {
             ...options,
-            testBefore,
-            testCommand: normalizedTestCommand || (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND),
-            priority: (_g = priorityFilter.minimumPriority) !== null && _g !== void 0 ? _g : 0,
+            projectPath: (_h = (_g = (_f = options.workspace) === null || _f === void 0 ? void 0 : _f.projectPath) !== null && _g !== void 0 ? _g : options.projectPath) !== null && _h !== void 0 ? _h : process.cwd(),
+            checkBefore,
+            checkCommand: resolveCoderCheckCommand((_j = options.checkCommand) === null || _j === void 0 ? void 0 : _j.trim(), checkBefore),
+            priority: (_k = priorityFilter.minimumPriority) !== null && _k !== void 0 ? _k : 0,
             minimumPriority: priorityFilter.minimumPriority,
             maximumPriority: priorityFilter.maximumPriority,
             priorityFilter,
@@ -85742,63 +86586,63 @@
     /**
      * Runs the optional pre-coding verification and, when requested, its one repair prompt.
      */
-    async function runTestBeforeIfNeeded(options) {
-        var _a, _b, _c, _d, _e;
+    async function runCheckBeforeIfNeeded(options) {
+        var _a, _b;
         const { options: runOptions, runner, runnerMetadata, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, hasWaitedForStart, isContinuingInterruptedPrompt, } = options;
-        if (runOptions.testBefore === 'no') {
+        if (runOptions.checkBefore === 'no') {
             return hasWaitedForStart;
         }
-        if (!runOptions.testCommand) {
+        if (!runOptions.checkCommand) {
             throw new NotAllowed(_spaceTrim.spaceTrim(`
-                ${'`--test-before ' + runOptions.testBefore + '`'} requires a verification command.
+                ${'`--check-before ' + runOptions.checkBefore + '`'} requires a verification command.
 
-                Pass one with ${'`--test <test-command>`'} or use the default ${'`npm test`'} command by providing the mode through the CLI.
+                Pass one with ${'`--check <check-command>`'} or use the default ${'`npm run check`'} command.
             `));
         }
         if (isCleanWorkingTreeRequired(runOptions.gitChanges, isContinuingInterruptedPrompt)) {
             await waitForRequestedPause({
-                checkpointLabel: 'checking the git working tree before testing',
+                checkpointLabel: 'checking the git working tree before checking',
                 phase: 'loading',
-                statusMessage: 'Checking the working tree before testing...',
+                statusMessage: 'Checking the working tree before checking...',
             });
-            await ensureWorkingTreeClean((_a = runOptions.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot);
+            await ensureWorkingTreeClean((_b = (_a = runOptions.workspace) === null || _a === void 0 ? void 0 : _a.repositoryRoot) !== null && _b !== void 0 ? _b : runOptions.projectPath);
         }
-        const testBeforeCommitScope = await captureTestBeforeCommitScopeIfNeeded(runOptions);
+        const checkBeforeCommitScope = await captureCheckBeforeCommitScopeIfNeeded(runOptions);
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
-        const testBeforeResult = await runTestBefore({
-            testCommand: runOptions.testCommand,
-            projectPath: (_c = (_b = runOptions.workspace) === null || _b === void 0 ? void 0 : _b.projectPath) !== null && _c !== void 0 ? _c : process.cwd(),
+        const checkBeforeResult = await runCheckBefore({
+            checkCommand: runOptions.checkCommand,
+            projectPath: runOptions.projectPath,
             waitForPauseCheckpoint: waitForRequestedPause,
         }).finally(() => {
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         });
-        await commitTestBeforeChangesIfNeeded({
+        await commitCheckBeforeChangesIfNeeded({
             runOptions,
-            testBeforeCommitScope,
+            checkBeforeCommitScope,
             waitForRequestedPause,
         });
-        if (testBeforeResult.isPassed) {
+        if (checkBeforeResult.isPassed) {
             return hasWaitedForStart;
         }
-        const testOutput = limitTestOutput(testBeforeResult.testOutput);
-        if (runOptions.testBefore === 'yes-and-fail') {
+        const checkOutput = limitCheckOutput(checkBeforeResult.checkOutput);
+        if (runOptions.checkBefore === 'yes-and-fail') {
             throw new NotAllowed(_spaceTrim.spaceTrim((block) => `
-                    Pre-coding verification command \`${runOptions.testCommand}\` failed.
+                    Pre-coding check command \`${runOptions.checkCommand}\` failed.
 
                     The coding agent was not started because the project was already failing before the first queued prompt.
 
-                    ### Test results
+                    ### Check results
                     ${'```'}
-                    ${block(testOutput)}
+                    ${block(checkOutput)}
                     ${'```'}
                 `));
         }
-        const repairPrompt = await createTestBeforeRepairPrompt({
-            projectPath: (_e = (_d = runOptions.workspace) === null || _d === void 0 ? void 0 : _d.projectPath) !== null && _e !== void 0 ? _e : process.cwd(),
-            testCommand: runOptions.testCommand,
-            testOutput,
+        const repairPrompt = await createCheckBeforeRepairPrompt({
+            projectPath: runOptions.projectPath,
+            checkCommand: runOptions.checkCommand,
+            checkOutput,
         });
-        const repairPromptLabel = buildPromptLabelForDisplay(repairPrompt.file, repairPrompt.section);
+        const repairPromptLabel = buildPromptLabelForDisplay(repairPrompt.file, repairPrompt.section, runOptions.projectPath);
         const updatedHasWaitedForStart = await waitForPromptConfirmationIfNeeded({
             options: runOptions,
             nextPrompt: repairPrompt,
@@ -85826,36 +86670,36 @@
         return updatedHasWaitedForStart;
     }
     /**
-     * Captures the files present before a `yes-and-fix` pre-coding test, so only changes made by that test can be committed.
+     * Captures the files present before a `yes-and-fix` pre-coding check, so only changes made by that check can be committed.
      */
-    async function captureTestBeforeCommitScopeIfNeeded(runOptions) {
+    async function captureCheckBeforeCommitScopeIfNeeded(runOptions) {
         var _a;
-        if (runOptions.testBefore !== 'yes-and-fix' || runOptions.noCommit) {
+        if (runOptions.checkBefore !== 'yes-and-fix' || runOptions.noCommit) {
             return undefined;
         }
-        return captureCoderCommitScope((_a = runOptions.workspace) !== null && _a !== void 0 ? _a : process.cwd());
+        return captureCoderCommitScope((_a = runOptions.workspace) !== null && _a !== void 0 ? _a : runOptions.projectPath);
     }
     /**
-     * Commits files changed by a `yes-and-fix` pre-coding test before the coder continues to a queued or repair prompt.
+     * Commits files changed by a `yes-and-fix` pre-coding check before the coder continues to a queued or repair prompt.
      */
-    async function commitTestBeforeChangesIfNeeded(options) {
+    async function commitCheckBeforeChangesIfNeeded(options) {
         var _a;
-        const { runOptions, testBeforeCommitScope, waitForRequestedPause } = options;
-        if (!testBeforeCommitScope) {
+        const { runOptions, checkBeforeCommitScope, waitForRequestedPause } = options;
+        if (!checkBeforeCommitScope) {
             return;
         }
-        const relevantPaths = await resolveCoderCommitScopePaths(testBeforeCommitScope);
+        const relevantPaths = await resolveCoderCommitScopePaths(checkBeforeCommitScope);
         if (relevantPaths.length === 0) {
             return;
         }
         await waitForRequestedPause({
-            checkpointLabel: 'committing changes made by pre-coding tests',
+            checkpointLabel: 'committing changes made by pre-coding checks',
             phase: 'verifying',
-            statusMessage: 'Committing changes made by pre-coding tests...',
+            statusMessage: 'Committing changes made by pre-coding checks...',
         });
-        await commitChanges(PRE_CODING_TEST_CHANGES_COMMIT_MESSAGE, {
+        await commitChanges(PRE_CODING_CHECK_CHANGES_COMMIT_MESSAGE, {
             autoPush: runOptions.autoPush,
-            projectPath: (_a = testBeforeCommitScope.repositoryRoot) !== null && _a !== void 0 ? _a : testBeforeCommitScope.projectPath,
+            projectPath: (_a = checkBeforeCommitScope.repositoryRoot) !== null && _a !== void 0 ? _a : checkBeforeCommitScope.projectPath,
             relevantPaths,
         });
     }
@@ -85901,7 +86745,6 @@
      * Runs the dry-run reporting mode and returns whether the main execution should stop.
      */
     async function runDryRunIfRequested(options, agentReferences) {
-        var _a, _b;
         if (!options.dryRun) {
             return false;
         }
@@ -85910,7 +86753,7 @@
             modelName: options.agentName ? resolveRunnerModel(options.agentName, options.model) : options.model,
             agentReferences,
         };
-        const promptFiles = (await loadPromptFiles(path.join((_b = (_a = options.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : process.cwd(), 'prompts'), {
+        const promptFiles = (await loadPromptFiles(path.join(options.projectPath, 'prompts'), {
             isMissingDirectoryAllowed: true,
         })).map((file) => ({
             ...file,
@@ -85919,7 +86762,7 @@
         const stats = summarizePrompts(promptFiles, options.priorityFilter);
         printStats(stats, options.priorityFilter);
         console.info(colors__default["default"].yellow('Following prompts need to be written:'));
-        printPromptsToBeWritten(promptFiles, options.priorityFilter);
+        printPromptsToBeWritten(promptFiles, options.priorityFilter, options.projectPath);
         return true;
     }
     /**
@@ -85934,7 +86777,7 @@
             serverUrl: options.serverUrl,
             priorityFilter: options.priorityFilter,
             limit: options.limit,
-            testCommand: options.testCommand,
+            checkCommand: options.checkCommand,
         });
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Running prompts with ${runnerName}`);
@@ -85957,10 +86800,9 @@
      * Loads prompt files, updates progress displays, and selects the next runnable prompt.
      */
     async function loadPromptQueueSnapshot(options) {
-        var _a, _b;
         const { options: runOptions, isRichUiEnabled, progressDisplay, uiHandle, promptRunnerIdentity, isContinuingInterruptedPrompt, } = options;
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCurrentScriptPath(undefined);
-        const promptFiles = await loadPromptFiles(path.join((_b = (_a = runOptions.workspace) === null || _a === void 0 ? void 0 : _a.projectPath) !== null && _b !== void 0 ? _b : process.cwd(), 'prompts'));
+        const promptFiles = await loadPromptFiles(path.join(runOptions.projectPath, 'prompts'));
         const stats = summarizePrompts(promptFiles, runOptions.priorityFilter);
         progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.update(stats);
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.updateProgress(stats);
@@ -85987,10 +86829,10 @@
         }
         if (stats.toBeWritten > 0) {
             console.info(colors__default["default"].yellow('Following prompts need to be written:'));
-            printPromptsToBeWritten(promptFiles, priorityFilter);
+            printPromptsToBeWritten(promptFiles, priorityFilter, options.projectPath);
             console.info('');
         }
-        printUpcomingTasks(listUpcomingTasks(promptFiles, priorityFilter, promptRunnerIdentity));
+        printUpcomingTasks(listUpcomingTasks(promptFiles, priorityFilter, promptRunnerIdentity, options.projectPath));
         return true;
     }
     /**
@@ -86187,12 +87029,14 @@
         return [
             ...options.promptFiles.map((promptFile) => buildCoderServerPromptFileResponse({
                 promptFile,
+                projectPath: options.projectPath,
                 isFinished: false,
                 priorityFilter: options.priorityFilter,
                 activePrompt,
             })),
             ...options.finishedPromptFiles.map((promptFile) => buildCoderServerPromptFileResponse({
                 promptFile,
+                projectPath: options.projectPath,
                 isFinished: true,
                 priorityFilter: options.priorityFilter,
                 activePrompt,
@@ -86203,13 +87047,15 @@
      * Builds one prompt-file response.
      */
     function buildCoderServerPromptFileResponse(options) {
+        var _a;
         const { promptFile, isFinished, priorityFilter, activePrompt } = options;
         return {
             filePath: promptFile.path,
             fileName: promptFile.name,
-            relativeFilePath: path.relative(process.cwd(), promptFile.path).replace(/\\/gu, '/'),
+            relativeFilePath: path.relative((_a = options.projectPath) !== null && _a !== void 0 ? _a : process.cwd(), promptFile.path).replace(/\\/gu, '/'),
             isFinished,
             sections: promptFile.sections.map((section) => buildCoderServerPromptSectionResponse({
+                projectPath: options.projectPath,
                 promptFile,
                 section,
                 isFinished,
@@ -86224,7 +87070,7 @@
     function buildCoderServerPromptSectionResponse(options) {
         const { promptFile, section, isFinished, priorityFilter, activePrompt } = options;
         const isUnwritten = isPromptToBeWritten(promptFile, section);
-        const isActive = isPromptActive(promptFile, section, activePrompt);
+        const isActive = isPromptActive(promptFile, section, activePrompt, options.projectPath);
         const column = getPromptColumn({
             section,
             isFinished,
@@ -86239,7 +87085,7 @@
             priority: section.priority,
             summary: buildPromptSummary(promptFile, section),
             content: buildCodexPrompt(promptFile, section),
-            label: buildPromptLabelForDisplay(promptFile, section),
+            label: buildPromptLabelForDisplay(promptFile, section, options.projectPath),
             tags: buildPromptTags({
                 section,
                 isUnwritten,
@@ -86316,11 +87162,11 @@
     /**
      * Checks whether a parsed section is the prompt currently handled by the active agent.
      */
-    function isPromptActive(promptFile, section, activePrompt) {
+    function isPromptActive(promptFile, section, activePrompt, projectPath) {
         if (!activePrompt || (section.status !== 'todo' && section.status !== 'in-progress')) {
             return false;
         }
-        return buildPromptLabelForDisplay(promptFile, section) === activePrompt.label;
+        return buildPromptLabelForDisplay(promptFile, section, projectPath) === activePrompt.label;
     }
     // Note: [🟡] Code for CLI command [coder server](scripts/run-codex-prompts/server/buildCoderServerPromptResponse.ts) should never be published outside of `@promptbook/cli`
 
@@ -87241,6 +88087,7 @@
         const promptFiles = await loadPromptFilesSafely(promptsDir);
         const finishedPromptFiles = await loadPromptFilesSafely(path.join(promptsDir, FINISHED_PROMPTS_DIRECTORY_NAME));
         return buildCoderServerPromptFileResponses({
+            projectPath: path.dirname(promptsDir),
             promptFiles,
             finishedPromptFiles,
             priorityFilter,
@@ -87327,18 +88174,20 @@
      * @private internal function of `ptbk coder server`
      */
     async function runCodexPromptsServer(options) {
-        var _a, _b, _c, _d;
-        const { port, ...runOptions } = options;
-        if (runOptions.dryRun) {
-            await runCodexPrompts(runOptions);
+        var _a, _b, _c, _d, _e;
+        const { port, ...providedOptions } = options;
+        if (providedOptions.dryRun) {
+            await runCodexPrompts(providedOptions);
             return;
         }
+        const workspace = (_a = providedOptions.workspace) !== null && _a !== void 0 ? _a : await $resolveWorkspaceRepository(providedOptions.projectPath);
+        const runOptions = { ...providedOptions, workspace, projectPath: workspace.projectPath };
         const serverUrl = `http://localhost:${port}`;
         const uiState = new CoderRunUiState(moment__default["default"]());
         const priorityFilter = normalizePriorityFilter({
             priority: runOptions.priority,
-            minimumPriority: (_a = runOptions.minimumPriority) !== null && _a !== void 0 ? _a : (_b = runOptions.priorityFilter) === null || _b === void 0 ? void 0 : _b.minimumPriority,
-            maximumPriority: (_c = runOptions.maximumPriority) !== null && _c !== void 0 ? _c : (_d = runOptions.priorityFilter) === null || _d === void 0 ? void 0 : _d.maximumPriority,
+            minimumPriority: (_b = runOptions.minimumPriority) !== null && _b !== void 0 ? _b : (_c = runOptions.priorityFilter) === null || _c === void 0 ? void 0 : _c.minimumPriority,
+            maximumPriority: (_d = runOptions.maximumPriority) !== null && _d !== void 0 ? _d : (_e = runOptions.priorityFilter) === null || _e === void 0 ? void 0 : _e.maximumPriority,
         });
         const serverHandle = startCoderHttpServer({
             port,