@promptbook/cli 0.114.0-49 → 0.114.0-50

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

@@ -20,12 +20,12 @@ const CODER_ENV_GITIGNORE_RULE = '.env';
 const CODER_GITIGNORE_HEADER = '# Promptbook Coder';
 
 /**
- * Coder-owned local artifacts which every initialized project should ignore.
+ * Local dependencies and artifacts which every initialized coder project should ignore.
  */
-const CODER_GITIGNORE_RULES = [PROMPTBOOK_TEMP_GITIGNORE_RULE, CODER_ENV_GITIGNORE_RULE] as const;
+const CODER_GITIGNORE_RULES = [PROMPTBOOK_TEMP_GITIGNORE_RULE, CODER_ENV_GITIGNORE_RULE, 'node_modules'] as const;
 
 /**
- * Ensures `.gitignore` contains Promptbook Coder's local artifacts and every supported harness's local artifacts.
+ * Ensures `.gitignore` covers local dependencies, coder artifacts and every supported harness's local artifacts.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */

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

@@ -1,5 +1,4 @@
-import { stat, writeFile } from 'fs/promises';
-import { join } from 'path';
+import { ensureProjectTextFile } from '../common/ensureProjectTextFile';
 import type { InitializationStatus } from './boilerplateTemplates';
 
 /**
@@ -12,24 +11,7 @@ export async function ensureCoderMarkdownFile(
     relativeFilePath: string,
     fileContent: string,
 ): Promise<InitializationStatus> {
-    const absoluteFilePath = join(projectPath, relativeFilePath);
-    if (await isExistingFile(absoluteFilePath)) {
-        return 'unchanged';
-    }
-
-    await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
-    return 'created';
-}
-
-/**
- * Checks whether a path exists and is a file.
- */
-async function isExistingFile(path: string): Promise<boolean> {
-    try {
-        return (await stat(path)).isFile();
-    } catch {
-        return false;
-    }
+    return ensureProjectTextFile(projectPath, relativeFilePath, fileContent);
 }
 
 // Note: [🟡] Code for coder init markdown bootstrapping [ensureCoderMarkdownFile](src/cli/cli-commands/coder/ensureCoderMarkdownFile.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,166 @@
