@promptbook/cli 0.114.0-47 → 0.114.0-49

package/esm/index.es.js

@@ -1,13 +1,13 @@
 import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
-import { writeFile, stat, readdir, mkdir, readFile, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, statfs, access, constants as constants$1, watch, rmdir, mkdtemp } from 'fs/promises';
-import { join, delimiter, relative, basename, resolve, dirname, isAbsolute, extname } from 'path';
+import { realpath, stat, access, writeFile, readdir, mkdir, readFile, rm, cp, lstat, symlink, rename, unlink, appendFile, copyFile, statfs, constants as constants$1, watch, rmdir, mkdtemp } from 'fs/promises';
+import { resolve, join, delimiter, relative, basename, dirname, isAbsolute, extname } from 'path';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'crypto';
 import { spawn, spawnSync, execFile } from 'child_process';
 import moment from 'moment';
 import * as fs from 'fs';
-import { createWriteStream, mkdirSync, writeFileSync, constants, statSync, readFileSync, existsSync, realpathSync, lstatSync, linkSync, unlinkSync, renameSync, openSync, fsyncSync, closeSync, promises } from 'fs';
+import { constants, createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, realpathSync, lstatSync, linkSync, unlinkSync, renameSync, openSync, fsyncSync, closeSync, promises } from 'fs';
 import * as dotenv from 'dotenv';
 import * as readline from 'readline';
 import { createInterface, emitKeypressEvents, cursorTo, clearLine } from 'readline';
@@ -51,7 +51,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-47';
+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
@@ -1746,6 +1746,56 @@ function $reportMissingCliSubcommand(command) {
     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: 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 = resolve(projectDirectory);
+    try {
+        const projectPath = await realpath(requestedPath);
+        if (!(await stat(projectPath)).isDirectory()) {
+            throw new EnvironmentMismatchError(spaceTrim(`Project path \`${requestedPath}\` is not a directory.`));
+        }
+        await access(projectPath, constants.R_OK | 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`.
@@ -2105,15 +2155,18 @@ function $initializeAgentChatCommand(program) {
     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,
         });
     }));
@@ -2139,8 +2192,11 @@ function $initializeAgentExecCommand(program) {
     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; });
@@ -2148,7 +2204,7 @@ function $initializeAgentExecCommand(program) {
             agentPath: resolveRequiredAgentPath(options),
             context: options.context,
             message: resolveRequiredAgentMessage(options),
-            currentWorkingDirectory: process.cwd(),
+            currentWorkingDirectory: projectPath,
             ...runnerOptions,
         });
     }));
@@ -2452,8 +2508,11 @@ function $initializeAgentInitCommand(program) {
             - ${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);
     }));
 }
@@ -2508,15 +2567,21 @@ function $initializeAgentRunnerCommand(program, options) {
             `));
     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);
                 },
@@ -24750,7 +24815,7 @@ async function appendScriptExecutionLogFinish({ scriptPath, logPath, status, det
  * 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';
 }
 
 /**
@@ -24953,28 +25018,44 @@ async function runBashScriptWithOutput(options) {
         /**
          * 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$1(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$1(output));
+                });
                 return;
             }
-            const failure = new Error(spaceTrim$1(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$1((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$1((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$1((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. */
@@ -26430,6 +26511,11 @@ class GeminiRunner {
     }
 }
 
+/** 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.
  */
