@promptbook/cli 0.114.0-48 → 0.114.0-49

package/src/cli/cli-commands/coder/ping.ts

@@ -5,6 +5,7 @@ import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
@@ -68,6 +69,7 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { period: periodValue } = cliOptions as {
                 readonly period?: string;
             } & PromptRunnerSelectionCliOptions;
@@ -81,7 +83,11 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             // 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);

package/src/cli/cli-commands/coder/plan.ts

@@ -7,13 +7,14 @@ import { spaceTrim } from '../../../utils/organization/spaceTrim';
 import { addCoderGitSyncOptions, normalizeCoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import {
     addPromptRunnerRuntimeOptions,
     addPromptRunnerSelectionOptions,
     normalizePromptRunnerSelectionCliOptions,
 } from '../common/promptRunnerCliOptions';
-import { addCoderAgentOption } from './agentCliOptions';
+import { addCoderExecutionOptions } from './agentCliOptions';
 
 /**
  * Registers the repository-aware, planning-only conversation under the existing coder command group.
@@ -22,10 +23,10 @@ import { addCoderAgentOption } from './agentCliOptions';
 export function $initializeCoderPlanCommand(program: Program): $side_effect {
     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.
@@ -35,7 +36,7 @@ export function $initializeCoderPlanCommand(program: Program): $side_effect {
     );
     addPromptRunnerSelectionOptions(command);
     addPromptRunnerRuntimeOptions(command);
-    addCoderAgentOption(command, 'planner');
+    addCoderExecutionOptions(command);
     addCoderGitSyncOptions(command);
     command.option(
         '--template <path>',
@@ -45,6 +46,7 @@ export function $initializeCoderPlanCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { createPlanningTerminal } = await import('./planning/createPlanningTerminal');
             const { runPlanningSession } = await import('./planning/runPlanningSession');
             const { resolvePlanningPath } = await import('./planning/resolvePlanningPath');
@@ -57,6 +59,7 @@ export function $initializeCoderPlanCommand(program: Program): $side_effect {
             assertPlanningHarnessSupported(options.agentName);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });
@@ -67,6 +70,13 @@ export function $initializeCoderPlanCommand(program: Program): $side_effect {
                     ),
                 );
             }
+            const { resolveCoderProjectContext } = await import(
+                '../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext'
+            );
+            const projectContext = await resolveCoderProjectContext({
+                ...cliOptions,
+                projectPath: workspace.projectPath,
+            });
             const terminal = createPlanningTerminal();
             try {
                 const { projectPath } = workspace;
@@ -80,6 +90,8 @@ export function $initializeCoderPlanCommand(program: Program): $side_effect {
                         ...options,
                         projectPath,
                         agent: cliOptions.agent,
+                        context: cliOptions.context,
+                        projectContext,
                         template: cliOptions.template,
                         preexistingChangedPaths: gitSync.isCommitEnabled
                             ? new Set(

package/src/cli/cli-commands/coder/planning/README.md

@@ -1,10 +1,12 @@
 # Coder planning
 
 Run `ptbk coder init`, then `ptbk coder plan --harness openai-codex` in an interactive terminal.
-The editable `agents/planner.book` uses the same implicit Adam inheritance as Developer. An explicit `--agent`
-overrides the Book through the shared resolver; planning resolves Books without initializing missing ancestors.
+The default primary Book is `agents/developer.book`; use `--agent ./agents/planner.book` to select Planner.
+Both use the same implicit Adam inheritance. `--path` defaults to invocation cwd, and additional context defaults
+to that project's AGENTS.md. An explicit `--context` replaces it with inline text or a project-relative file;
+`--context ""` disables it. Planning resolves Books without initializing missing ancestors.
 
-The discussion retains messages, read results and saved paths across topics. Planner proposes changes as data.
+The discussion retains messages, read results and saved paths across topics. The selected Book proposes changes as data.
 The CLI shows exact paths and changed text, then accepts `/save`, `/draft`, `/discard`, or another discussion turn.
 EOF and `/exit` discard unsaved proposals. Ctrl+C aborts inference. Saved files remain intact after failures.
 

package/src/cli/cli-commands/coder/planning/fixtures/coding.cjs

@@ -0,0 +1,22 @@
+// Offline coding harness. Capture exactly what the installed CLI supplied, including the shell's -C argument.
+const FILESYSTEM = require('fs');
+const PATH = require('path');
+const ARGUMENTS = process.argv.slice(2);
+if (ARGUMENTS[0] === 'login') {
+    process.stdout.write('Logged in using ChatGPT\n');
+    process.exit(0);
+}
+if (!ARGUMENTS.includes('exec')) process.exit(2);
+let prompt = '';
+process.stdin.on('data', (chunk) => { prompt += chunk; });
+process.stdin.on('end', () => {
+    const projectPath = ARGUMENTS[ARGUMENTS.indexOf('-C') + 1];
+    if (PATH.resolve(projectPath) !== process.cwd()) {
+        process.stderr.write(`Wrong project argument: ${projectPath}; cwd: ${process.cwd()}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    FILESYSTEM.mkdirSync('.promptbook', { recursive: true });
+    FILESYSTEM.writeFileSync('.promptbook/mock-call.json', JSON.stringify({ projectPath, cwd: process.cwd(), prompt }));
+    process.stdout.write('Offline fixture completed.\ntokens used\n0\n');
+});

package/src/cli/cli-commands/coder/planning/runPlanningSession.ts

@@ -2,6 +2,11 @@ import { existsSync, readFileSync } from 'fs';
 import { realpath } from 'fs/promises';
 import { join } from 'path';
 import { resolveCoderAgent } from '../../../../../scripts/run-codex-prompts/common/resolveCoderAgent';
+import {
+    resolveCoderProjectContext,
+    type ResolvedCoderProjectContext,
+} from '../../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext';
+import { DEFAULT_CODER_AGENT_ROLE } from '../coderAgentRole';
 import { CoderTeamRuntime } from '../../../../../scripts/run-codex-prompts/team/CoderTeamRuntime';
 import { appendCoderTeamEvent } from '../../../../../scripts/run-codex-prompts/team/createCoderTeamPromptRunner';
 import type { Usage } from '../../../../execution/Usage';
@@ -38,6 +43,8 @@ export async function runPlanningSession(
     options: NormalizedPromptRunnerSelectionCliOptions & {
         readonly projectPath: string;
         readonly agent?: string;
+        readonly context?: string;
+        readonly projectContext?: ResolvedCoderProjectContext;
         readonly template?: string;
         readonly preexistingChangedPaths?: ReadonlySet<string>;
     },
@@ -46,15 +53,16 @@ export async function runPlanningSession(
 ): Promise<ReadonlyMap<string, string>> {
     const projectPath = await realpath(options.projectPath);
     assertPlanningHarnessSupported(options.agentName);
+    const projectContext = options.projectContext ?? (await resolveCoderProjectContext({ ...options, projectPath }));
     const agent = await resolveCoderAgent(options.agent, projectPath, {
-        defaultRole: 'planner',
+        defaultRole: DEFAULT_CODER_AGENT_ROLE,
         isInitializationAllowed: false,
         signal: io.signal,
     });
     if (!existsSync(join(projectPath, 'prompts'))) {
         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`.'));
+    if (!agent) throw new NotFoundError(spaceTrim('Primary Book is missing. Run `ptbk coder init`.'));
     resolvePlanningPath(projectPath, 'prompts');
     const templateOption =
         options.template ??
@@ -111,7 +119,10 @@ export async function runPlanningSession(
             },
             { 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',

package/src/cli/cli-commands/coder/planning/savePlanningChanges.ts

@@ -63,9 +63,7 @@ export function savePlanningChanges(
             const current = existsSync(change.path) ? readFileSync(change.path, 'utf-8') : null;
             if (current !== change.before) {
                 throw new NotAllowed(
-                    spaceTrim(
-                        `\`${change.planningPath}\` changed while saving. Review a fresh preview.`,
-                    ),
+                    spaceTrim(`\`${change.planningPath}\` changed while saving. Review a fresh preview.`),
                 );
             }
             if (change.before === null) {

package/src/cli/cli-commands/coder/prepareCoderPackageJsonScripts.ts

@@ -0,0 +1,304 @@
+import {
+    assertProjectCheckScriptsAreConfigured,
+    CHECK_SETUP_PLACEHOLDER_COMMAND,
+    CoderCheckSetupError,
+    isCheckSetupRequired,
+} from '../../../../scripts/run-codex-prompts/checks/projectCheck';
+import { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonScripts';
+import { projectScriptReferences } from '../../../../scripts/run-codex-prompts/checks/projectScriptReferences';
+
+/** Old initialized aggregate entries, used only at this migration boundary. */
+const LEGACY_CHECK_SCRIPT_NAMES = ['test-for-ptbk-coder', 'check-for-ptbk-coder'] as const;
+
+/** 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'],
+] as const;
+
+/** 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'],
+] as const;
+
+/** 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'] as const;
+
+/** Result of preparing project-owned checks and migrating recognized generated callers. @private internal initializer result */
+export type PreparedCoderPackageJsonScripts = {
+    readonly scripts: Readonly<Record<string, string>>;
+    readonly checkScriptSummary: string;
+    readonly migrationInstructions: ReadonlyArray<string>;
+    readonly isCheckConfigured: boolean;
+};
+
+/**
+ * Preserves project scripts, creates one canonical check, and migrates only exact generated caller forms.
+ * @private shared package-script preparation for Coder initialization
+ */
+export function prepareCoderPackageJsonScripts(
+    existing: Readonly<Record<string, string>>,
+    externalCallers: Readonly<Record<string, ReadonlyArray<string>>> = {},
+): PreparedCoderPackageJsonScripts {
+    const scripts = { ...existing };
+    const migrationInstructions: string[] = [];
+    const legacyNames = LEGACY_CHECK_SCRIPT_NAMES.filter((name) =>
+        Object.prototype.hasOwnProperty.call(existing, name),
+    );
+    let checkScriptSummary: string;
+
+    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 = externalCallers[legacyName] ?? [];
+        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: string, scripts: Readonly<Record<string, string>>): boolean {
+    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: string, scripts: Readonly<Record<string, string>>): boolean {
+    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: string): string | undefined {
+    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: Readonly<Record<string, string>>): string[] {
+    if (
+        SCRIPT_LIFECYCLE_PREFIXES.some(
+            (prefix) =>
+                scripts[`${prefix}check`] !== undefined &&
+                !isUsableValidationScript(`${prefix}check`, scripts, new Set()),
+        )
+    )
+        return [];
+    const selected: string[] = [];
+    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: string,
+    scripts: Readonly<Record<string, string>>,
+    visited: ReadonlySet<string>,
+): boolean {
+    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: string,
+    target: string,
+    scripts: Readonly<Record<string, string>>,
+    visited: ReadonlySet<string>,
+): boolean {
+    if (visited.has(name)) return false;
+    const nextVisited = new Set([...visited, name]);
+    const command = scripts[name] ?? '';
+    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),
+    );
+}

package/src/cli/cli-commands/coder/printInitializationSummary.ts

@@ -18,10 +18,12 @@ export function printInitializationSummary(
 ): void {
     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)
@@ -60,6 +62,8 @@ export function printInitializationSummary(
     } 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}`));
 }
 
 /**

package/src/cli/cli-commands/coder/promptsReadmeTemplate.ts

@@ -225,9 +225,9 @@ export const PROMPTS_README_TEMPLATE = spaceTrim(`
 
     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.
@@ -278,9 +278,9 @@ export const PROMPTS_README_TEMPLATE = spaceTrim(`
     | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | \`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.                                                                                                                                                                                                                                    |
@@ -292,11 +292,18 @@ export const PROMPTS_README_TEMPLATE = spaceTrim(`
     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
 
@@ -308,9 +315,20 @@ export const PROMPTS_README_TEMPLATE = spaceTrim(`
     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.