+import type { Command as Program } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import { DEFAULT_CODER_CHECK_COMMAND } from '../../../../scripts/run-codex-prompts/checks/CheckBeforeMode';
+import { assertProjectCheckIsConfigured } from '../../../../scripts/run-codex-prompts/checks/projectCheck';
+import { resolveCoderProjectContext } from '../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext';
+import { runCoderFix, validateCoderFixOptions } from '../../../../scripts/run-codex-prompts/main/runCoderFix';
+import { addCoderCheckOptions, normalizeCheckCommandOption } from '../common/coderCheckCliOptions';
+import { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSufficientFreeDiskSpace';
+import { handleActionErrors } from '../common/handleActionErrors';
+import { normalizeProjectCliOptions, type ProjectCliOptions } from '../common/projectCliOptions';
+import {
+    addPromptRunnerExecutionOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerCliOptions,
+    type PromptRunnerCliOptions,
+} from '../common/promptRunnerCliOptions';
+import {
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { addCoderExecutionOptions } from './agentCliOptions';
+import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
+
+/**
+ * Shared shell convention for an interrupted finite command.
+ * @private internal CLI exit convention
+ */
+const INTERRUPTED_EXIT_CODE = 130;
+
+/**
+ * Registers a finite check-repair command with the shared parser, defaults and execution policy.
+ * @private internal CLI command registration
+ */
+export function $initializeCoderFixCommand(program: Program): $side_effect {
+    const command = program.command('fix').description(
+        spaceTrim(`
+        Run project checks, repair their failures with one PRD, verify, commit eligible changes, and exit
+
+        Omitted --check selects npm run check in the selected project. A passing project starts no coding harness.
+        Repairs use the project's Developer Book and the selected harness/model; only the selected repair runs.
+        Ordinary PRDs and their statuses are left alone. There is no queue, watcher, or planning session.
+        Pull and push are explicit opt-ins. --no-commit follows the shared --git-changes ignore constraint.
+        Implementation/repair and check changes use separate commits; failed checks retain their genuine outcome.
+        Interrupted work is preserved; --git-changes continue cannot resume arbitrary backlog tasks here.
+    `),
+    );
+    command.option('--dry-run', 'Describe the resolved check and possible repair without executing or mutating', false);
+    addPromptRunnerSelectionOptions(command);
+    addQuestionsOption(command);
+    addCoderExecutionOptions(command);
+    addCoderCheckOptions(
+        command,
+        false,
+        'Run checks first and verify each repair attempt (default npm run check); persist check changes separately unless --no-commit; quote commands containing flags or shell composition',
+    );
+    addPromptRunnerExecutionOptions(command);
+    command.option('--preserve-logs', 'Keep successful check and repair artifacts', false);
+    command.option('--wait-after-error <duration>', 'Delay before bounded execution-error retries (default 10m)');
+    addWorkspaceRepositoryOptions(command);
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const inputs = cliOptions as PromptRunnerCliOptions &
+                QuestionsCliOptions &
+                ProjectCliOptions & {
+                    readonly dryRun: boolean;
+                    readonly agent?: string;
+                    readonly context?: string;
+                    readonly check?: string | string[];
+                    readonly preserveLogs: boolean;
+                    readonly waitAfterError?: string;
+                };
+            const runnerOptions = normalizePromptRunnerCliOptions(inputs, { isAgentRequired: !inputs.dryRun });
+            const options = {
+                ...runnerOptions,
+                ...normalizeQuestionsCliOptions(inputs),
+                dryRun: inputs.dryRun,
+                agent: inputs.agent,
+                context: inputs.context,
+                checkCommand: normalizeCheckCommandOption(inputs.check) ?? DEFAULT_CODER_CHECK_COMMAND,
+                preserveLogs: inputs.preserveLogs,
+                waitAfterError: parseOptionalWaitDuration(inputs.waitAfterError, DEFAULT_WAIT_AFTER_ERROR_MS),
+            };
+            if (options.gitChanges === 'continue')
+                throw new NotAllowed(
+                    spaceTrim(`
+            \`coder fix\` cannot resume an arbitrary interrupted PRD with \`--git-changes continue\`.
+            Inspect the specific repair's saved PRD, trace and changes; commit or recover that work before retrying.
+            Use \`--git-changes ignore\` explicitly to preserve existing work while starting a new check job.
+        `),
+                );
+            validateCoderFixOptions(options);
+            const projectOptions = normalizeProjectCliOptions(inputs);
+            // Read-only discovery lets check configuration fail before an interactive Git initializer can write.
+            const inspectedWorkspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'read-only',
+                ...options,
+            });
+            await assertProjectCheckIsConfigured(options.checkCommand, inspectedWorkspace.projectPath);
+            const projectContext = await resolveCoderProjectContext({
+                projectPath: inspectedWorkspace.projectPath,
+                agent: options.agent,
+                context: options.context,
+                isDefaultAgentDeferred: true,
+            });
+            const workspace = inputs.dryRun
+                ? inspectedWorkspace
+                : await $preflightWorkspaceRepository({
+                      projectDirectory: inspectedWorkspace.projectPath,
+                      policy: 'mutate',
+                      ...options,
+                  });
+            if (!inputs.dryRun) await $assertSufficientFreeDiskSpace(workspace.projectPath);
+            const controller = new AbortController();
+            /** Cancels owned activity and waits for artifact/lock cleanup before exiting. */
+            const cancel = () =>
+                controller.abort(
+                    new NotAllowed('Check repair interrupted; recoverable work and diagnostics were preserved.'),
+                );
+            if (!inputs.dryRun) {
+                process.on('SIGINT', cancel);
+                process.on('SIGTERM', cancel);
+            }
+            try {
+                const result = await runCoderFix({ ...options, workspace, projectContext, signal: controller.signal });
+                if (inputs.dryRun) return;
+                const persistence = options.noCommit
+                    ? 'Eligible changes left uncommitted.'
+                    : options.autoPush
+                    ? 'Eligible changes committed and pushed, when present.'
+                    : 'Eligible changes committed, when present.';
+                if (result.kind === 'passed-without-repair')
+                    console.info(`Checks passed without repair. ${persistence}`);
+                else if (result.kind === 'repaired-and-verified')
+                    console.info(`Repaired and verified with \`${options.checkCommand}\`. ${persistence}`);
+                else {
+                    const label =
+                        result.kind === 'checks-failed'
+                            ? 'Unresolved check failures'
+                            : result.kind === 'interrupted'
+                            ? 'Check repair interrupted'
+                            : result.kind === 'persistence-error'
+                            ? `Git/persistence error; checks ${result.isCheckPassed ? 'passed' : 'did not pass'}`
+                            : result.kind === 'execution-error'
+                            ? 'Check execution error'
+                            : 'Check repair setup/harness error';
+                    console.error(`${label}. Ordinary PRDs were not processed.`);
+                    if (result.repairPrompt) console.error(`Repair artifact: \`${result.repairPrompt.file.path}\`.`);
+                    console.error(result.error instanceof Error ? result.error.message : String(result.error));
+                    return process.exit(result.kind === 'interrupted' ? INTERRUPTED_EXIT_CODE : 1);
+                }
+            } finally {
+                process.removeListener('SIGINT', cancel);
+                process.removeListener('SIGTERM', cancel);
+            }
+        }),
+    );
+}
+
+// Note: [🟡] Code for CLI command [fix](src/cli/cli-commands/coder/fix.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/coder/fixtures/fix.cjs