@@ -26439,7 +26525,7 @@ function buildGitHubCopilotScript(options) {
     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
@@ -26880,7 +26966,7 @@ function buildCodexScript(options) {
         ...(options.isMachineReadableProgressEnabled ? ['    --json \\'] : []),
         '    --local-provider none \\',
         `    --sandbox ${options.sandbox} \\`,
-        `    -C ${projectPath} \\`,
+        `    -C ${quoteBashArgument(projectPath)} \\`,
         '    --skip-git-repo-check \\',
         `    <<'${delimiter}'`,
         '',
@@ -29216,7 +29302,7 @@ function buildSessionRows(options, bodyWidth, pausePresentation) {
         ...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 [
         {
@@ -31710,7 +31796,7 @@ function createCoderRunOptionsForAgent(options) {
     return {
         dryRun: false,
         context: undefined,
-        testCommand: undefined,
+        checkCommand: undefined,
         preserveLogs: false,
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
@@ -32812,40 +32898,207 @@ function createCoderRunStepTracker(onStepStarted) {
 }
 
 /**
- * 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$1(`
+            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 readFile(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$1(`
+    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.
  */
@@ -32853,12 +33106,18 @@ const SHELL_SCRIPT_EXTENSION = '.sh';
 /**
  * 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,
@@ -32868,10 +33127,10 @@ async function runPromptWithTestFeedback(options) {
         });
         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,
@@ -32879,42 +33138,44 @@ async function runPromptWithTestFeedback(options) {
             kind: attemptCount === 1 ? 'implementation' : 'fixing',
             stepTracker,
         });
-        await waitForVerificationPauseCheckpoint(options.waitForPauseCheckpoint, normalizedTestCommand, attemptCount);
-        console.info(colors.gray(`Running verification command after attempt #${attemptCount}: ${normalizedTestCommand}`));
-        const failedVerification = await runVerificationStep({
-            runPromptTestCommandExecutor,
-            testCommand: normalizedTestCommand,
+        await waitForCheckPauseCheckpoint(options.waitForPauseCheckpoint, normalizedCheckCommand, attemptCount);
+        console.info(colors.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.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.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.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.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({
@@ -32924,33 +33185,41 @@ async function runRunnerPromptStep(options) {
         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 });
     }
 }
 /**
@@ -32964,13 +33233,13 @@ async function waitForPromptAttemptPauseCheckpoint(waitForPauseCheckpoint, runne
     }));
 }
 /**
- * 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}`,
     }));
 }
 /**
@@ -32986,51 +33255,53 @@ function buildPromptAttemptStatusMessage(runnerName, attemptCount) {
     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`;
 }
 
 /**
@@ -41930,16 +42201,16 @@ function validateAgentRunOptions(options) {
  * 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({
@@ -41951,7 +42222,7 @@ async function tickAgentMessages(options, tickOptions = {}) {
         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);
@@ -41970,24 +42241,24 @@ async function tickAgentMessages(options, tickOptions = {}) {
             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,
                 ]);
@@ -42071,7 +42342,7 @@ async function runQueuedAgentMessage(options) {
     try {
         try {
             promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => {
-                const runResult = await runPromptWithTestFeedback({
+                const runResult = await runPromptWithCheckFeedback({
                     runner,
                     prompt,
                     scriptPath,
@@ -42498,12 +42769,12 @@ const MULTI_AGENT_QUEUE_POLL_INTERVAL_MS = 2000;
  * 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();
@@ -42527,7 +42798,7 @@ async function runMultipleAgentMessages(options, controls = {}) {
                     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.green('Watching direct child agent repositories for queued messages.'));
                 }
@@ -43786,6 +44057,7 @@ const WORKSPACE_REPOSITORY_DESCRIPTION = spaceTrim$1(`
  * @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`);
@@ -43887,17 +44159,7 @@ const EXECUTE_FILE = promisify(execFile);
  * @private shared workspace discovery for CLI commands
  */
 async function $resolveWorkspaceRepository(projectDirectory = process.cwd()) {
-    const requestedPath = resolve(projectDirectory);
-    let projectPath;
-    try {
-        projectPath = await realpath(requestedPath);
-        if (!(await stat(projectPath)).isDirectory()) {
-            throw new EnvironmentMismatchError(`The project path \`${requestedPath}\` is not a directory.`);
-        }
-    }
-    catch (error) {
-        throw new EnvironmentMismatchError(spaceTrim$1(`Cannot access project directory \`${requestedPath}\`. Check that it exists and is accessible.\n\n${describeWorkspaceError(error)}`));
-    }
+    const projectPath = await resolveProjectDirectory(projectDirectory);
     return $inspectWorkspaceRepository(projectPath);
 }
 /**
@@ -44009,7 +44271,7 @@ async function $inspectWorkspaceRepository(projectPath) {
         // 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 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' };
@@ -44337,10 +44599,15 @@ function $initializeCoderAddCommand(program) {
     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`
@@ -44563,7 +44830,9 @@ function $initializeCoderFindFreshEmojiTagCommand(program) {
         `));
     addWorkspaceRepositoryOptions(command);
     command.action(handleActionErrors(async (cliOptions) => {
+        const projectOptions = normalizeProjectCliOptions(cliOptions);
         const workspace = await $preflightWorkspaceRepository({
+            ...projectOptions,
             policy: 'read-only',
             isAskingQuestionsEnabled: cliOptions.questions,
         });
@@ -44804,8 +45073,10 @@ function $initializeCoderFindRefactorCandidatesCommand(program) {
     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,
         });
@@ -44839,8 +45110,10 @@ function $initializeCoderFindUnwrittenCommand(program) {
     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,
         });
@@ -44994,10 +45267,12 @@ function $initializeCoderGenerateBoilerplatesCommand(program) {
     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,
         });
@@ -46036,16 +46311,16 @@ const CODER_REFERENCED_ARTIFACT_DEFINITIONS = [
     ...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;
         }
@@ -46664,7 +46939,7 @@ async function ensureCoderGitignoreRules(projectPath, rules) {
 /**
  * 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`.
  *
@@ -46684,14 +46959,13 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS = [
     {
         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],
     },
@@ -46704,8 +46978,8 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS = [
     {
         // 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: [],
     },
 ];
@@ -46770,12 +47044,13 @@ const DEFAULT_JSON_FILE_NEWLINE = '\n';
 /**
  * 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 mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
     }
@@ -46785,7 +47060,7 @@ async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldP
     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
@@ -46794,7 +47069,12 @@ async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldP
         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 };
     }
@@ -46883,6 +47163,301 @@ function isPlainObject$1(value) {
 }
 // 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 readdir(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 readFile(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.
  */
@@ -46890,17 +47465,30 @@ const PACKAGE_JSON_FILE_PATH = 'package.json';
 /**
  * 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`
 
@@ -47194,9 +47782,9 @@ const PROMPTS_README_TEMPLATE = spaceTrim$1(`
 
     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.
@@ -47247,9 +47835,9 @@ const PROMPTS_README_TEMPLATE = spaceTrim$1(`
     | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | \`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.                                                                                                                                                                                                                                    |
@@ -47261,11 +47849,18 @@ const PROMPTS_README_TEMPLATE = spaceTrim$1(`
     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
 
@@ -47277,9 +47872,20 @@ const PROMPTS_README_TEMPLATE = spaceTrim$1(`
     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.
@@ -47350,7 +47956,7 @@ async function initializeCoderProjectConfiguration(projectPath, onStepCompleted)
     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),
@@ -47371,6 +47977,9 @@ async function initializeCoderProjectConfiguration(projectPath, onStepCompleted)
         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`
@@ -47382,9 +47991,11 @@ async function initializeCoderProjectConfiguration(projectPath, onStepCompleted)
  */
 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.yellow('Promptbook coder initialization has unresolved artifacts.')
+        ? colors.yellow('Promptbook coder configuration setup: additional setup is required.')
         : colors.green('Promptbook coder configuration setup:'));
     if (workspace)
         console.info(colors.gray(`✔ Git repository: ${workspace.repositoryStatus} (${workspace.repositoryRoot})`));
@@ -47413,6 +48024,9 @@ function printInitializationSummary(summary, workspace) {
     else {
         printInitializationNote('Required coder env variables are already present.', colors.gray);
     }
+    console.info((summary.isCheckConfigured ? colors.cyan : colors.yellow)(summary.checkScriptSummary));
+    for (const instruction of summary.migrationInstructions)
+        console.info(colors.yellow(`! ${instruction}`));
 }
 /**
  * Formats one initialization status into a human-readable label.
@@ -47494,7 +48108,7 @@ function $initializeCoderInitCommand(program) {
                 - 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
@@ -47512,9 +48126,14 @@ function $initializeCoderInitCommand(program) {
     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 {
@@ -47628,6 +48247,11 @@ const CODER_DEFAULT_AGENT_BOOK_PATHS = {
     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
 
 /**
@@ -47647,6 +48271,14 @@ function addCoderAgentOption(command, defaultRole) {
         : '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
 
@@ -47675,9 +48307,13 @@ function $initializeCoderListCommand(program) {
     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);
@@ -47818,12 +48454,17 @@ function $initializeCoderPingCommand(program) {
         `));
     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 = {
@@ -47855,10 +48496,10 @@ function $initializeCoderPingCommand(program) {
  */
 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.
@@ -47867,11 +48508,12 @@ function $initializeCoderPlanCommand(program) {
     `));
     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; });
@@ -47882,12 +48524,18 @@ function $initializeCoderPlanCommand(program) {
         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;
@@ -47900,6 +48548,8 @@ function $initializeCoderPlanCommand(program) {
                 ...options,
                 projectPath,
                 agent: cliOptions.agent,
+                context: cliOptions.context,
+                projectContext,
                 template: cliOptions.template,
                 preexistingChangedPaths: gitSync.isCommitEnabled
                     ? new Set(Array.from(commitScope.snapshotBeforeOperation.changedFileHashes.keys(), (path) => relative(projectPath, join(workspace.repositoryRoot, path)).replace(/\\/gu, '/')))
@@ -48089,30 +48739,20 @@ async function $assertSufficientFreeDiskSpace(inspectedPath) {
 }
 // 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$1(`
-                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$1(`
+                Invalid ${'`--check-before`'} mode: \`${String(options.checkBefore)}\`.
 
                 Use one of: \`no\`, \`yes-and-fail\`, \`yes-and-fix\`.
             `));
@@ -48150,9 +48790,9 @@ function validateCoderRunOptions(options) {
                 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$1(`
-                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.
             `));
@@ -48199,9 +48839,9 @@ const NODE_MODULES_DIRECTORY_NAME = 'node_modules';
  *
  * @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];
@@ -48209,8 +48849,8 @@ async function $resolvePromptbookCliInstallations() {
 /**
  * Finds the closest ancestor `package.json` which directly declares a Promptbook CLI package.
  */
-async function $resolveLocalPromptbookCliInstallations() {
-    let candidateProjectPath = resolve(process.cwd());
+async function $resolveLocalPromptbookCliInstallations(projectPath) {
+    let candidateProjectPath = resolve(projectPath);
     let isFileSystemRootReached = false;
     while (!isFileSystemRootReached) {
         const projectPackageJson = await $readJsonObject(join(candidateProjectPath, PACKAGE_JSON_FILENAME));
@@ -48366,8 +49006,8 @@ function isDefined(value) {
  *
  * @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 [];
     }
@@ -48422,10 +49062,10 @@ function buildPromptbookCliInstallCommand(installation) {
  * @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.cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));
     try {
         await $execCommand({
@@ -48495,7 +49135,7 @@ function formatPromptbookCliInstallationLocation(installationLocation) {
  * @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;
@@ -48504,7 +49144,7 @@ async function $ensurePromptbookCliInstallations(questionsOptions) {
         // 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);
@@ -48518,7 +49158,7 @@ async function $ensurePromptbookCliInstallations(questionsOptions) {
     }
     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);
@@ -48563,6 +49203,89 @@ function reportManualPromptbookCliUpdateCommands(outdatedStatuses) {
 }
 // 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 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 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$1(`
+            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.
  *
@@ -48609,20 +49332,16 @@ function $initializeCoderRunCommand(program) {
             - 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 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$1(`
@@ -48651,9 +49370,9 @@ function $initializeCoderRunCommand(program) {
     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,
         });
@@ -48682,8 +49401,8 @@ function $initializeCoderRunCommand(program) {
             model: runnerOptions.model,
             agent,
             context,
-            testCommand,
-            testBefore,
+            checkCommand,
+            checkBefore,
             preserveLogs,
             isIsolated,
             noUi: runnerOptions.noUi,
@@ -48702,16 +49421,20 @@ function $initializeCoderRunCommand(program) {
         };
         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);
@@ -48720,8 +49443,7 @@ function $initializeCoderRunCommand(program) {
         // 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);
@@ -48731,23 +49453,6 @@ function $initializeCoderRunCommand(program) {
         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
 
@@ -48793,9 +49498,8 @@ function $initializeCoderServerCommand(program) {
     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);
@@ -48817,9 +49521,10 @@ function $initializeCoderServerCommand(program) {
     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,
         });
@@ -48843,7 +49548,7 @@ function $initializeCoderServerCommand(program) {
             model: runnerOptions.model,
             agent,
             context,
-            testCommand,
+            checkCommand,
             preserveLogs,
             noUi: runnerOptions.noUi,
             thinkingLevel: runnerOptions.thinkingLevel,
@@ -48860,13 +49565,17 @@ function $initializeCoderServerCommand(program) {
         };
         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);
@@ -48875,7 +49584,7 @@ function $initializeCoderServerCommand(program) {
         // 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);
@@ -48901,23 +49610,6 @@ function parseCoderServerPort(rawPort) {
     }
     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
 
@@ -48995,9 +49687,11 @@ function $initializeCoderVerifyCommand(program) {
     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,
         });
@@ -49033,7 +49727,7 @@ function collectStringOption(value, previousValues) {
  * 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
@@ -49054,7 +49748,7 @@ function $initializeCoderCommand(program) {
             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
@@ -72175,12 +72869,21 @@ async function resolveInlineOrFileText(options) {
     }
     const textPath = resolve(options.currentWorkingDirectory, normalizedTextReference);
     const textPathStats = await 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()) {
@@ -72190,7 +72893,55 @@ async function resolveInlineOrFileText(options) {
                 Pass a file path or inline text in \`${options.optionName}\`.
             `));
     }
-    return readFile(textPath, 'utf-8');
+    return 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 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 = join(currentWorkingDirectory, AGENTS_FILE_PATH);
+        try {
+            return await 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 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,
+    });
 }
 
 /**
@@ -72269,11 +73020,7 @@ function createAgentChatWorkspacePath(options) {
         .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);
 }
 /**
@@ -72328,7 +73075,7 @@ function createPromptRunnerOptions(options) {
     return {
         dryRun: false,
         context: undefined,
-        testCommand: undefined,
+        checkCommand: undefined,
         preserveLogs: false,
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
@@ -72394,12 +73141,7 @@ function normalizeRelativePath(relativePath) {
  */
 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,
@@ -72462,12 +73204,7 @@ async function runAgentExec(options) {
         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,
@@ -72553,13 +73290,13 @@ const AGENT_IDLE_AUTO_PULL_INTERVAL_MS = 30000;
  * 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({
@@ -72576,7 +73313,7 @@ async function runAgentMessages(options, controls = {}) {
                 }
             }
             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;
@@ -78429,8 +79166,8 @@ async function loadPromptFiles(promptsDir, options = {}) {
 /**
  * Builds a display label using the prompt line number for easier navigation.
  */
-function buildPromptLabelForDisplay(file, section) {
-    return `${relative(process.cwd(), file.path).replace(/\\/g, '/')}#${section.startLine + 1}`;
+function buildPromptLabelForDisplay(file, section, projectPath = process.cwd()) {
+    return `${relative(projectPath, file.path).replace(/\\/g, '/')}#${section.startLine + 1}`;
 }
 
 /**
@@ -78445,11 +79182,11 @@ function buildPromptSummary(file, section) {
 /**
  * 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}`);
     }
@@ -78519,7 +79256,7 @@ async function findUnwrittenPrompts(options = {}) {
     }
     else {
         console.info(colors.yellow(`Found ${unwrittenPrompts.length} prompt(s) that need to be written:`));
-        printPromptsToBeWritten(promptFiles, priorityFilter);
+        printPromptsToBeWritten(promptFiles, priorityFilter, options.projectPath);
     }
     return unwrittenPrompts.length;
 }
@@ -79363,9 +80100,9 @@ function listRunnablePrompts(files, priorityFilter = {}, promptRunnerIdentity) {
 /**
  * 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,
     }));
@@ -79420,7 +80157,7 @@ async function listCoderPrompts(options = {}) {
     const promptFiles = await loadPromptFiles(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;
 }
@@ -79800,6 +80537,24 @@ var createPlanningTerminal$1 = /*#__PURE__*/Object.freeze({
     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. */
@@ -80018,6 +80773,19 @@ class CoderTeamRuntime {
 }
 // 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 || !isAbsolute(reference.trim()))
+        return reference;
+    const relativePath = relative(originalProjectPath, reference.trim());
+    if (isAbsolute(relativePath) || relativePath === '..' || /^\.\.[/\\]/u.test(relativePath))
+        return reference;
+    return 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. */
@@ -80204,7 +80972,7 @@ function buildBridgeClient(url, token) {
  * 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,
@@ -80220,8 +80988,11 @@ function createCoderTeamPromptRunner(runner, agentBookReference) {
             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, resolve(options.projectPath, relative(originalProjectPath, originalRepositoryRoot)))
+                    : agentBookReference;
+                const agent = await resolveCoderAgent(reference, options.projectPath, {
+                    defaultRole: DEFAULT_CODER_AGENT_ROLE,
                     isInitializationAllowed: false,
                     signal: controller.signal,
                 });
@@ -81102,11 +81873,12 @@ function writeDurableFile(path, content) {
  * @private internal utility of `coder plan`
  */
 async function runPlanningSession(options, io, harness = runPlanningHarness) {
-    var _a, _b;
+    var _a, _b, _c;
     const projectPath = await 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,
     });
@@ -81114,9 +81886,9 @@ async function runPlanningSession(options, io, harness = runPlanningHarness) {
         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 : (existsSync(join(projectPath, COMMON_PROMPT_TEMPLATE_FILE_PATH))
+    const templateOption = (_b = options.template) !== null && _b !== void 0 ? _b : (existsSync(join(projectPath, COMMON_PROMPT_TEMPLATE_FILE_PATH))
         ? COMMON_PROMPT_TEMPLATE_FILE_PATH
         : undefined);
     const template = await resolveCoderPromptTemplate({ projectPath, templateOption });
@@ -81160,7 +81932,10 @@ async function runPlanningSession(options, io, harness = runPlanningHarness) {
             },
             { role: 'context', content: await readPlanningContext(projectPath, { kind: 'list', path: '.' }) },
         ];
-        for (const path of ['README.md', 'AGENTS.md']) {
+        if (projectContext.context !== undefined) {
+            history.push({ role: 'context', content: projectContext.context });
+        }
+        for (const path of ['README.md']) {
             if (existsSync(join(projectPath, path))) {
                 history.push({
                     role: 'context',
@@ -81177,7 +81952,7 @@ async function runPlanningSession(options, io, harness = runPlanningHarness) {
         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)
@@ -81314,7 +82089,7 @@ const DEFAULT_WAIT_AFTER_ERROR_MS = 10 * 60 * 1000;
 /**
  * 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.
  */
@@ -81324,8 +82099,8 @@ const KNOWN_OPTION_FLAGS = new Set([
     '--model',
     '--agent',
     '--context',
-    '--test',
-    '--test-before',
+    '--check',
+    '--check-before',
     '--preserve-logs',
     '--isolate',
     '--no-ui',
@@ -81351,6 +82126,15 @@ const KNOWN_OPTION_FLAGS = new Set([
  * 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');
@@ -81366,10 +82150,10 @@ function parseRunOptions(args) {
         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');
@@ -81407,8 +82191,8 @@ function parseRunOptions(args) {
     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(', ')}.`);
@@ -81443,8 +82227,8 @@ function parseRunOptions(args) {
         model,
         agent,
         context,
-        testCommand,
-        testBefore,
+        checkCommand: resolveCoderCheckCommand(checkCommand, checkBefore),
+        checkBefore,
         thinkingLevel,
         priority: minimumPriority !== null && minimumPriority !== void 0 ? minimumPriority : 0,
         minimumPriority,
@@ -81456,15 +82240,15 @@ function parseRunOptions(args) {
 /**
  * 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;
 }
@@ -81525,8 +82309,14 @@ function readVariadicOptionValue(args, flag) {
         }
         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.
@@ -81968,18 +82758,6 @@ async function sleepWithCountdown(options) {
     });
 }
 
-/**
- * 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.
  *
@@ -83574,7 +84352,7 @@ function buildScriptPath(file, section, projectPath = process.cwd()) {
  */
 const CODER_RUN_STEP_LABELS = {
     implementation: 'Implementation',
-    testing: 'Testing',
+    checking: 'Checking',
     fixing: 'Fixing',
 };
 /**
@@ -83585,16 +84363,16 @@ const IN_PROGRESS_STEP_SUFFIX = 'in progress';
  * 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('; ');
 }
@@ -83602,7 +84380,7 @@ function formatCoderRunSteps(steps, inProgressStepKind) {
  * 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.duration(step.durationMs).humanize();
     const priceString = step.usage === null ? undefined : formatUsagePrice(step.usage);
     if (priceString === undefined) {
@@ -83610,6 +84388,10 @@ function formatCoderRunStep(step) {
     }
     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.
@@ -83950,13 +84732,13 @@ function buildPromptRunTraceSummarySection(options) {
         `-   **Runner:** ${runnerSignature}${loginMethodSuffix}`,
         `-   **Attempts:** ${options.attemptCount}`,
         ...buildPromptRunTraceStepsLines(outcome),
-        ...buildPromptRunTraceTestCommandLines(options.testCommand),
+        ...buildPromptRunTraceCheckCommandLines(options.checkCommand),
         `-   **Started:** ${options.startedDate.toISOString()}`,
         `-   **Finished:** ${options.finishedDate.toISOString()}`,
         `-   **Duration:** ${moment.duration(options.finishedDate.diff(options.startedDate)).humanize()}`,
     ];
     return spaceTrim$1((block) => `
-            # Run trace of \`${buildPromptLabelForDisplay(file, section)}\`
+            # Run trace of \`${buildPromptLabelForDisplay(file, section, options.projectPath)}\`
 
             ${block(detailLines.join('\n'))}
         `);
@@ -83989,11 +84771,11 @@ function buildPromptRunTraceStepsLines(outcome) {
 /**
  * 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.
@@ -84080,9 +84862,9 @@ const MAX_RETRY_ATTEMPTS_AFTER_ERROR = 3;
  *
  * @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
@@ -84099,8 +84881,7 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
               `)
         : 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 });
@@ -84119,13 +84900,13 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
         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) => {
@@ -84165,7 +84946,9 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
                 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({
@@ -84407,13 +85190,15 @@ async function finalizeFailedPromptRound(options) {
  * 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(),
@@ -85011,12 +85796,12 @@ async function abortSquashMerge(worktree) {
  * @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,
@@ -85024,16 +85809,44 @@ async function runIsolatedPromptRound(options) {
     });
     announceIsolatedRoundStart(worktree, promptLabel, isRichUiEnabled);
     try {
-        const isolatedProjectPath = join(worktree.worktreePath, relative((_e = originalProjectCommitScope.repositoryRoot) !== null && _e !== void 0 ? _e : projectPath, projectPath));
+        const isolatedProjectPath = join(worktree.worktreePath, 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: join(isolatedWorkspace.projectPath, 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
@@ -85054,7 +85867,7 @@ async function runIsolatedPromptRound(options) {
     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}\``);
@@ -85063,9 +85876,23 @@ async function runIsolatedPromptRound(options) {
  * 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 = join(worktree.worktreePath, relative(repositoryRoot, tracePath));
+    // The failed merge did not bring back the worktree's trace. Preserve it beside the failure report.
+    await mkdir(dirname(tracePath), { recursive: true });
+    let isTraceCopied = false;
+    try {
+        await 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({
@@ -85077,13 +85904,11 @@ async function recordIsolationMergeFailure(options, worktree, failureDetails) {
     });
     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);
@@ -85124,8 +85949,8 @@ function findNextTodoPrompt(files, priorityFilter = {}, promptRunnerIdentity) {
 /**
  * Builds a label that identifies the prompt section by index.
  */
-function buildPromptLabel(file, section) {
-    return `${relative(process.cwd(), file.path).replace(/\\/g, '/')}#${section.index + 1}`;
+function buildPromptLabel(file, section, projectPath = process.cwd()) {
+    return `${relative(projectPath, file.path).replace(/\\/g, '/')}#${section.index + 1}`;
 }
 
 /**
@@ -85353,18 +86178,20 @@ function startCoderRunUiSubscriptionUsageRefresh(options) {
 }
 
 /**
- * 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({
@@ -85377,50 +86204,56 @@ async function createTestBeforeRepairPrompt(options) {
     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.gray(initialTestStatusMessage));
+    (_d = options.signal) === null || _d === void 0 ? void 0 : _d.throwIfAborted();
+    console.info(colors.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.green('Pre-coding tests passed.'));
-        return { isPassed: true, testOutput };
+        (_e = options.signal) === null || _e === void 0 ? void 0 : _e.throwIfAborted();
+        console.info(colors.green('Pre-coding checks passed.'));
+        return { isPassed: true, checkOutput };
     }
     catch (error) {
-        const testOutput = formatUnknownErrorMessage(error);
-        console.error(colors.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.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.
  *
@@ -85429,10 +86262,15 @@ const PRE_CODING_TEST_CHANGES_COMMIT_MESSAGE = 'test: Apply changes made by pre-
  * @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();
     const { isRichUiEnabled, progressDisplay, uiHandle } = createRunDisplays(options, runStartDate);
@@ -85450,20 +86288,25 @@ async function runCodexPrompts(providedOptions) {
     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 = {
@@ -85494,7 +86337,7 @@ async function runCodexPrompts(providedOptions) {
         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)) {
@@ -85509,11 +86352,11 @@ async function runCodexPrompts(providedOptions) {
                 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,
@@ -85524,8 +86367,8 @@ async function runCodexPrompts(providedOptions) {
                     isContinuingInterruptedPrompt,
                 });
             }
-            if (!hasRunTestBefore) {
-                hasWaitedForStart = await runTestBeforeIfNeeded({
+            if (!hasRunCheckBefore) {
+                hasWaitedForStart = await runCheckBeforeIfNeeded({
                     options,
                     runner,
                     runnerMetadata,
@@ -85538,7 +86381,7 @@ async function runCodexPrompts(providedOptions) {
                     hasWaitedForStart,
                     isContinuingInterruptedPrompt,
                 });
-                hasRunTestBefore = true;
+                hasRunCheckBefore = true;
             }
             await waitForRequestedPause({
                 checkpointLabel: 'loading prompts',
@@ -85554,6 +86397,7 @@ async function runCodexPrompts(providedOptions) {
                 isContinuingInterruptedPrompt,
             });
             hasShownUpcomingTasks || (hasShownUpcomingTasks = showUpcomingTasksOnce({
+                projectPath,
                 hasShownUpcomingTasks,
                 promptFiles: promptQueueSnapshot.promptFiles,
                 stats: promptQueueSnapshot.stats,
@@ -85584,7 +86428,7 @@ async function runCodexPrompts(providedOptions) {
                 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({
@@ -85619,7 +86463,7 @@ async function runCodexPrompts(providedOptions) {
                     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
@@ -85681,7 +86525,7 @@ function isCleanWorkingTreeRequired(gitChanges, isContinuingInterruptedPrompt) {
  * 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;
@@ -85689,7 +86533,7 @@ async function pullLatestChangesIfEnabled(options) {
     if (!isRichUiEnabled) {
         console.info(colors.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.
@@ -85714,19 +86558,19 @@ function createRunDisplays(options, runStartDate) {
  * 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,
@@ -85735,63 +86579,63 @@ function normalizeRunOptions(options) {
 /**
  * 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$1(`
-                ${'`--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$1((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,
@@ -85819,36 +86663,36 @@ async function runTestBeforeIfNeeded(options) {
     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,
     });
 }
@@ -85894,7 +86738,6 @@ function startPauseListenerIfNeeded(isRichUiEnabled) {
  * 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;
     }
@@ -85903,7 +86746,7 @@ async function runDryRunIfRequested(options, agentReferences) {
         modelName: options.agentName ? resolveRunnerModel(options.agentName, options.model) : options.model,
         agentReferences,
     };
-    const promptFiles = (await loadPromptFiles(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(join(options.projectPath, 'prompts'), {
         isMissingDirectoryAllowed: true,
     })).map((file) => ({
         ...file,
@@ -85912,7 +86755,7 @@ async function runDryRunIfRequested(options, agentReferences) {
     const stats = summarizePrompts(promptFiles, options.priorityFilter);
     printStats(stats, options.priorityFilter);
     console.info(colors.yellow('Following prompts need to be written:'));
-    printPromptsToBeWritten(promptFiles, options.priorityFilter);
+    printPromptsToBeWritten(promptFiles, options.priorityFilter, options.projectPath);
     return true;
 }
 /**
@@ -85927,7 +86770,7 @@ function initializeRunUi(uiHandle, runnerName, actualRunnerModel, options) {
         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}`);
@@ -85950,10 +86793,9 @@ async function initializeRunUiAgentVisual(uiHandle, agentSource) {
  * 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(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(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);
@@ -85980,10 +86822,10 @@ function showUpcomingTasksOnce(options) {
     }
     if (stats.toBeWritten > 0) {
         console.info(colors.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;
 }
 /**
@@ -86180,12 +87022,14 @@ function buildCoderServerPromptFileResponses(options) {
     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,
@@ -86196,13 +87040,15 @@ function buildCoderServerPromptFileResponses(options) {
  * Builds one prompt-file response.
  */
 function buildCoderServerPromptFileResponse(options) {
+    var _a;
     const { promptFile, isFinished, priorityFilter, activePrompt } = options;
     return {
         filePath: promptFile.path,
         fileName: promptFile.name,
-        relativeFilePath: relative(process.cwd(), promptFile.path).replace(/\\/gu, '/'),
+        relativeFilePath: 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,
@@ -86217,7 +87063,7 @@ function buildCoderServerPromptFileResponse(options) {
 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,
@@ -86232,7 +87078,7 @@ function buildCoderServerPromptSectionResponse(options) {
         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,
@@ -86309,11 +87155,11 @@ function getActivePrompt(uiState) {
 /**
  * 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`
 
@@ -87234,6 +88080,7 @@ async function loadPromptsForApi(options) {
     const promptFiles = await loadPromptFilesSafely(promptsDir);
     const finishedPromptFiles = await loadPromptFilesSafely(join(promptsDir, FINISHED_PROMPTS_DIRECTORY_NAME));
     return buildCoderServerPromptFileResponses({
+        projectPath: dirname(promptsDir),
         promptFiles,
         finishedPromptFiles,
         priorityFilter,
@@ -87320,18 +88167,20 @@ function jsonHeaders() {
  * @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());
     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,