@@ -0,0 +1,29 @@
+// Deterministic offline harness for the installed CLI check-repair contract.
+const FILESYSTEM = require('fs');
+const PATH = require('path');
+const ARGUMENTS = process.argv.slice(2);
+if (ARGUMENTS.includes('--version')) {
+    process.stdout.write('codex-cli 0.0.0\n');
+    process.exit(0);
+}
+FILESYSTEM.mkdirSync('.promptbook', { recursive: true });
+FILESYSTEM.appendFileSync('.promptbook/harness-invocations', `${ARGUMENTS.join(' ')}\n`);
+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() || prompt.includes('FORBIDDEN_') ||
+        !prompt.includes('Fix the existing project check failures only.')) {
+        process.stderr.write('Fixture received wrong project or ordinary task.\n');
+        process.exitCode = 2;
+        return;
+    }
+    FILESYSTEM.writeFileSync('.promptbook/mock-call.json', JSON.stringify({ projectPath, prompt }));
+    if (!FILESYSTEM.existsSync('.promptbook/keep-failing')) FILESYSTEM.writeFileSync('value.txt', 'fixed');
+    process.stdout.write('Verified correction fixture completed.\ntokens used\n0\n');
+});

package/src/cli/cli-commands/coder/fixtures/healthyDisk.cjs

@@ -0,0 +1,4 @@
+// Subprocess-only fixture: machine disk pressure is not an input to CLI parsing/repair smoke tests.
+// The production disk guard and its dedicated unit tests retain the real thresholds.
+const FILE_SYSTEM_PROMISES = require('fs/promises');
+FILE_SYSTEM_PROMISES.statfs = async () => ({ bsize: 4096, bavail: 10000000, blocks: 20000000 });

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

@@ -3,6 +3,7 @@ import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
 import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
 import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
 import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_GITATTRIBUTES_FILE_PATH } from './ensureCoderGitattributesFile';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 
 /**
@@ -27,6 +28,7 @@ export function getCoderInitializationCommitPaths(
         },
         { relativeFilePath: '.env', status: summary.envFileStatus },
         { relativeFilePath: '.gitignore', status: summary.gitignoreFileStatus },
+        { relativeFilePath: CODER_GITATTRIBUTES_FILE_PATH, status: summary.gitattributesFileStatus },
         { relativeFilePath: 'package.json', status: summary.packageJsonFileStatus },
         { relativeFilePath: '.vscode/settings.json', status: summary.vscodeSettingsFileStatus },
         ...summary.referencedArtifactStatuses,

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

@@ -29,6 +29,7 @@ import { AGENTS_FILE_PATH } from './agentsFile';
 import { DEFAULT_BOILERPLATE_COUNT } from './boilerplateCount';
 import { getDefaultCoderProjectPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH } from './boilerplateTemplates';
 import { CODER_AGENTS_DIRECTORY_PATH, CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_GITATTRIBUTES_FILE_PATH } from './ensureCoderGitattributesFile';
 import { isDirectoryEmpty } from './ensureDirectory';
 import { formatDisplayPath } from './formatDisplayPath';
 import { generatePromptBoilerplate } from './generate-boilerplates';
@@ -79,7 +80,8 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 - agents/copywriter.book
                 - ${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}
                 - ${AGENTS_FILE_PATH}
-                - .gitignore with local artifacts from every supported harness
+                - .gitignore with node_modules and local artifacts from every supported harness
+                - ${CODER_GITATTRIBUTES_FILE_PATH} with automatic text detection and LF line endings (existing file is preserved)
                 - package.json
                 - .vscode/settings.json
 

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

@@ -10,6 +10,7 @@ import { ensureCoderReferencedArtifacts } from './coderReferencedArtifacts';
 import { ensureCoderDefaultAgentFiles } from './ensureCoderDefaultAgentFiles';
 import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
+import { CODER_GITATTRIBUTES_FILE_PATH, ensureCoderGitattributesFile } from './ensureCoderGitattributesFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
@@ -33,6 +34,7 @@ export type CoderInitializationSummary = {
     readonly adamAgentFileDiagnostic?: string;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
+    readonly gitattributesFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
     readonly vscodeSettingsFileStatus: InitializationStatus;
     readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
@@ -91,6 +93,10 @@ export async function initializeCoderProjectConfiguration(
     )!;
     const { envFileStatus, initializedEnvVariableNames } = await completeStep('.env', ensureCoderEnvFile(projectPath));
     const gitignoreFileStatus = await completeStep('.gitignore', ensureCoderGitignoreFile(projectPath));
+    const gitattributesFileStatus = await completeStep(
+        CODER_GITATTRIBUTES_FILE_PATH,
+        ensureCoderGitattributesFile(projectPath),
+    );
     const {
         status: packageJsonFileStatus,
         addedEntryKeys: addedPackageJsonScriptNames,
@@ -123,6 +129,7 @@ export async function initializeCoderProjectConfiguration(
         adamAgentFileDiagnostic: adamArtifact.diagnostic,
         envFileStatus,
         gitignoreFileStatus,
+        gitattributesFileStatus,
         packageJsonFileStatus,
         vscodeSettingsFileStatus,
         addedPackageJsonScriptNames,

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

@@ -2,6 +2,10 @@
 const FILESYSTEM = require('fs');
 const PATH = require('path');
 const ARGUMENTS = process.argv.slice(2);
+if (ARGUMENTS.includes('--version')) {
+    process.stdout.write('codex-cli 0.0.0\n');
+    process.exit(0);
+}
 if (ARGUMENTS[0] === 'login') {
     process.stdout.write('Logged in using ChatGPT\n');
     process.exit(0);

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

@@ -2,6 +2,7 @@ import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
 import colors from 'colors';
 import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
 import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_GITATTRIBUTES_FILE_PATH } from './ensureCoderGitattributesFile';
 import type { InitializationStatus } from './boilerplateTemplates';
 import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
 import { formatDisplayPath } from './formatDisplayPath';
@@ -40,6 +41,7 @@ export function printInitializationSummary(
     );
     printInitializationStatusLine('.env', summary.envFileStatus);
     printInitializationStatusLine('.gitignore', summary.gitignoreFileStatus);
+    printInitializationStatusLine(CODER_GITATTRIBUTES_FILE_PATH, summary.gitattributesFileStatus);
     printInitializationStatusLine('package.json', summary.packageJsonFileStatus);
     printInitializationStatusLine('.vscode/settings.json', summary.vscodeSettingsFileStatus);
 

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

@@ -281,6 +281,7 @@ export const PROMPTS_README_TEMPLATE = spaceTrim(`
     | \`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 --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 fix --harness openai-codex\`                                                   | Always runs project checks first (default \`npm run check\`), repairs genuine failures with one PRD, verifies and commits eligible changes, then exits. Never selects ordinary queued PRDs. A passing project launches no harness or repair. |
     | \`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.                                                                                                                                                                                                                                    |
@@ -301,6 +302,29 @@ export const PROMPTS_README_TEMPLATE = spaceTrim(`
     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.
+
+    \`ptbk coder fix\` reuses run's check-and-repair phase and stops as soon as that phase finishes. Use
+    \`ptbk coder fix --harness openai-codex --check "npm run lint && npm run build && npm test"\` to select
+    the project's explicit validation scope. No extra validation command is added. Check failures produce one
+    repair PRD under \`prompts/\`; feedback retries update that same task, with at most three repair verification attempts.
+    The repair may correct a defective check while preserving its intended validation, but must never weaken
+    assertions, lint rules, builds, or thresholds to get a pass. Ordinary PRDs and their statuses are left alone,
+    including interrupted tasks. An absent prompts directory is created only when a repair needs its artifact.
+    Default Book compilation and harness preparation happen only after a failed check actually needs repair.
+    Configure a missing Developer with \`ptbk coder init\` or select a custom Book; an already healthy project
+    requires neither a Book nor an installed harness. Explicit Books/context overrides are validated up front.
+    Passing formatters/generators commit only their eligible files, with no empty commit and no fabricated PRD.
+    Repair checks run after scoped line-ending normalization, verifying the content that will be committed.
+    Use \`--no-normalize-line-endings\` for projects that intentionally require other line endings.
+    Existing unrelated staged/unstaged files remain outside scoped commits. \`--git-changes ignore\` explicitly
+    permits a dirty tree; \`--no-commit\` also requires that option. Pull/push remain explicit \`--auto-pull\` /
+    \`--auto-push\` opt-ins. A rejected push leaves the local verified commit available and starts no new repair.
+    \`--dry-run\` describes the job without checking, creating tasks, installing tools, calling models or committing.
+    \`--no-ui\`, \`--no-questions\` and \`--preserve-logs\` apply to this finite job. Cancellation preserves work
+    and diagnostics. \`fix\` rejects \`--git-changes continue\`: inspect/recover the specific saved repair before
+    retrying instead of resuming an arbitrary backlog task. Run/server/fix share an exclusive workspace mutation
+    lease; inspect a stopped worker's work before explicitly removing a stale lease reported in its diagnostic.
+
     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.
@@ -315,7 +339,7 @@ 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\`, \`server\` and \`plan\` default to Developer.
+    invoke everyone. \`run\`, \`fix\`, \`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.
 

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

@@ -33,6 +33,7 @@ import {
 import { addCoderCheckOptions, normalizeCheckCommandOption } from '../common/coderCheckCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
+import { withCoderWorkspaceLock } from '../../../../scripts/run-codex-prompts/common/withCoderWorkspaceLock';
 import { addCoderExecutionOptions, type CoderAgentCliOptions } from './agentCliOptions';
 import { printCoderRunFailure } from './printCoderRunFailure';
 
@@ -75,6 +76,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Supports GPG signing of commits
             - Optional pre-coding check run that can stop or repair pre-existing failures
             - Optional post-prompt checks with check-feedback retries
+            - Persists implementation and check-produced changes in separate commits, including failed checks
+            - Records task completion only after passing checks and required local persistence
             - Progress tracking and interactive P/S/X terminal controls; O changes only the dashboard output view
             - Dry-run mode to preview prompts
         `,
@@ -97,6 +100,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
         spaceTrim(`
             Implement each prompt in its own temporary git worktree with its own isolated environment.
             A verified task is merged back into the branch the coder runs on and the worktree is deleted.
+            Fast-forward integration preserves separate implementation, check and finalization commits.
             A task that cannot be merged is marked as failed and its worktree is kept for a manual merge.
         `),
         false,
@@ -259,16 +263,21 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 // Check disk space before installations and repository writes; previews require no setup.
                 await $assertSufficientFreeDiskSpace(workspace.projectPath);
 
-                if (await $ensurePromptbookCliInstallations(questionsOptions, workspace.projectPath)) {
+                const isCliUpdated = await withCoderWorkspaceLock(workspace, async () => {
+                    if (await $ensurePromptbookCliInstallations(questionsOptions, workspace.projectPath)) {
+                        return true;
+                    }
+                    await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+                    await $ensureCoderHarnessGitignoreRules(
+                        workspace.projectPath,
+                        runnerOptions.agentName,
+                        questionsOptions,
+                    );
+                    return false;
+                });
+                if (isCliUpdated) {
                     return process.exit(0);
                 }
-
-                await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
-                await $ensureCoderHarnessGitignoreRules(
-                    workspace.projectPath,
-                    runnerOptions.agentName,
-                    questionsOptions,
-                );
             }
 
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed

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

@@ -33,6 +33,7 @@ import {
 import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
+import { withCoderWorkspaceLock } from '../../../../scripts/run-codex-prompts/common/withCoderWorkspaceLock';
 import { addCoderExecutionOptions, type CoderAgentCliOptions } from './agentCliOptions';
 import { printCoderRunFailure } from './printCoderRunFailure';
 
@@ -235,12 +236,14 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 // Check disk space before installations and repository writes; previews require no setup.
                 await $assertSufficientFreeDiskSpace(workspace.projectPath);
 
-                await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
-                await $ensureCoderHarnessGitignoreRules(
-                    workspace.projectPath,
-                    runnerOptions.agentName,
-                    questionsOptions,
-                );
+                await withCoderWorkspaceLock(workspace, async () => {
+                    await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+                    await $ensureCoderHarnessGitignoreRules(
+                        workspace.projectPath,
+                        runnerOptions.agentName,
+                        questionsOptions,
+                    );
+                });
             }
 
             // Note: Import dynamically to avoid loading heavy dependencies until needed

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

@@ -15,6 +15,7 @@ import { $initializeCoderListCommand } from './coder/list';
 import { $initializeCoderPingCommand } from './coder/ping';
 import { $initializeCoderPlanCommand } from './coder/plan';
 import { $initializeCoderRunCommand } from './coder/run';
+import { $initializeCoderFixCommand } from './coder/fix';
 import { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
 
@@ -29,6 +30,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * - find-refactor-candidates: Find files that need refactoring
  * - list: List ready prompts in priority order without running them
  * - run: Run coding prompts with AI agents
+ * - fix: Check and repair the project, then exit without processing the queue
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
@@ -52,6 +54,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - find-unwritten: List prompt sections that still need to be authored
             - list: List ready prompts in priority order without running them
             - run: Run coding prompts with AI agents
+            - fix: Check and repair the project, then exit without processing the queue
             - ping: Test the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
@@ -70,6 +73,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderFindUnwrittenCommand(coderCommand);
     $initializeCoderListCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderFixCommand(coderCommand);
     $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);

package/src/cli/cli-commands/common/coderCheckCliOptions.ts

@@ -35,18 +35,19 @@ export const LEGACY_CODER_CHECK_OPTIONS = [
  * Registers the shared project check command and rejects retired aggregate-test spellings.
  * @private shared CLI registration for Coder execution
  */
-export function addCoderCheckOptions(command: Command, isCheckBeforeSupported: boolean): void {
-    command.option(
-        '--check <check-command...>',
-        'Run project checks after each prompt; quote the full command when it contains flags or shell composition',
-    );
+export function addCoderCheckOptions(
+    command: Command,
+    isCheckBeforeSupported: boolean,
+    description = 'Run project checks after each prompt; commit eligible check changes separately unless --no-commit; quote commands containing flags or shell composition',
+): void {
+    command.option('--check <check-command...>', description);
     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)`,
+                )} (defaults to no; uses npm run check when --check is omitted; both enabled modes commit eligible check changes separately unless --no-commit)`,
             )
                 .choices([...CHECK_BEFORE_MODE_VALUES])
                 .default('no'),

package/src/cli/cli-commands/common/ensureProjectTextFile.ts

@@ -0,0 +1,35 @@
+import { stat, writeFile } from 'fs/promises';
+import { join } from 'path';
+import type { ProjectInitializationStatus } from './projectInitialization';
+
+/**
+ * Creates one project text file with default content, preserving any existing file.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export async function ensureProjectTextFile(
+    projectPath: string,
+    relativeFilePath: string,
+    fileContent: string,
+): Promise<ProjectInitializationStatus> {
+    const absoluteFilePath = join(projectPath, relativeFilePath);
+    if (await isExistingFile(absoluteFilePath)) {
+        return 'unchanged';
+    }
+
+    await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
+    return 'created';
+}
+
+/**
+ * Checks whether a path exists and is a file.
+ */
+async function isExistingFile(path: string): Promise<boolean> {
+    try {
+        return (await stat(path)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+// Note: [🟡] Code for project text file bootstrapping [ensureProjectTextFile](src/cli/cli-commands/common/ensureProjectTextFile.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts

@@ -4,6 +4,8 @@ import { $applyHarnessInstallationStatus } from './$applyHarnessInstallationStat
 import { $checkHarnessInstallation } from './$checkHarnessInstallation';
 import type { HarnessDefinition } from './HarnessDefinition';
 import { getHarnessDefinition } from './HarnessDefinition';
+import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import { NotAllowed } from '../../../../errors/NotAllowed';
 
 /**
  * Checks that every given CLI coding harness is installed globally and, when the questions are enabled, up to date.
@@ -19,6 +21,7 @@ import { getHarnessDefinition } from './HarnessDefinition';
 export async function $ensureHarnessInstallations(
     harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
     questionsOptions: NormalizedQuestionsCliOptions,
+    options: { readonly isRequired?: boolean } = {},
 ): Promise<void> {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
 
@@ -37,6 +40,16 @@ export async function $ensureHarnessInstallations(
 
     for (const status of statuses) {
         await $applyHarnessInstallationStatus(status, questionsOptions);
+        if (options.isRequired && status.installationState === 'not-installed') {
+            const rechecked = await $checkHarnessInstallation(status.definition, false);
+            if (rechecked.installationState === 'not-installed') {
+                throw new NotAllowed(
+                    `Repair requires ${status.definition.label}. Install it with \`${buildHarnessInstallCommand(
+                        status.definition,
+                    )}\`, then retry. No other task was executed.`,
+                );
+            }
+        }
     }
 }
 

package/src/cli/cli-commands/common/validateCoderRunOptions.ts

@@ -8,7 +8,22 @@ import { NotAllowed } from '../../../errors/NotAllowed';
  * Validates cross-flag constraints before workspace setup or the run starts.
  * @private shared validation for Coder execution commands
  */
-export function validateCoderRunOptions(options: RunOptions): void {
+export function validateCoderRunOptions(
+    options: Pick<
+        RunOptions,
+        | 'checkCommand'
+        | 'checkBefore'
+        | 'allowDestructiveAutoMigrate'
+        | 'autoMigrate'
+        | 'noCommit'
+        | 'waitForUser'
+        | 'gitChanges'
+        | 'autoPull'
+        | 'dryRun'
+        | 'isIsolated'
+        | 'limit'
+    >,
+): void {
     if (options.checkCommand !== undefined && !options.checkCommand.trim()) {
         throw new NotAllowed(
             spaceTrim(`