From 3fb14be887be4759ab8a572b04fe9dfcb05d60fd Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Sun, 25 Jan 2026 19:00:09 +0000
Subject: [PATCH 01/13] feat: add refinement plan for version 0.1.0 with user
 experience improvements

---
 plans/v0-1-0_REFINEMENT_PLAN.md | 367 ++++++++++++++++++++++++++++++++
 1 file changed, 367 insertions(+)
 create mode 100644 plans/v0-1-0_REFINEMENT_PLAN.md

diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
new file mode 100644
index 0000000..3bc5918
--- /dev/null
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -0,0 +1,367 @@
+# Refinement Plan for Version 0.1.0
+
+I have provisioned a separated repository to test ghcralph in isolation from source code getting it directly from npm registry and discovered a few things I would like your help to refine to be able to push a new enhanced version of the package to npm registry.
+
+## Initial Context
+
+You will find below the context of the repository created to test ghcralph in isolation. Small complementary detail: the tests have been run from a GitHub Codespace using a devcontainer.
+
+### Devcontainer
+
+```json
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
+{
+	"name": "Node.js & TypeScript",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/typescript-node:4-24-bookworm",
+	"features": {
+		"ghcr.io/devcontainers/features/copilot-cli:1": {},
+		"ghcr.io/devcontainers/features/github-cli:1": {}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"yzhang.markdown-all-in-one",
+				"GitHub.copilot"
+			]
+		}
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "npm install -g ghcralph"
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}
+```
+
+### Plan
+
+Same as [the one for the calculator test scenario](../test/integration/calculator/PLAN.md).
+
+## Findings
+
+### Finding 1: Init does not provide interactive experience by default
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph init
+
+🤖 GitHub Copilot Ralph - Initialize
+
+Configuration:
+  Plan source: local
+  Max iterations: 10
+  Max tokens: 100,000
+  Model: gpt-4.1
+  Auto commit: true
+  Branch prefix: ghcralph/
+
+Created:
+  /workspaces/ghc-ralph-cli-demo/.ghcralph
+
+✔ GitHub Copilot Ralph initialized successfully!
+
+ℹ Run ghcralph run --task "Your task" to start.
+```
+
+The `ghcralph init` command works generting the configuration json file under the expected location with the defined default values.
+But even has the creator of the CLI, I was a bit surprised it does not provide an interactive experience by default, which could be improved to enhance user-friendliness.
+
+To enhance the user experience, I would suggest to add an interactive mode by default when running `ghcralph init`,
+- first presenting the default values to the user, and asking if they want to keep them or change them,
+- then, if they want to change them, prompting for each configuration value one by one,
+- finally, summarizing the configuration values to be written in the configuration file and asking for confirmation
+
+For Plan Source, Model (list of models available using GitHub Copilot CLI) and Auto commit, please provide a list of options to choose from.
+
+### Finding 2: Run file and plan parameters confusing
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --help
+Usage: ghcralph run [options]
+
+Execute an agentic coding loop
+
+Options:
+  -t, --task <description>       Task to execute (inline)
+  -f, --file <path>              Read task from file
+  -p, --plan <path>              Read tasks from a Markdown plan file
+  -g, --github <owner/repo>      Use GitHub Issues as plan source
+  -l, --label <label>            Filter GitHub issues by label
+  --milestone <name>             Filter GitHub issues by milestone
+  --assignee <user>              Filter GitHub issues by assignee
+  -c, --context <glob...>        Include files matching glob patterns in context
+  -b, --branch <name>            Use or create a specific branch name
+  --force                        Skip branch confirmation prompts
+  --no-commit                    Disable automatic checkpoint commits
+  --unlimited                    Allow more than 50 iterations
+  --timeout <minutes>            Maximum duration in minutes
+  --allow-delete                 Allow deletion of pre-existing files
+  -n, --max-iterations <number>  Maximum loop iterations (default: "10")
+  --max-tokens <number>          Maximum token budget (default: "100000")
+  -m, --model <model>            Copilot model to use (default: "gpt-4")
+  --dry-run                      Show what would happen without executing
+  -h, --help                     display help for command
+
+Examples:
+  $ ghcralph run --task "Add input validation to the login form"
+  $ ghcralph run --file tasks/refactor.md --max-iterations 5
+  $ ghcralph run --plan TODO.md
+  $ ghcralph run --github owner/repo --label "ralph-ready"
+  $ ghcralph run --task "Fix bug" --context "src/**/*.ts" --branch fix/login-bug
+  $ ghcralph run --task "Large refactor" --unlimited --timeout 60
+
+See also:
+  ghcralph status     View current session progress
+  ghcralph rollback   Undo recent changes
+  ghcralph init       Initialize Ralph in your project
+```
+
+I think the `--file` and `--plan` parameters are a bit confusing as they both refer to a file containing a plan, but with different formats. If we want to support different file formats (exemple md and json), the processing could be dynamically routed based on the file extension rather than having separate parameters.
+
+### Finding 3: Run could benefit from complementay configuration entries for GitHub Issues plan source
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --help
+Usage: ghcralph run [options]
+
+Execute an agentic coding loop
+
+Options:
+  -t, --task <description>       Task to execute (inline)
+  -f, --file <path>              Read task from file
+  -p, --plan <path>              Read tasks from a Markdown plan file
+  -g, --github <owner/repo>      Use GitHub Issues as plan source
+  -l, --label <label>            Filter GitHub issues by label
+  --milestone <name>             Filter GitHub issues by milestone
+  --assignee <user>              Filter GitHub issues by assignee
+  -c, --context <glob...>        Include files matching glob patterns in context
+  -b, --branch <name>            Use or create a specific branch name
+  --force                        Skip branch confirmation prompts
+  --no-commit                    Disable automatic checkpoint commits
+  --unlimited                    Allow more than 50 iterations
+  --timeout <minutes>            Maximum duration in minutes
+  --allow-delete                 Allow deletion of pre-existing files
+  -n, --max-iterations <number>  Maximum loop iterations (default: "10")
+  --max-tokens <number>          Maximum token budget (default: "100000")
+  -m, --model <model>            Copilot model to use (default: "gpt-4")
+  --dry-run                      Show what would happen without executing
+  -h, --help                     display help for command
+
+Examples:
+  $ ghcralph run --task "Add input validation to the login form"
+  $ ghcralph run --file tasks/refactor.md --max-iterations 5
+  $ ghcralph run --plan TODO.md
+  $ ghcralph run --github owner/repo --label "ralph-ready"
+  $ ghcralph run --task "Fix bug" --context "src/**/*.ts" --branch fix/login-bug
+  $ ghcralph run --task "Large refactor" --unlimited --timeout 60
+
+See also:
+  ghcralph status     View current session progress
+  ghcralph rollback   Undo recent changes
+  ghcralph init       Initialize Ralph in your project
+```
+
+When using GitHub Issues as plan source, it could be useful to have complementary configuration entries in the `.ghcralph` configuration file to define default values for the owner/repo, label, milestone and assignee filters.
+
+### Finding 4: Run parameters should not offer overwriting configuration file values
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --help
+Usage: ghcralph run [options]
+
+Execute an agentic coding loop
+
+Options:
+  -t, --task <description>       Task to execute (inline)
+  -f, --file <path>              Read task from file
+  -p, --plan <path>              Read tasks from a Markdown plan file
+  -g, --github <owner/repo>      Use GitHub Issues as plan source
+  -l, --label <label>            Filter GitHub issues by label
+  --milestone <name>             Filter GitHub issues by milestone
+  --assignee <user>              Filter GitHub issues by assignee
+  -c, --context <glob...>        Include files matching glob patterns in context
+  -b, --branch <name>            Use or create a specific branch name
+  --force                        Skip branch confirmation prompts
+  --no-commit                    Disable automatic checkpoint commits
+  --unlimited                    Allow more than 50 iterations
+  --timeout <minutes>            Maximum duration in minutes
+  --allow-delete                 Allow deletion of pre-existing files
+  -n, --max-iterations <number>  Maximum loop iterations (default: "10")
+  --max-tokens <number>          Maximum token budget (default: "100000")
+  -m, --model <model>            Copilot model to use (default: "gpt-4")
+  --dry-run                      Show what would happen without executing
+  -h, --help                     display help for command
+
+Examples:
+  $ ghcralph run --task "Add input validation to the login form"
+  $ ghcralph run --file tasks/refactor.md --max-iterations 5
+  $ ghcralph run --plan TODO.md
+  $ ghcralph run --github owner/repo --label "ralph-ready"
+  $ ghcralph run --task "Fix bug" --context "src/**/*.ts" --branch fix/login-bug
+  $ ghcralph run --task "Large refactor" --unlimited --timeout 60
+
+See also:
+  ghcralph status     View current session progress
+  ghcralph rollback   Undo recent changes
+  ghcralph init       Initialize Ralph in your project
+```
+
+Some of the parameters available when running `ghcralph run` are already defined in the configuration file created when running `ghcralph init`. To avoid confusion and potential misconfiguration, I would suggest to remove from the `ghcralph run` parameters list any parameter that is already defined in the configuration file, so that the configuration file remains the single source of truth for those values.
+
+This ajustement could be completed by enhancing the documentation to clearly indicate which parameters can be set only via the configuration file and which ones can be set only via command line parameters and also the output of the help command to reflect this distinction.
+
+### Finding 5: Run dry run does present a model different than the one defined in the configuration file
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --plan PLAN.md --dry-run
+ℹ Loaded 11 tasks from PLAN.md
+ℹ Selected task from plan: Create calculator.sh with basic structure
+
+🤖 GitHub Copilot Ralph - Run
+
+  Plan: PLAN.md
+  Task: Create calculator.sh with basic structure
+  Model: gpt-4
+  Max iterations: 10
+  Max tokens: 100,000
+
+⚠ Dry run mode - no changes will be made
+
+Task content:
+Create calculator.sh with basic structure
+
+✔ Dry run complete - no actions taken
+```
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph config list
+
+📋 Ralph Configuration
+
+  planSource: local
+  maxIterations: 10
+  maxTokens: 100000
+  defaultModel: gpt-5.2-codex
+  autoCommit: true
+  branchPrefix: ghcralph/
+```
+
+When running `ghcralph run --dry-run`, the model presented in the summary is `gpt-4`, while the configuration file indicates `gpt-5.2-codex` as the default model. It indicates either the dry run is not reading the configuration file correctly, or the model value is hardcoded in the dry run output or worse is not being used at all by the run command (hypothesis confirmed running run without the dry-run flag).
+
+### Finding 6: First simple run generates an error
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --plan PLAN.md
+ℹ Loaded 11 tasks from PLAN.md
+ℹ Selected task from plan: Create calculator.sh with basic structure
+
+🤖 GitHub Copilot Ralph - Run
+
+  Plan: PLAN.md
+  Task: Create calculator.sh with basic structure
+  Model: gpt-4
+  Max iterations: 10
+  Max tokens: 100,000
+
+⚠ Working directory has 0 modified files and 1 untracked files
+ℹ Use --force to proceed anyway, or commit/stash your changes first
+ℹ Changes stashed automatically
+file:///usr/local/share/npm-global/lib/node_modules/ghcralph/dist/core/git-branch-manager.js:140
+            throw new Error(`Failed to create branch: ${message}`);
+                  ^
+
+Error: Failed to create branch: Command failed: git checkout -b "ralph/task-15-20260125"
+Switched to a new branch 'ralph/task-15-20260125'
+
+This repository is configured for Git LFS but 'git-lfs' was not found on your path. If you no longer wish to use Git LFS, remove this hook by deleting the 'post-checkout' file in the hooks directory (set by 'core.hookspath'; usually '.git/hooks').
+
+
+    at GitBranchManager.createAndSwitchBranch (file:///usr/local/share/npm-global/lib/node_modules/ghcralph/dist/core/git-branch-manager.js:140:19)
+    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
+    at async GitBranchManager.prepareForOperation (file:///usr/local/share/npm-global/lib/node_modules/ghcralph/dist/core/git-branch-manager.js:265:13)
+    at async Command.<anonymous> (file:///usr/local/share/npm-global/lib/node_modules/ghcralph/dist/commands/run.js:272:30)
+
+Node.js v24.12.0
+```
+
+When running `ghcralph run --plan PLAN.md` for the first time in a repository initialized with `ghcralph init`, I get an error related to Git LFS when the CLI tries to create and switch to a new branch for the task execution.
+
+I could potentially fix this adjusting my devcontainer to include Git LFS installation, but I think the CLI should handle this more gracefully, either by checking for Git LFS presence before attempting to create a branch or by providing a clearer error message with guidance on how to resolve the issue or even better not requiring Git LFS at all for basic operations.
+
+If the need for Git LFS for basic operations is not negotiable, it should be documented clearly in the CLI documentation (new markdown file under docs/) to inform users about this prerequisite.
+
+But launching the same command a second time seems to work as expected but end blocked without giving back control to the user forcing to interrupt the process:
+
+```
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (ralph/task-15-20260125) $ ghcralph run --plan PLAN.md
+ℹ Loaded 11 tasks from PLAN.md
+ℹ Selected task from plan: Create calculator.sh with basic structure
+
+🤖 GitHub Copilot Ralph - Run
+
+  Plan: PLAN.md
+  Task: Create calculator.sh with basic structure
+  Model: gpt-4
+  Max iterations: 10
+  Max tokens: 100,000
+
+⚠ Working directory has 0 modified files and 1 untracked files
+ℹ Use --force to proceed anyway, or commit/stash your changes first
+ℹ Changes stashed automatically
+  Branch: ralph/task-15-20260125
+⠴ Running agentic loop...ℹ Copilot agent initialized (model: gpt-4)
+⠼ Running agentic loop...ℹ Executing 2 action(s)...
+ℹ Created: calculator.sh
+ℹ Executing: chmod +x calculator.sh && ./calculator.sh 5 + 3
+ℹ Iteration 1: ✓ (1,099 tokens)
+  [ACTION:CREATE]
+⠇ Running agentic loop...ℹ Executing 1 action(s)...
+ℹ Task complete: calculator.sh created with basic structure including shebang, argument validation, case statement for operations, and addition operation working correctly (tested with 5 + 3 = 8)
+ℹ AI marked task complete: calculator.sh created with basic structure including shebang, argument validation, case statement for operations, and addition operation working correctly (tested with 5 + 3 = 8)
+ℹ Running verification hooks...
+ℹ ✓ All verification hooks passed - task complete!
+ℹ Iteration 2: ✓ (1,301 tokens)
+  Task complete: calculator.sh created with basic structure including shebang, argument validation, case statement for operations, and addition operation working correctly (tested with 5 + 3 = 8)
+
+📊 Summary
+
+  Status: completed
+  Iterations: 2/10
+  Tokens used: 2,400
+  Elapsed time: 18s
+  Successful iterations: 2
+
+ℹ Task marked as complete in plan file
+✔ Loop completed successfully
+^C⚠ Shutdown requested - completing current iteration...
+⚠ No active loop to stop
+node:internal/streams/writable:489
+    err = new ERR_STREAM_DESTROYED('write');
+          ^
+
+Error [ERR_STREAM_DESTROYED]: Cannot call write after a stream was destroyed
+    at _write (node:internal/streams/writable:489:11)
+    at Writable.write (node:internal/streams/writable:508:10)
+    at /usr/local/share/npm-global/lib/node_modules/ghcralph/node_modules/vscode-jsonrpc/lib/node/ril.js:88:29
+    at new Promise (<anonymous>)
+    at WritableStreamWrapper.write (/usr/local/share/npm-global/lib/node_modules/ghcralph/node_modules/vscode-jsonrpc/lib/node/ril.js:78:16)
+    at StreamMessageWriter.doWrite (/usr/local/share/npm-global/lib/node_modules/ghcralph/node_modules/vscode-jsonrpc/lib/common/messageWriter.js:99:33)
+    at /usr/local/share/npm-global/lib/node_modules/ghcralph/node_modules/vscode-jsonrpc/lib/common/messageWriter.js:90:29 {
+  code: 'ERR_STREAM_DESTROYED'
+}
+
+Node.js v24.12.0
+```
+
+This indicates that the run process does not terminate correctly after completing the task, leading to a situation where the user has to manually interrupt the process. The CLI should ensure that it exits gracefully after task completion, returning control to the user without requiring manual intervention.
\ No newline at end of file

From e983f01a32d521cfc7e23042ae3303560b3336f8 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Sun, 25 Jan 2026 19:09:57 +0000
Subject: [PATCH 02/13] Make init interactive by default

---
 JOURNAL.md                      |  20 ++++
 plans/v0-1-0_REFINEMENT_PLAN.md |   2 +-
 src/commands/init.ts            | 181 +++++++++++++++++++++++++++++++-
 3 files changed, 200 insertions(+), 3 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index 40114aa..ce460b3 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1035,6 +1035,26 @@ The Ralph realignment is working! The CLI now:
 
 ## 2026-01-25 - Fix Windows CI test portability
 
+## 2026-01-25 - ghcralph init interactive by default
+
+### Problem
+- `ghcralph init` ran non-interactively by default, writing defaults without confirmation or any chance to change them.
+
+### Root cause
+- `src/commands/init.ts` always wrote the config after computing `planSource`, without any prompt/confirmation flow.
+
+### Fix
+- Added an interactive init flow (TTY only) that:
+  - Shows defaults and asks whether to keep them.
+  - If not, prompts for each configuration entry (with option lists for plan source, model, auto-commit).
+  - Summarizes the final config and asks for confirmation before writing.
+- Keeps non-interactive behavior when stdin/stdout are not TTY or when `--local/--github/--plan-source` are provided.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- Manual smoke check in a temp git repo (interactive + non-interactive)
+
 ## 2026-01-25 - Stabilize Windows checkpoint-manager tests
 
 ### Problem
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 3bc5918..8e0c1dd 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -51,7 +51,7 @@ Same as [the one for the calculator test scenario](../test/integration/calculato
 
 ## Findings
 
-### Finding 1: Init does not provide interactive experience by default
+### Finding 1: Init does not provide interactive experience by default ✅ (Addressed)
 
 ```
 @rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph init
diff --git a/src/commands/init.ts b/src/commands/init.ts
index 1172013..c6b1057 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -5,6 +5,7 @@
  */
 
 import { execSync } from 'node:child_process';
+import { createInterface, type Interface } from 'node:readline/promises';
 import type { Command } from 'commander';
 import { info, success, error, warn, debug, heading, code, dim } from '../utils/index.js';
 import { ConfigManager } from '../core/config-manager.js';
@@ -38,6 +39,77 @@ function getGitRoot(): string | null {
   }
 }
 
+function isInteractiveTerminal(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+async function promptConfirm(
+  rl: Interface,
+  message: string,
+  defaultValue: boolean
+): Promise<boolean> {
+  while (true) {
+    const hint = defaultValue ? 'Y/n' : 'y/N';
+    const answer = (await rl.question(`${message} (${hint}) `)).trim().toLowerCase();
+
+    if (!answer) return defaultValue;
+    if (answer === 'y' || answer === 'yes') return true;
+    if (answer === 'n' || answer === 'no') return false;
+  }
+}
+
+async function promptNumber(rl: Interface, message: string, defaultValue: number): Promise<number> {
+  while (true) {
+    const answer = (await rl.question(`${message} (${defaultValue}) `)).trim();
+    if (!answer) return defaultValue;
+
+    const parsed = parseInt(answer, 10);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+
+    console.log(dim('Please enter a positive number.'));
+  }
+}
+
+async function promptString(rl: Interface, message: string, defaultValue: string): Promise<string> {
+  const answer = (await rl.question(`${message} (${defaultValue}) `)).trim();
+  return answer || defaultValue;
+}
+
+async function promptSelect<T extends string>(
+  rl: Interface,
+  message: string,
+  options: ReadonlyArray<{ label: string; value: T }>,
+  defaultValue: T
+): Promise<T> {
+  const first = options[0];
+  if (!first) {
+    throw new Error(`No options provided for ${message}`);
+  }
+
+  let defaultIndex = options.findIndex(o => o.value === defaultValue);
+  if (defaultIndex < 0) defaultIndex = 0;
+
+  while (true) {
+    console.log('');
+    console.log(dim(`${message}:`));
+    for (const [i, opt] of options.entries()) {
+      const isDefault = i === defaultIndex;
+      console.log(`  ${i + 1}) ${opt.label}${isDefault ? dim(' (default)') : ''}`);
+    }
+
+    const answer = (await rl.question(`${message} [1-${options.length}] `)).trim();
+    if (!answer) {
+      return options[defaultIndex]?.value ?? first.value;
+    }
+
+    const idx = parseInt(answer, 10) - 1;
+    const selected = Number.isInteger(idx) ? options[idx] : undefined;
+    if (selected) return selected.value;
+
+    console.log(dim('Please enter a valid option number.'));
+  }
+}
+
 export interface InitOptions {
   force?: boolean;
   planSource?: PlanSource;
@@ -110,8 +182,113 @@ See also:
       // Update configuration
       configManager.set('planSource', planSource);
 
-      // Initialize local directory and save config
-      const stateDir = await configManager.initLocal();
+      const shouldPrompt =
+        isInteractiveTerminal() &&
+        options.planSource === undefined &&
+        options.github !== true &&
+        options.local !== true;
+
+      let stateDir: string | undefined;
+      try {
+        if (shouldPrompt) {
+          const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+          const current = configManager.getConfig();
+          console.log(dim('Default configuration:'));
+          console.log(`  ${dim('Plan source:')} ${code(current.planSource)}`);
+          console.log(`  ${dim('Max iterations:')} ${current.maxIterations}`);
+          console.log(`  ${dim('Max tokens:')} ${current.maxTokens.toLocaleString()}`);
+          console.log(`  ${dim('Model:')} ${code(current.defaultModel)}`);
+          console.log(`  ${dim('Auto commit:')} ${current.autoCommit}`);
+          console.log(`  ${dim('Branch prefix:')} ${code(current.branchPrefix)}`);
+          console.log('');
+
+          const keepDefaults = await promptConfirm(rl, 'Keep these defaults?', true);
+
+          if (!keepDefaults) {
+            const selectedPlanSource = await promptSelect<PlanSource>(
+              rl,
+              'Plan source',
+              [
+                { label: 'local', value: 'local' },
+                { label: 'github', value: 'github' },
+              ],
+              current.planSource
+            );
+            configManager.set('planSource', selectedPlanSource);
+
+            const maxIterations = await promptNumber(rl, 'Max iterations', current.maxIterations);
+            configManager.set('maxIterations', maxIterations);
+
+            const maxTokens = await promptNumber(rl, 'Max tokens', current.maxTokens);
+            configManager.set('maxTokens', maxTokens);
+
+            const modelOptions = [
+              { label: 'gpt-4.1', value: 'gpt-4.1' },
+              { label: 'gpt-4', value: 'gpt-4' },
+              { label: 'gpt-5', value: 'gpt-5' },
+              { label: 'gpt-5.2-codex', value: 'gpt-5.2-codex' },
+              { label: 'claude-sonnet-4.5', value: 'claude-sonnet-4.5' },
+              { label: 'Custom (enter manually)', value: '__custom__' },
+            ] as const;
+
+            const selectedModel = await promptSelect(
+              rl,
+              'Model',
+              modelOptions,
+              (modelOptions.some(o => o.value === current.defaultModel)
+                ? (current.defaultModel as (typeof modelOptions)[number]['value'])
+                : '__custom__')
+            );
+
+            if (selectedModel === '__custom__') {
+              const customModel = await promptString(rl, 'Custom model', current.defaultModel);
+              configManager.set('defaultModel', customModel);
+            } else {
+              configManager.set('defaultModel', selectedModel);
+            }
+
+            const selectedAutoCommit = await promptSelect<'true' | 'false'>(
+              rl,
+              'Auto commit',
+              [
+                { label: 'true', value: 'true' },
+                { label: 'false', value: 'false' },
+              ],
+              current.autoCommit ? 'true' : 'false'
+            );
+            configManager.set('autoCommit', selectedAutoCommit === 'true');
+
+            const branchPrefix = await promptString(rl, 'Branch prefix', current.branchPrefix);
+            configManager.set('branchPrefix', branchPrefix);
+          }
+
+          const finalConfig = configManager.getConfig();
+          console.log('');
+          console.log(dim('Configuration to write:'));
+          console.log(`  ${dim('Plan source:')} ${code(finalConfig.planSource)}`);
+          console.log(`  ${dim('Max iterations:')} ${finalConfig.maxIterations}`);
+          console.log(`  ${dim('Max tokens:')} ${finalConfig.maxTokens.toLocaleString()}`);
+          console.log(`  ${dim('Model:')} ${code(finalConfig.defaultModel)}`);
+          console.log(`  ${dim('Auto commit:')} ${finalConfig.autoCommit}`);
+          console.log(`  ${dim('Branch prefix:')} ${code(finalConfig.branchPrefix)}`);
+          console.log('');
+
+          const confirmWrite = await promptConfirm(rl, 'Write configuration?', true);
+          rl.close();
+
+          if (!confirmWrite) {
+            info('Initialization cancelled.');
+            return;
+          }
+        }
+
+        // Initialize local directory and save config
+        stateDir = await configManager.initLocal();
+      } catch (e) {
+        error((e as Error).message);
+        process.exit(1);
+      }
 
       // Display configuration
       const config = configManager.getConfig();

From 0852cb5e9404a8fd96fddc2600199a52fee1fbae Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Sun, 25 Jan 2026 19:34:50 +0000
Subject: [PATCH 03/13] Simplify run plan vs file

---
 JOURNAL.md                            | 21 +++++++
 README.md                             |  4 +-
 docs/architecture.md                  |  2 +-
 docs/cookbook.md                      |  4 +-
 plans/v0-1-0_REFINEMENT_PLAN.md       |  2 +-
 src/cli.ts                            |  2 +-
 src/commands/run.ts                   | 83 +++++++++++++++++++++------
 test/integration/calculator/README.md |  2 +-
 8 files changed, 93 insertions(+), 27 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index ce460b3..c7bab2b 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1086,3 +1086,24 @@ The Ralph realignment is working! The CLI now:
 - `npm run lint`
 - `npm run typecheck`
 - `npm test`
+
+## 2026-01-25 - ghcralph run: simplify plan vs file
+
+### Problem
+- The `ghcralph run` command exposed both `--file` (single task file) and `--plan` (Markdown plan file), which is confusing since both point at a file path.
+
+### Root cause
+- `src/commands/run.ts` treated task-from-file and plan-from-file as separate modes requiring different flags, instead of routing by file content/type.
+
+### Fix
+- Made `--file` accept either a single task file or a Markdown plan file (auto-detected via checkbox tasks in Markdown).
+- Kept `--plan` as a **deprecated** option (hidden from help) that forces plan parsing for backward compatibility.
+- Updated docs/examples to prefer `ghcralph run --file PLAN.md`.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- Manual checks:
+  - `node bin/ghcralph.js run --help` no longer shows `--plan`
+  - `node bin/ghcralph.js run --file test/integration/calculator/PLAN.md --dry-run --force` selects a plan task
+  - `node bin/ghcralph.js run --file task.md --dry-run --force` treats a non-plan Markdown file as a one-off task
diff --git a/README.md b/README.md
index 3f7b798..e6289ff 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ ghcralph run --task "Refactor auth middleware to reduce duplication"
 
 ### Run from a local Markdown plan
 ```bash
-ghcralph run --plan TODO.md
+ghcralph run --file TODO.md
 ```
 
 ### Run tasks from GitHub Issues
@@ -144,7 +144,7 @@ ghcralph run --task "Add input validation to the login form"
 ghcralph run --file tasks/add-validation.md
 
 # Tasks from a Markdown plan file
-ghcralph run --plan TODO.md
+ghcralph run --file TODO.md
 
 # Tasks from GitHub Issues
 ghcralph run --github owner/repo --label "ready"
diff --git a/docs/architecture.md b/docs/architecture.md
index 5df30d0..191c1ec 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -116,7 +116,7 @@ sequenceDiagram
     participant SDK as Copilot SDK
     participant API as Copilot API
 
-    User->>CLI: ghcralph run --plan PLAN.md
+    User->>CLI: ghcralph run --file PLAN.md
     
     rect rgb(240, 248, 255)
         Note over CLI,Config: Phase 1: Initialization
diff --git a/docs/cookbook.md b/docs/cookbook.md
index a14d311..1a77ffb 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -59,7 +59,7 @@ ghcralph run --github owner/repo --label "bug"
 ghcralph run --task "Add a dark mode toggle to the settings page"
 
 # Multi-step feature from a plan
-ghcralph run --plan features/user-preferences.md
+ghcralph run --file features/user-preferences.md
 
 # With more iterations for complex features
 ghcralph run --task "Implement user authentication with JWT" \
@@ -203,7 +203,7 @@ ghcralph run --task "Create a CONTRIBUTING.md guide for new contributors"
 ghcralph run --task "Address code review feedback: add error handling to API calls"
 
 # Multiple review items
-ghcralph run --plan pr-feedback.md
+ghcralph run --file pr-feedback.md
 
 # Quick style fixes
 ghcralph run --task "Fix linting issues and apply consistent formatting" \
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 8e0c1dd..204946d 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -84,7 +84,7 @@ To enhance the user experience, I would suggest to add an interactive mode by de
 
 For Plan Source, Model (list of models available using GitHub Copilot CLI) and Auto commit, please provide a list of options to choose from.
 
-### Finding 2: Run file and plan parameters confusing
+### Finding 2: Run file and plan parameters confusing ✅ (Addressed)
 
 ```
 @rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --help
diff --git a/src/cli.ts b/src/cli.ts
index fa05a1d..123ea09 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -33,7 +33,7 @@ program
 ${dim('Examples:')}
   $ ghcralph init                          # Initialize GitHub Copilot Ralph in your project
   $ ghcralph run --task "Add tests"        # Run a coding loop for a task
-  $ ghcralph run --plan TODO.md            # Execute tasks from a plan file
+  $ ghcralph run --file TODO.md            # Execute tasks from a plan file
   $ ghcralph run --github owner/repo       # Work through GitHub Issues
   $ ghcralph status                        # Check current session status
   $ ghcralph rollback --iterations 2       # Undo last 2 iterations
diff --git a/src/commands/run.ts b/src/commands/run.ts
index 9a76f06..c156b02 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -5,7 +5,8 @@
  */
 
 import fs from 'node:fs/promises';
-import type { Command } from 'commander';
+import path from 'node:path';
+import { Option, type Command } from 'commander';
 import { info, success, error, warn, debug, spinner, heading, code, dim, parsePositiveInt, parseNonNegativeInt } from '../utils/index.js';
 import { CopilotAgent } from '../integrations/index.js';
 import {
@@ -67,6 +68,10 @@ async function readTaskFromFile(filePath: string): Promise<string> {
   }
 }
 
+function looksLikeMarkdownPlan(content: string): boolean {
+  return /^\s*-\s*\[[ xX]\]\s+.+$/m.test(content);
+}
+
 /**
  * Create a task object from options
  */
@@ -119,8 +124,8 @@ export function registerRunCommand(program: Command): void {
     .command('run')
     .description('Execute an agentic coding loop')
     .option('-t, --task <description>', 'Task to execute (inline)')
-    .option('-f, --file <path>', 'Read task from file')
-    .option('-p, --plan <path>', 'Read tasks from a Markdown plan file')
+    .option('-f, --file <path>', 'Read task (or Markdown plan) from file')
+    .addOption(new Option('-p, --plan <path>', 'Read tasks from a Markdown plan file (deprecated; use --file)').hideHelp())
     .option('-g, --github <owner/repo>', 'Use GitHub Issues as plan source')
     .option('-l, --label <label>', 'Filter GitHub issues by label')
     .option('--milestone <name>', 'Filter GitHub issues by milestone')
@@ -140,7 +145,7 @@ export function registerRunCommand(program: Command): void {
 Examples:
   $ ghcralph run --task "Add input validation to the login form"
   $ ghcralph run --file tasks/refactor.md --max-iterations 5
-  $ ghcralph run --plan TODO.md
+  $ ghcralph run --file TODO.md
   $ ghcralph run --github owner/repo --label "ralph-ready"
   $ ghcralph run --task "Fix bug" --context "src/**/*.ts" --branch fix/login-bug
   $ ghcralph run --task "Large refactor" --unlimited --timeout 60
@@ -152,7 +157,12 @@ See also:
 `)
     .action(async (options: RunOptions) => {
       if (!options.task && !options.file && !options.plan && !options.github) {
-        error('Please provide a task with --task, --file, --plan, or --github');
+        error('Please provide a task with --task, --file, or --github');
+        process.exit(1);
+      }
+
+      if (options.plan && options.file) {
+        error('Please provide only one of --file or --plan');
         process.exit(1);
       }
 
@@ -205,6 +215,7 @@ See also:
       // Create task - either from options or from plan source
       let task: Task;
       let planManager: PlanManager | null = null;
+      let planFilePath: string | undefined;
 
       try {
         if (options.github) {
@@ -245,19 +256,53 @@ See also:
           task = nextTask;
           await planManager.startTask(task.id);
           info(`Selected issue from GitHub: ${task.title}`);
-        } else if (options.plan) {
-          // Load task from Markdown plan file
-          planManager = new LocalMarkdownPlan(options.plan);
-          await planManager.initialize();
-          const nextTask = await planManager.getNextTask();
-          if (!nextTask) {
-            success('All tasks in the plan are complete!');
-            return;
-          }
-          task = nextTask;
-          info(`Selected task from plan: ${task.title}`);
         } else {
-          task = await createTask(options);
+          const fileArg = options.plan ?? options.file;
+          const forcePlan = options.plan !== undefined;
+
+          if (fileArg) {
+            // If user explicitly used --plan, always treat as plan.
+            // Otherwise, auto-detect Markdown plan files by the presence of task checkboxes.
+            if (forcePlan) {
+              planManager = new LocalMarkdownPlan(fileArg);
+              planFilePath = fileArg;
+              await planManager.initialize();
+              const nextTask = await planManager.getNextTask();
+              if (!nextTask) {
+                success('All tasks in the plan are complete!');
+                return;
+              }
+              task = nextTask;
+              info(`Selected task from plan: ${task.title}`);
+            } else {
+              const content = await readTaskFromFile(fileArg);
+              const ext = path.extname(fileArg).toLowerCase();
+              const isMarkdown = ext === '.md' || ext === '.markdown';
+
+              if (isMarkdown && looksLikeMarkdownPlan(content)) {
+                planManager = new LocalMarkdownPlan(fileArg);
+                planFilePath = fileArg;
+                await planManager.initialize();
+                const nextTask = await planManager.getNextTask();
+                if (!nextTask) {
+                  success('All tasks in the plan are complete!');
+                  return;
+                }
+                task = nextTask;
+                info(`Selected task from plan: ${task.title}`);
+              } else {
+                task = {
+                  id: `task-${Date.now()}`,
+                  title: fileArg,
+                  content,
+                  status: 'pending',
+                  source: 'local',
+                };
+              }
+            }
+          } else {
+            task = await createTask(options);
+          }
         }
       } catch (err) {
         error(err instanceof Error ? err.message : String(err));
@@ -273,8 +318,8 @@ See also:
         if (options.label) {
           console.log(`  ${dim('Label filter:')} ${code(options.label)}`);
         }
-      } else if (options.plan) {
-        console.log(`  ${dim('Plan:')} ${code(options.plan)}`);
+      } else if (planFilePath) {
+        console.log(`  ${dim('Plan:')} ${code(planFilePath)}`);
       }
       console.log(`  ${dim('Task:')} ${task.title}`);
       console.log(`  ${dim('Model:')} ${code(options.model ?? 'gpt-4')}`);
diff --git a/test/integration/calculator/README.md b/test/integration/calculator/README.md
index af78bc5..d96e3aa 100644
--- a/test/integration/calculator/README.md
+++ b/test/integration/calculator/README.md
@@ -42,7 +42,7 @@ node ../../../bin/ghcralph.js init --local
 
 ```bash
 # Execute the plan to create calculator.sh
-node ../../../bin/ghcralph.js run --plan PLAN.md --force
+node ../../../bin/ghcralph.js run --file PLAN.md --force
 ```
 
 ### Step 4: Validate the output

From 80dd52099f0f6d89486efbdfc93399d2cd57751a Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Sun, 25 Jan 2026 20:14:04 +0000
Subject: [PATCH 04/13] Add GitHub issue defaults to config

---
 JOURNAL.md                      | 20 ++++++++++
 README.md                       | 12 +++++-
 plans/v0-1-0_REFINEMENT_PLAN.md |  2 +-
 src/commands/config.ts          |  2 +-
 src/commands/run.ts             | 69 +++++++++++++++++++++++++++------
 src/core/config-manager.ts      |  3 ++
 src/core/config-schema.test.ts  |  9 +++++
 src/core/config-schema.ts       | 12 ++++++
 8 files changed, 115 insertions(+), 14 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index c7bab2b..f66df78 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1087,6 +1087,26 @@ The Ralph realignment is working! The CLI now:
 - `npm run typecheck`
 - `npm test`
 
+## 2026-01-25 - ghcralph run: GitHub defaults via config
+
+### Problem
+- When using `ghcralph run --github`, users had to provide `owner/repo` and filters every time.
+
+### Root cause
+- `src/commands/run.ts` did not load `.ghcralph/config.json` / `GHCRALPH_*` defaults for GitHub repo and issue filters.
+
+### Fix
+- Added config keys: `githubLabel`, `githubMilestone`, `githubAssignee` (plus env vars `GHCRALPH_GITHUB_LABEL`, `GHCRALPH_GITHUB_MILESTONE`, `GHCRALPH_GITHUB_ASSIGNEE`).
+- Updated `ghcralph run --github` to accept an optional repo argument and fall back to configured `githubRepo` and default filters.
+- Updated docs and `ghcralph config set` help to include the new keys.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- Manual checks:
+  - `node bin/ghcralph.js run --help` shows `--github [owner/repo]`
+  - `node bin/ghcralph.js run --github --dry-run --force` exits with code 1 when no repo is configured
+
 ## 2026-01-25 - ghcralph run: simplify plan vs file
 
 ### Problem
diff --git a/README.md b/README.md
index e6289ff..995dba9 100644
--- a/README.md
+++ b/README.md
@@ -192,6 +192,9 @@ GitHub Copilot Ralph uses a hierarchical configuration system:
 | `autoCommit`    | `true`      | Auto-commit after iterations                          |
 | `branchPrefix`  | `ghcralph/` | Prefix for GitHub Copilot Ralph branches              |
 | `githubRepo`    | -           | GitHub repository (owner/repo) for GitHub plan source |
+| `githubLabel`   | -           | Default GitHub issue label filter for GitHub plan      |
+| `githubMilestone` | -         | Default GitHub issue milestone filter for GitHub plan  |
+| `githubAssignee` | -          | Default GitHub issue assignee filter for GitHub plan   |
 | `localPlanFile` | -           | Path to local plan file                               |
 
 ### Environment Variables
@@ -205,6 +208,10 @@ export GHCRALPH_DEFAULT_MODEL=gpt-4.1
 export GHCRALPH_AUTO_COMMIT=true
 export GHCRALPH_BRANCH_PREFIX=ghcralph/
 export GHCRALPH_PLAN_SOURCE=local
+export GHCRALPH_GITHUB_REPO=owner/repo
+export GHCRALPH_GITHUB_LABEL=ralph-ready
+export GHCRALPH_GITHUB_MILESTONE=v1.0
+export GHCRALPH_GITHUB_ASSIGNEE=octocat
 ```
 
 ### Example Configuration File
@@ -217,7 +224,10 @@ export GHCRALPH_PLAN_SOURCE=local
   "defaultModel": "gpt-4.1",
   "autoCommit": true,
   "branchPrefix": "ghcralph/",
-  "githubRepo": "owner/repo"
+  "githubRepo": "owner/repo",
+  "githubLabel": "ralph-ready",
+  "githubMilestone": "v1.0",
+  "githubAssignee": "octocat"
 }
 ```
 
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 204946d..9d9d095 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -129,7 +129,7 @@ See also:
 
 I think the `--file` and `--plan` parameters are a bit confusing as they both refer to a file containing a plan, but with different formats. If we want to support different file formats (exemple md and json), the processing could be dynamically routed based on the file extension rather than having separate parameters.
 
-### Finding 3: Run could benefit from complementay configuration entries for GitHub Issues plan source
+### Finding 3: Run could benefit from complementay configuration entries for GitHub Issues plan source ✅ (Addressed)
 
 ```
 @rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --help
diff --git a/src/commands/config.ts b/src/commands/config.ts
index dd05b51..0cb5b00 100644
--- a/src/commands/config.ts
+++ b/src/commands/config.ts
@@ -61,7 +61,7 @@ export function registerConfigCommand(program: Command): void {
       if (!isValidConfigKey(key)) {
         error(`Unknown configuration key: ${key}`);
         info(
-          `Valid keys: ${code('planSource, maxIterations, maxTokens, defaultModel, autoCommit, branchPrefix, githubRepo, localPlanFile')}`
+          `Valid keys: ${code('planSource, maxIterations, maxTokens, defaultModel, autoCommit, branchPrefix, githubRepo, githubLabel, githubMilestone, githubAssignee, localPlanFile')}`
         );
         process.exit(1);
       }
diff --git a/src/commands/run.ts b/src/commands/run.ts
index c156b02..a69723c 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -6,6 +6,7 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { execSync } from 'node:child_process';
 import { Option, type Command } from 'commander';
 import { info, success, error, warn, debug, spinner, heading, code, dim, parsePositiveInt, parseNonNegativeInt } from '../utils/index.js';
 import { CopilotAgent } from '../integrations/index.js';
@@ -17,6 +18,7 @@ import {
   GitBranchManager,
   CheckpointManager,
   FileSafeguardManager,
+  ConfigManager,
   type PlanManager,
 } from '../core/index.js';
 import type { Task } from '../types/index.js';
@@ -25,7 +27,7 @@ export interface RunOptions {
   task?: string;
   file?: string;
   plan?: string;
-  github?: string;
+  github?: string | boolean;
   label?: string;
   milestone?: string;
   assignee?: string;
@@ -72,6 +74,17 @@ function looksLikeMarkdownPlan(content: string): boolean {
   return /^\s*-\s*\[[ xX]\]\s+.+$/m.test(content);
 }
 
+function getGitRoot(): string | null {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Create a task object from options
  */
@@ -126,7 +139,7 @@ export function registerRunCommand(program: Command): void {
     .option('-t, --task <description>', 'Task to execute (inline)')
     .option('-f, --file <path>', 'Read task (or Markdown plan) from file')
     .addOption(new Option('-p, --plan <path>', 'Read tasks from a Markdown plan file (deprecated; use --file)').hideHelp())
-    .option('-g, --github <owner/repo>', 'Use GitHub Issues as plan source')
+    .option('-g, --github [owner/repo]', 'Use GitHub Issues as plan source (defaults from config)')
     .option('-l, --label <label>', 'Filter GitHub issues by label')
     .option('--milestone <name>', 'Filter GitHub issues by milestone')
     .option('--assignee <user>', 'Filter GitHub issues by assignee')
@@ -212,15 +225,43 @@ See also:
         process.exit(1);
       }
 
+      let githubRepo: string | undefined;
+      let githubLabel: string | undefined;
+      let githubMilestone: string | undefined;
+      let githubAssignee: string | undefined;
+
+      if (options.github) {
+        const gitRoot = getGitRoot();
+        const configManager = new ConfigManager(gitRoot ?? undefined);
+        const config = await configManager.load({
+          ...(typeof options.github === 'string' ? { githubRepo: options.github } : {}),
+          ...(options.label ? { githubLabel: options.label } : {}),
+          ...(options.milestone ? { githubMilestone: options.milestone } : {}),
+          ...(options.assignee ? { githubAssignee: options.assignee } : {}),
+        });
+
+        githubRepo = typeof options.github === 'string' ? options.github : config.githubRepo;
+        if (!githubRepo) {
+          error(
+            'Missing GitHub repository. Provide --github <owner/repo> or set githubRepo in .ghcralph/config.json (or GHCRALPH_GITHUB_REPO)'
+          );
+          process.exit(1);
+        }
+
+        githubLabel = config.githubLabel;
+        githubMilestone = config.githubMilestone;
+        githubAssignee = config.githubAssignee;
+      }
+
       // Create task - either from options or from plan source
       let task: Task;
       let planManager: PlanManager | null = null;
       let planFilePath: string | undefined;
 
       try {
-        if (options.github) {
+        if (githubRepo) {
           // Parse owner/repo
-          const parts = options.github.split('/');
+          const parts = githubRepo.split('/');
           if (parts.length !== 2) {
             error('GitHub repository must be in format: owner/repo');
             process.exit(1);
@@ -242,9 +283,9 @@ See also:
             owner,
             repo,
           };
-          if (options.label) ghConfig.label = options.label;
-          if (options.milestone) ghConfig.milestone = options.milestone;
-          if (options.assignee) ghConfig.assignee = options.assignee;
+          if (githubLabel) ghConfig.label = githubLabel;
+          if (githubMilestone) ghConfig.milestone = githubMilestone;
+          if (githubAssignee) ghConfig.assignee = githubAssignee;
 
           planManager = new GitHubPlan(ghConfig);
           await planManager.initialize();
@@ -313,10 +354,16 @@ See also:
       console.log('');
       console.log(heading('🤖 GitHub Copilot Ralph - Run'));
       console.log('');
-      if (options.github) {
-        console.log(`  ${dim('Source:')} GitHub Issues (${code(options.github)})`);
-        if (options.label) {
-          console.log(`  ${dim('Label filter:')} ${code(options.label)}`);
+      if (githubRepo) {
+        console.log(`  ${dim('Source:')} GitHub Issues (${code(githubRepo)})`);
+        if (githubLabel) {
+          console.log(`  ${dim('Label filter:')} ${code(githubLabel)}`);
+        }
+        if (githubMilestone) {
+          console.log(`  ${dim('Milestone filter:')} ${code(githubMilestone)}`);
+        }
+        if (githubAssignee) {
+          console.log(`  ${dim('Assignee filter:')} ${code(githubAssignee)}`);
         }
       } else if (planFilePath) {
         console.log(`  ${dim('Plan:')} ${code(planFilePath)}`);
diff --git a/src/core/config-manager.ts b/src/core/config-manager.ts
index 99663d3..c4222ab 100644
--- a/src/core/config-manager.ts
+++ b/src/core/config-manager.ts
@@ -66,6 +66,9 @@ function loadEnvConfig(): Partial<RalphConfiguration> {
     [`${ENV_PREFIX}AUTO_COMMIT`]: 'autoCommit',
     [`${ENV_PREFIX}BRANCH_PREFIX`]: 'branchPrefix',
     [`${ENV_PREFIX}GITHUB_REPO`]: 'githubRepo',
+    [`${ENV_PREFIX}GITHUB_LABEL`]: 'githubLabel',
+    [`${ENV_PREFIX}GITHUB_MILESTONE`]: 'githubMilestone',
+    [`${ENV_PREFIX}GITHUB_ASSIGNEE`]: 'githubAssignee',
     [`${ENV_PREFIX}LOCAL_PLAN_FILE`]: 'localPlanFile',
   };
 
diff --git a/src/core/config-schema.test.ts b/src/core/config-schema.test.ts
index b277fb0..aaa0c3f 100644
--- a/src/core/config-schema.test.ts
+++ b/src/core/config-schema.test.ts
@@ -33,6 +33,9 @@ describe('Config Schema', () => {
       expect(isValidConfigKey('autoCommit')).toBe(true);
       expect(isValidConfigKey('branchPrefix')).toBe(true);
       expect(isValidConfigKey('githubRepo')).toBe(true);
+      expect(isValidConfigKey('githubLabel')).toBe(true);
+      expect(isValidConfigKey('githubMilestone')).toBe(true);
+      expect(isValidConfigKey('githubAssignee')).toBe(true);
       expect(isValidConfigKey('mcpServers')).toBe(true);
     });
 
@@ -70,6 +73,9 @@ describe('Config Schema', () => {
       expect(validateConfigValue('defaultModel', 'gpt-4.1').valid).toBe(true);
       expect(validateConfigValue('branchPrefix', 'feature/').valid).toBe(true);
       expect(validateConfigValue('githubRepo', 'owner/repo').valid).toBe(true);
+      expect(validateConfigValue('githubLabel', 'my-label').valid).toBe(true);
+      expect(validateConfigValue('githubMilestone', 'v1.0').valid).toBe(true);
+      expect(validateConfigValue('githubAssignee', 'octocat').valid).toBe(true);
       expect(validateConfigValue('defaultModel', 123 as unknown as string).valid).toBe(false);
     });
   });
@@ -103,6 +109,9 @@ describe('Config Schema', () => {
         'autoCommit',
         'branchPrefix',
         'githubRepo',
+        'githubLabel',
+        'githubMilestone',
+        'githubAssignee',
         'localPlanFile',
         'promptTemplate',
         'mcpServers',
diff --git a/src/core/config-schema.ts b/src/core/config-schema.ts
index deb9e21..f17c48a 100644
--- a/src/core/config-schema.ts
+++ b/src/core/config-schema.ts
@@ -43,6 +43,12 @@ export interface RalphConfiguration {
   branchPrefix: string;
   /** GitHub repository (owner/repo) for GitHub plan source */
   githubRepo?: string;
+  /** Default GitHub issue label filter for GitHub plan source */
+  githubLabel?: string;
+  /** Default GitHub issue milestone filter for GitHub plan source */
+  githubMilestone?: string;
+  /** Default GitHub issue assignee filter for GitHub plan source */
+  githubAssignee?: string;
   /** Local plan file path for local plan source */
   localPlanFile?: string;
   /** Custom prompt template */
@@ -74,6 +80,9 @@ export const CONFIG_KEYS = [
   'autoCommit',
   'branchPrefix',
   'githubRepo',
+  'githubLabel',
+  'githubMilestone',
+  'githubAssignee',
   'localPlanFile',
   'promptTemplate',
   'mcpServers',
@@ -115,6 +124,9 @@ export function validateConfigValue(
     case 'defaultModel':
     case 'branchPrefix':
     case 'githubRepo':
+    case 'githubLabel':
+    case 'githubMilestone':
+    case 'githubAssignee':
     case 'localPlanFile':
       if (typeof value !== 'string') {
         return { valid: false, error: `${key} must be a string` };

From 1200787a3f4c7d7018c5b91fdf9b576a7787db93 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Sun, 25 Jan 2026 20:38:11 +0000
Subject: [PATCH 05/13] Make run config authoritative

---
 JOURNAL.md                      | 21 +++++++++
 README.md                       | 13 +++---
 docs/cookbook.md                | 17 ++++---
 plans/v0-1-0_REFINEMENT_PLAN.md |  2 +-
 src/commands/run.ts             | 79 +++++++++------------------------
 5 files changed, 60 insertions(+), 72 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index f66df78..e078256 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1109,6 +1109,27 @@ The Ralph realignment is working! The CLI now:
 
 ## 2026-01-25 - ghcralph run: simplify plan vs file
 
+## 2026-01-25 - ghcralph run: config is the source of truth
+
+### Problem
+- `ghcralph run` exposed CLI flags (`--max-iterations`, `--max-tokens`, `--model`, `--no-commit`, and GitHub repo/filters) that overlap with config keys, making it unclear which values are authoritative.
+
+### Root cause
+- `src/commands/run.ts` hardcoded defaults and accepted per-run overrides instead of consistently loading `.ghcralph/config.json` / `GHCRALPH_*` and using those values.
+
+### Fix
+- Updated `ghcralph run` to load configuration at startup and use it for:
+  - `maxIterations`, `maxTokens`, `defaultModel`, `autoCommit`, `branchPrefix`
+  - GitHub plan source repo + default filters (`githubRepo`, `githubLabel`, `githubMilestone`, `githubAssignee`)
+- Removed config-backed overrides from the `run` command options and help output.
+- Updated README and cookbook examples to show configuring these values via `.ghcralph/config.json` instead of CLI flags.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- `npm run build`
+- Manual check: `node bin/ghcralph.js run --help` no longer lists config-backed override flags
+
 ### Problem
 - The `ghcralph run` command exposed both `--file` (single task file) and `--plan` (Markdown plan file), which is confusing since both point at a file path.
 
diff --git a/README.md b/README.md
index 995dba9..714fbb4 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,8 @@ ghcralph run --file TODO.md
 ### Run tasks from GitHub Issues
 ```bash
 ghcralph init --github
-ghcralph run --github owner/repo --label "ready"
+# Configure githubRepo (and optional filters) via .ghcralph/config.json
+ghcralph run --github
 ```
 
 ## Usage
@@ -146,15 +147,15 @@ ghcralph run --file tasks/add-validation.md
 # Tasks from a Markdown plan file
 ghcralph run --file TODO.md
 
-# Tasks from GitHub Issues
-ghcralph run --github owner/repo --label "ready"
+# Tasks from GitHub Issues (configured via .ghcralph/config.json)
+ghcralph run --github
 ```
 
 ### Advanced Run Options
 
 ```bash
-# Control iterations and tokens
-ghcralph run --task "Refactor auth" --max-iterations 20 --max-tokens 50000
+# Control iterations, tokens, and model via configuration
+# (set maxIterations / maxTokens / defaultModel in .ghcralph/config.json)
 
 # Specify context files
 ghcralph run --task "Fix tests" --context "src/**/*.test.ts"
@@ -298,7 +299,7 @@ gh auth login
 ```
 
 ### "Maximum iterations reached"
-Increase the limit: `--max-iterations 20`  
+Increase the limit: set `maxIterations` in `.ghcralph/config.json` (or `GHCRALPH_MAX_ITERATIONS`).  
 Or for very long tasks: `--unlimited`
 
 ### Progress seems stuck
diff --git a/docs/cookbook.md b/docs/cookbook.md
index 1a77ffb..26aa452 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -29,15 +29,15 @@ ghcralph run --task "Fix the login button not responding on mobile devices"
 ghcralph run --task "Fix issue #42: Form validation fails for email addresses" \
   --context "src/components/Form*.tsx" "src/utils/validation.ts"
 
-# From a GitHub issue
-ghcralph run --github owner/repo --label "bug"
+# From a GitHub issue (configured via .ghcralph/config.json)
+ghcralph run --github
 ```
 
 ### Tips for Success
 
 1. **Be specific about the bug**: Include error messages, reproduction steps
 2. **Provide context files**: Point Ralph to relevant code with `--context`
-3. **Start with low iterations**: `--max-iterations 5` for simple bugs
+3. **Start with low iterations**: set `maxIterations` in `.ghcralph/config.json` for simple bugs
 4. **Check after each iteration**: Use `ghcralph status` to monitor progress
 
 ### Common Pitfalls
@@ -62,8 +62,8 @@ ghcralph run --task "Add a dark mode toggle to the settings page"
 ghcralph run --file features/user-preferences.md
 
 # With more iterations for complex features
+# (set maxIterations in .ghcralph/config.json)
 ghcralph run --task "Implement user authentication with JWT" \
-  --max-iterations 15 \
   --context "src/auth/**/*.ts"
 ```
 
@@ -206,8 +206,9 @@ ghcralph run --task "Address code review feedback: add error handling to API cal
 ghcralph run --file pr-feedback.md
 
 # Quick style fixes
+# (set maxIterations in .ghcralph/config.json)
 ghcralph run --task "Fix linting issues and apply consistent formatting" \
-  --max-iterations 3
+  --context "src/**/*.{ts,tsx,js}"
 ```
 
 ### Example PR Feedback Plan
@@ -249,7 +250,8 @@ ghcralph rollback --iterations 1
 
 ```bash
 # Increase budget for next run
-ghcralph run --task "Continue previous work" --max-tokens 200000
+# (set maxTokens in .ghcralph/config.json)
+ghcralph run --task "Continue previous work"
 
 # Or break task into smaller pieces
 ```
@@ -261,7 +263,8 @@ ghcralph run --task "Continue previous work" --max-tokens 200000
 ghcralph run --task "Large refactor" --unlimited --timeout 60
 
 # Or increase iteration limit
-ghcralph run --task "..." --max-iterations 30
+# (set maxIterations in .ghcralph/config.json)
+ghcralph run --task "..."
 ```
 
 ### Changes not what I expected
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 9d9d095..4b92536 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -174,7 +174,7 @@ See also:
 
 When using GitHub Issues as plan source, it could be useful to have complementary configuration entries in the `.ghcralph` configuration file to define default values for the owner/repo, label, milestone and assignee filters.
 
-### Finding 4: Run parameters should not offer overwriting configuration file values
+### Finding 4: Run parameters should not offer overwriting configuration file values ✅ (Addressed)
 
 ```
 @rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --help
diff --git a/src/commands/run.ts b/src/commands/run.ts
index a69723c..436a7fd 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -8,7 +8,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { Option, type Command } from 'commander';
-import { info, success, error, warn, debug, spinner, heading, code, dim, parsePositiveInt, parseNonNegativeInt } from '../utils/index.js';
+import { info, success, error, warn, debug, spinner, heading, code, dim, parseNonNegativeInt } from '../utils/index.js';
 import { CopilotAgent } from '../integrations/index.js';
 import {
   LoopEngine,
@@ -27,20 +27,13 @@ export interface RunOptions {
   task?: string;
   file?: string;
   plan?: string;
-  github?: string | boolean;
-  label?: string;
-  milestone?: string;
-  assignee?: string;
+  github?: boolean;
   context?: string[];
   branch?: string;
   force?: boolean;
-  noCommit?: boolean;
   unlimited?: boolean;
   timeout?: string;
   allowDelete?: boolean;
-  maxIterations: string;
-  maxTokens?: string;
-  model?: string;
   dryRun?: boolean;
 }
 
@@ -139,27 +132,24 @@ export function registerRunCommand(program: Command): void {
     .option('-t, --task <description>', 'Task to execute (inline)')
     .option('-f, --file <path>', 'Read task (or Markdown plan) from file')
     .addOption(new Option('-p, --plan <path>', 'Read tasks from a Markdown plan file (deprecated; use --file)').hideHelp())
-    .option('-g, --github [owner/repo]', 'Use GitHub Issues as plan source (defaults from config)')
-    .option('-l, --label <label>', 'Filter GitHub issues by label')
-    .option('--milestone <name>', 'Filter GitHub issues by milestone')
-    .option('--assignee <user>', 'Filter GitHub issues by assignee')
+    .option('-g, --github', 'Use GitHub Issues as plan source (configured via .ghcralph/config.json)')
     .option('-c, --context <glob...>', 'Include files matching glob patterns in context')
     .option('-b, --branch <name>', 'Use or create a specific branch name')
     .option('--force', 'Skip branch confirmation prompts')
-    .option('--no-commit', 'Disable automatic checkpoint commits')
     .option('--unlimited', 'Allow more than 50 iterations')
     .option('--timeout <minutes>', 'Maximum duration in minutes')
     .option('--allow-delete', 'Allow deletion of pre-existing files')
-    .option('-n, --max-iterations <number>', 'Maximum loop iterations', '10')
-    .option('--max-tokens <number>', 'Maximum token budget', '100000')
-    .option('-m, --model <model>', 'Copilot model to use', 'gpt-4')
     .option('--dry-run', 'Show what would happen without executing')
     .addHelpText('after', `
+Config-backed settings (set via .ghcralph/config.json or GHCRALPH_* env vars):
+  - maxIterations, maxTokens, defaultModel, autoCommit, branchPrefix
+  - githubRepo (+ optional filters: githubLabel, githubMilestone, githubAssignee)
+
 Examples:
   $ ghcralph run --task "Add input validation to the login form"
-  $ ghcralph run --file tasks/refactor.md --max-iterations 5
+  $ ghcralph run --file tasks/refactor.md
   $ ghcralph run --file TODO.md
-  $ ghcralph run --github owner/repo --label "ralph-ready"
+  $ ghcralph run --github
   $ ghcralph run --task "Fix bug" --context "src/**/*.ts" --branch fix/login-bug
   $ ghcralph run --task "Large refactor" --unlimited --timeout 60
 
@@ -179,31 +169,13 @@ See also:
         process.exit(1);
       }
 
-      // Validate numeric inputs
-      const maxIterationsResult = parsePositiveInt(options.maxIterations, 'max-iterations');
-      if (!maxIterationsResult.valid) {
-        error(maxIterationsResult.error ?? 'Invalid max-iterations value');
-        process.exit(1);
-      }
-      if (maxIterationsResult.value === undefined) {
-        error(maxIterationsResult.error ?? 'Invalid max-iterations value');
-        process.exit(1);
-      }
-      const maxIterations = maxIterationsResult.value;
+      const gitRoot = getGitRoot();
+      const configManager = new ConfigManager(gitRoot ?? undefined);
+      const config = await configManager.load();
 
-      let maxTokens = 100000;
-      if (options.maxTokens) {
-        const maxTokensResult = parsePositiveInt(options.maxTokens, 'max-tokens');
-        if (!maxTokensResult.valid) {
-          error(maxTokensResult.error ?? 'Invalid max-tokens value');
-          process.exit(1);
-        }
-        if (maxTokensResult.value === undefined) {
-          error(maxTokensResult.error ?? 'Invalid max-tokens value');
-          process.exit(1);
-        }
-        maxTokens = maxTokensResult.value;
-      }
+      const maxIterations = config.maxIterations;
+      const maxTokens = config.maxTokens;
+      const model = config.defaultModel;
 
       let maxDurationMinutes = 0;
       if (options.timeout) {
@@ -231,19 +203,10 @@ See also:
       let githubAssignee: string | undefined;
 
       if (options.github) {
-        const gitRoot = getGitRoot();
-        const configManager = new ConfigManager(gitRoot ?? undefined);
-        const config = await configManager.load({
-          ...(typeof options.github === 'string' ? { githubRepo: options.github } : {}),
-          ...(options.label ? { githubLabel: options.label } : {}),
-          ...(options.milestone ? { githubMilestone: options.milestone } : {}),
-          ...(options.assignee ? { githubAssignee: options.assignee } : {}),
-        });
-
-        githubRepo = typeof options.github === 'string' ? options.github : config.githubRepo;
+        githubRepo = config.githubRepo;
         if (!githubRepo) {
           error(
-            'Missing GitHub repository. Provide --github <owner/repo> or set githubRepo in .ghcralph/config.json (or GHCRALPH_GITHUB_REPO)'
+            'Missing GitHub repository. Set githubRepo in .ghcralph/config.json (or GHCRALPH_GITHUB_REPO)'
           );
           process.exit(1);
         }
@@ -369,7 +332,7 @@ See also:
         console.log(`  ${dim('Plan:')} ${code(planFilePath)}`);
       }
       console.log(`  ${dim('Task:')} ${task.title}`);
-      console.log(`  ${dim('Model:')} ${code(options.model ?? 'gpt-4')}`);
+      console.log(`  ${dim('Model:')} ${code(model)}`);
       console.log(`  ${dim('Max iterations:')} ${maxIterations}`);
       console.log(`  ${dim('Max tokens:')} ${maxTokens.toLocaleString()}`);
 
@@ -387,7 +350,7 @@ See also:
       console.log('');
 
       // Setup git branch isolation
-      const gitManager = new GitBranchManager();
+      const gitManager = new GitBranchManager({ branchPrefix: config.branchPrefix });
       const isGitRepo = await gitManager.isGitRepository();
       let branchInfo: { branchName: string; created: boolean; originalBranch: string } | null = null;
 
@@ -439,7 +402,7 @@ See also:
 
       // Create agent and engine with context configuration
       const agent = new CopilotAgent({
-        model: options.model ?? 'gpt-4',
+        model,
         maxTokensPerRequest: 4096,
       });
 
@@ -471,7 +434,7 @@ See also:
 
       // Create checkpoint manager for auto-commits
       const checkpointManager = new CheckpointManager({
-        autoCommit: options.noCommit !== true,
+        autoCommit: config.autoCommit,
       });
 
       // Create file safeguard manager

From b4b890bf646e3550ecd86584cf42404904c3f5d5 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Sun, 25 Jan 2026 20:57:21 +0000
Subject: [PATCH 06/13] Remove run --plan option

---
 JOURNAL.md                      | 16 +++++++++-
 plans/v0-1-0_REFINEMENT_PLAN.md |  4 ++-
 src/commands/run.ts             | 53 ++++++++++-----------------------
 3 files changed, 33 insertions(+), 40 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index e078256..2bedef0 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1145,6 +1145,20 @@ The Ralph realignment is working! The CLI now:
 - `npm run typecheck`
 - `npm test`
 - Manual checks:
-  - `node bin/ghcralph.js run --help` no longer shows `--plan`
+  - `node bin/ghcralph.js run --help` does not show `--plan`
   - `node bin/ghcralph.js run --file test/integration/calculator/PLAN.md --dry-run --force` selects a plan task
   - `node bin/ghcralph.js run --file task.md --dry-run --force` treats a non-plan Markdown file as a one-off task
+
+## 2026-01-25 - ghcralph run: remove --plan
+
+### Problem
+- Even as a hidden/deprecated flag, `--plan` is easy to forget and becomes accidental long-term surface area.
+
+### Fix
+- Removed `--plan/-p` from `ghcralph run` entirely; `--file` is the only way to load Markdown plan files (auto-detected).
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- `npm run build`
+- Manual check: `node bin/ghcralph.js run --help` shows no `--plan`
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 4b92536..32cb1fc 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -127,7 +127,9 @@ See also:
   ghcralph init       Initialize Ralph in your project
 ```
 
-I think the `--file` and `--plan` parameters are a bit confusing as they both refer to a file containing a plan, but with different formats. If we want to support different file formats (exemple md and json), the processing could be dynamically routed based on the file extension rather than having separate parameters.
+I think the `--file` parameter should handle both a one-off task file and a Markdown plan file (auto-detected), instead of having a separate `--plan` parameter.
+
+**Update (2026-01-25):** `--plan` was removed entirely; use `--file` for Markdown plan files.
 
 ### Finding 3: Run could benefit from complementay configuration entries for GitHub Issues plan source ✅ (Addressed)
 
diff --git a/src/commands/run.ts b/src/commands/run.ts
index 436a7fd..63d9c91 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -7,7 +7,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { Option, type Command } from 'commander';
+import type { Command } from 'commander';
 import { info, success, error, warn, debug, spinner, heading, code, dim, parseNonNegativeInt } from '../utils/index.js';
 import { CopilotAgent } from '../integrations/index.js';
 import {
@@ -26,7 +26,6 @@ import type { Task } from '../types/index.js';
 export interface RunOptions {
   task?: string;
   file?: string;
-  plan?: string;
   github?: boolean;
   context?: string[];
   branch?: string;
@@ -131,7 +130,6 @@ export function registerRunCommand(program: Command): void {
     .description('Execute an agentic coding loop')
     .option('-t, --task <description>', 'Task to execute (inline)')
     .option('-f, --file <path>', 'Read task (or Markdown plan) from file')
-    .addOption(new Option('-p, --plan <path>', 'Read tasks from a Markdown plan file (deprecated; use --file)').hideHelp())
     .option('-g, --github', 'Use GitHub Issues as plan source (configured via .ghcralph/config.json)')
     .option('-c, --context <glob...>', 'Include files matching glob patterns in context')
     .option('-b, --branch <name>', 'Use or create a specific branch name')
@@ -159,16 +157,11 @@ See also:
   ghcralph init       Initialize Ralph in your project
 `)
     .action(async (options: RunOptions) => {
-      if (!options.task && !options.file && !options.plan && !options.github) {
+      if (!options.task && !options.file && !options.github) {
         error('Please provide a task with --task, --file, or --github');
         process.exit(1);
       }
 
-      if (options.plan && options.file) {
-        error('Please provide only one of --file or --plan');
-        process.exit(1);
-      }
-
       const gitRoot = getGitRoot();
       const configManager = new ConfigManager(gitRoot ?? undefined);
       const config = await configManager.load();
@@ -261,13 +254,14 @@ See also:
           await planManager.startTask(task.id);
           info(`Selected issue from GitHub: ${task.title}`);
         } else {
-          const fileArg = options.plan ?? options.file;
-          const forcePlan = options.plan !== undefined;
+          const fileArg = options.file;
 
           if (fileArg) {
-            // If user explicitly used --plan, always treat as plan.
-            // Otherwise, auto-detect Markdown plan files by the presence of task checkboxes.
-            if (forcePlan) {
+            const content = await readTaskFromFile(fileArg);
+            const ext = path.extname(fileArg).toLowerCase();
+            const isMarkdown = ext === '.md' || ext === '.markdown';
+
+            if (isMarkdown && looksLikeMarkdownPlan(content)) {
               planManager = new LocalMarkdownPlan(fileArg);
               planFilePath = fileArg;
               await planManager.initialize();
@@ -279,30 +273,13 @@ See also:
               task = nextTask;
               info(`Selected task from plan: ${task.title}`);
             } else {
-              const content = await readTaskFromFile(fileArg);
-              const ext = path.extname(fileArg).toLowerCase();
-              const isMarkdown = ext === '.md' || ext === '.markdown';
-
-              if (isMarkdown && looksLikeMarkdownPlan(content)) {
-                planManager = new LocalMarkdownPlan(fileArg);
-                planFilePath = fileArg;
-                await planManager.initialize();
-                const nextTask = await planManager.getNextTask();
-                if (!nextTask) {
-                  success('All tasks in the plan are complete!');
-                  return;
-                }
-                task = nextTask;
-                info(`Selected task from plan: ${task.title}`);
-              } else {
-                task = {
-                  id: `task-${Date.now()}`,
-                  title: fileArg,
-                  content,
-                  status: 'pending',
-                  source: 'local',
-                };
-              }
+              task = {
+                id: `task-${Date.now()}`,
+                title: fileArg,
+                content,
+                status: 'pending',
+                source: 'local',
+              };
             }
           } else {
             task = await createTask(options);

From f339e63cb314c310971a2d1d429db9bbef23c244 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 01:28:04 +0000
Subject: [PATCH 07/13] Init: prompt GitHub config conditionally

---
 JOURNAL.md                      | 21 +++++++
 plans/v0-1-0_REFINEMENT_PLAN.md |  2 +
 src/commands/init.ts            | 97 +++++++++++++++++++++++++++++++++
 3 files changed, 120 insertions(+)

diff --git a/JOURNAL.md b/JOURNAL.md
index 2bedef0..2da0974 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1162,3 +1162,24 @@ The Ralph realignment is working! The CLI now:
 - `npm test`
 - `npm run build`
 - Manual check: `node bin/ghcralph.js run --help` shows no `--plan`
+
+## 2026-01-26 - ghcralph init: prompt GitHub config only when planSource=github
+
+### Problem
+- After adding GitHub defaults to configuration (repo/filters), `ghcralph init` did not help users set them up, and local plan users should not be prompted for GitHub details.
+
+### Root cause
+- `src/commands/init.ts` only prompted for generic configuration keys and did not branch on `planSource` to collect GitHub-specific configuration.
+
+### Fix
+- Updated interactive init to:
+  - Prompt for `githubRepo` (required) when `planSource=github`
+  - Optionally prompt for `githubLabel` / `githubMilestone` / `githubAssignee`
+  - Skip all GitHub prompts when `planSource=local`
+- Enhanced init output summary to display GitHub settings when `planSource=github`, and warn if GitHub plan source is selected but `githubRepo` is missing.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- `npm run build`
+- Manual check: `node bin/ghcralph.js init --help`
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 32cb1fc..73d1196 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -176,6 +176,8 @@ See also:
 
 When using GitHub Issues as plan source, it could be useful to have complementary configuration entries in the `.ghcralph` configuration file to define default values for the owner/repo, label, milestone and assignee filters.
 
+**Update (2026-01-26):** `ghcralph init` now prompts for `githubRepo` (and optionally label/milestone/assignee) only when `planSource=github`.
+
 ### Finding 4: Run parameters should not offer overwriting configuration file values ✅ (Addressed)
 
 ```
diff --git a/src/commands/init.ts b/src/commands/init.ts
index c6b1057..bfb8f94 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -75,6 +75,26 @@ async function promptString(rl: Interface, message: string, defaultValue: string
   return answer || defaultValue;
 }
 
+async function promptGitHubRepo(rl: Interface, defaultValue?: string): Promise<string> {
+  while (true) {
+    const hint = defaultValue ? ` (${defaultValue}) ` : ' ';
+    const answer = (await rl.question(`GitHub repo (owner/repo)${hint}`)).trim();
+    const value = answer || defaultValue || '';
+
+    const parts = value.split('/');
+    if (parts.length === 2 && parts[0] && parts[1]) return value;
+
+    console.log(dim('Please enter a valid repo in the form owner/repo.'));
+  }
+}
+
+async function promptOptionalString(rl: Interface, message: string, defaultValue?: string): Promise<string | undefined> {
+  const hint = defaultValue ? ` (${defaultValue}) ` : ' ';
+  const answer = (await rl.question(`${message}${hint}`)).trim();
+  const value = answer || defaultValue || '';
+  return value ? value : undefined;
+}
+
 async function promptSelect<T extends string>(
   rl: Interface,
   message: string,
@@ -201,6 +221,18 @@ See also:
           console.log(`  ${dim('Model:')} ${code(current.defaultModel)}`);
           console.log(`  ${dim('Auto commit:')} ${current.autoCommit}`);
           console.log(`  ${dim('Branch prefix:')} ${code(current.branchPrefix)}`);
+          if (current.planSource === 'github') {
+            console.log(`  ${dim('GitHub repo:')} ${code(current.githubRepo ?? '(not set)')}`);
+            if (current.githubLabel) {
+              console.log(`  ${dim('GitHub label:')} ${code(current.githubLabel)}`);
+            }
+            if (current.githubMilestone) {
+              console.log(`  ${dim('GitHub milestone:')} ${code(current.githubMilestone)}`);
+            }
+            if (current.githubAssignee) {
+              console.log(`  ${dim('GitHub assignee:')} ${code(current.githubAssignee)}`);
+            }
+          }
           console.log('');
 
           const keepDefaults = await promptConfirm(rl, 'Keep these defaults?', true);
@@ -263,6 +295,42 @@ See also:
             configManager.set('branchPrefix', branchPrefix);
           }
 
+          const finalPlanSource = configManager.getConfig().planSource;
+          if (finalPlanSource === 'github') {
+            const repo = await promptGitHubRepo(rl, configManager.getConfig().githubRepo);
+            configManager.set('githubRepo', repo);
+
+            const hasAnyFilters = Boolean(
+              configManager.getConfig().githubLabel ||
+                configManager.getConfig().githubMilestone ||
+                configManager.getConfig().githubAssignee
+            );
+            const setFilters = await promptConfirm(
+              rl,
+              'Configure default GitHub issue filters (label/milestone/assignee)?',
+              hasAnyFilters
+            );
+
+            if (setFilters) {
+              const label = await promptOptionalString(rl, 'GitHub label filter', configManager.getConfig().githubLabel);
+              if (label) configManager.set('githubLabel', label);
+
+              const milestone = await promptOptionalString(
+                rl,
+                'GitHub milestone filter',
+                configManager.getConfig().githubMilestone
+              );
+              if (milestone) configManager.set('githubMilestone', milestone);
+
+              const assignee = await promptOptionalString(
+                rl,
+                'GitHub assignee filter',
+                configManager.getConfig().githubAssignee
+              );
+              if (assignee) configManager.set('githubAssignee', assignee);
+            }
+          }
+
           const finalConfig = configManager.getConfig();
           console.log('');
           console.log(dim('Configuration to write:'));
@@ -272,6 +340,18 @@ See also:
           console.log(`  ${dim('Model:')} ${code(finalConfig.defaultModel)}`);
           console.log(`  ${dim('Auto commit:')} ${finalConfig.autoCommit}`);
           console.log(`  ${dim('Branch prefix:')} ${code(finalConfig.branchPrefix)}`);
+          if (finalConfig.planSource === 'github') {
+            console.log(`  ${dim('GitHub repo:')} ${code(finalConfig.githubRepo ?? '(not set)')}`);
+            if (finalConfig.githubLabel) {
+              console.log(`  ${dim('GitHub label:')} ${code(finalConfig.githubLabel)}`);
+            }
+            if (finalConfig.githubMilestone) {
+              console.log(`  ${dim('GitHub milestone:')} ${code(finalConfig.githubMilestone)}`);
+            }
+            if (finalConfig.githubAssignee) {
+              console.log(`  ${dim('GitHub assignee:')} ${code(finalConfig.githubAssignee)}`);
+            }
+          }
           console.log('');
 
           const confirmWrite = await promptConfirm(rl, 'Write configuration?', true);
@@ -299,7 +379,24 @@ See also:
       console.log(`  ${dim('Model:')} ${code(config.defaultModel)}`);
       console.log(`  ${dim('Auto commit:')} ${config.autoCommit}`);
       console.log(`  ${dim('Branch prefix:')} ${code(config.branchPrefix)}`);
+      if (config.planSource === 'github') {
+        console.log(`  ${dim('GitHub repo:')} ${code(config.githubRepo ?? '(not set)')}`);
+        if (config.githubLabel) {
+          console.log(`  ${dim('GitHub label:')} ${code(config.githubLabel)}`);
+        }
+        if (config.githubMilestone) {
+          console.log(`  ${dim('GitHub milestone:')} ${code(config.githubMilestone)}`);
+        }
+        if (config.githubAssignee) {
+          console.log(`  ${dim('GitHub assignee:')} ${code(config.githubAssignee)}`);
+        }
+      }
       console.log('');
+
+      if (config.planSource === 'github' && !config.githubRepo) {
+        warn('GitHub plan source selected but githubRepo is not configured.');
+        info(`Set it with ${code('ghcralph config set githubRepo owner/repo')} (or GHCRALPH_GITHUB_REPO).`);
+      }
       console.log(dim('Created:'));
       console.log(`  ${code(stateDir)}`);
       console.log('');

From 5633a1590b310e8953294258c8623e90b0e8ea56 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 01:30:28 +0000
Subject: [PATCH 08/13] Simplify `ghcralph run` command by merging `--file` and
 `--plan` options; deprecate `--plan` for backward compatibility

---
 JOURNAL.md | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index 2da0974..c06c7bf 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1109,6 +1109,25 @@ The Ralph realignment is working! The CLI now:
 
 ## 2026-01-25 - ghcralph run: simplify plan vs file
 
+### Problem
+- The `ghcralph run` command exposed both `--file` (single task file) and `--plan` (Markdown plan file), which is confusing since both point at a file path.
+
+### Root cause
+- `src/commands/run.ts` treated task-from-file and plan-from-file as separate modes requiring different flags, instead of routing by file content/type.
+
+### Fix
+- Made `--file` accept either a single task file or a Markdown plan file (auto-detected via checkbox tasks in Markdown).
+- Kept `--plan` as a **deprecated** option (hidden from help) that forces plan parsing for backward compatibility.
+- Updated docs/examples to prefer `ghcralph run --file PLAN.md`.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- Manual checks:
+  - `node bin/ghcralph.js run --help` does not show `--plan`
+  - `node bin/ghcralph.js run --file test/integration/calculator/PLAN.md --dry-run --force` selects a plan task
+  - `node bin/ghcralph.js run --file task.md --dry-run --force` treats a non-plan Markdown file as a one-off task
+
 ## 2026-01-25 - ghcralph run: config is the source of truth
 
 ### Problem
@@ -1130,25 +1149,6 @@ The Ralph realignment is working! The CLI now:
 - `npm run build`
 - Manual check: `node bin/ghcralph.js run --help` no longer lists config-backed override flags
 
-### Problem
-- The `ghcralph run` command exposed both `--file` (single task file) and `--plan` (Markdown plan file), which is confusing since both point at a file path.
-
-### Root cause
-- `src/commands/run.ts` treated task-from-file and plan-from-file as separate modes requiring different flags, instead of routing by file content/type.
-
-### Fix
-- Made `--file` accept either a single task file or a Markdown plan file (auto-detected via checkbox tasks in Markdown).
-- Kept `--plan` as a **deprecated** option (hidden from help) that forces plan parsing for backward compatibility.
-- Updated docs/examples to prefer `ghcralph run --file PLAN.md`.
-
-### Validation
-- `npm run typecheck`
-- `npm test`
-- Manual checks:
-  - `node bin/ghcralph.js run --help` does not show `--plan`
-  - `node bin/ghcralph.js run --file test/integration/calculator/PLAN.md --dry-run --force` selects a plan task
-  - `node bin/ghcralph.js run --file task.md --dry-run --force` treats a non-plan Markdown file as a one-off task
-
 ## 2026-01-25 - ghcralph run: remove --plan
 
 ### Problem

From 8dfab3f0b8bfef486894122217fd9d81db1f4597 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 01:38:27 +0000
Subject: [PATCH 09/13] Docs: mark Finding 5 addressed

---
 JOURNAL.md                      | 17 +++++++++++++++++
 plans/v0-1-0_REFINEMENT_PLAN.md |  8 +++++---
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index c06c7bf..aafb3f6 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1163,6 +1163,23 @@ The Ralph realignment is working! The CLI now:
 - `npm run build`
 - Manual check: `node bin/ghcralph.js run --help` shows no `--plan`
 
+## 2026-01-26 - Finding 5: run dry-run uses configured model
+
+### Problem
+- `ghcralph run --dry-run` used to display a hardcoded/default model (`gpt-4`) instead of the configured `defaultModel`.
+
+### Root cause
+- `ghcralph run` was not consistently loading `.ghcralph/config.json` / `GHCRALPH_*` before printing its run summary.
+
+### Fix
+- `ghcralph run` now loads config at startup and uses `defaultModel` for both dry-run output and real runs.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- `npm run build`
+- Manual smoke test: init a temp repo, set `defaultModel` in `.ghcralph/config.json`, then run `ghcralph run --file PLAN.md --dry-run` and verify the model printed matches config.
+
 ## 2026-01-26 - ghcralph init: prompt GitHub config only when planSource=github
 
 ### Problem
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 73d1196..4bd1136 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -225,10 +225,10 @@ Some of the parameters available when running `ghcralph run` are already defined
 
 This ajustement could be completed by enhancing the documentation to clearly indicate which parameters can be set only via the configuration file and which ones can be set only via command line parameters and also the output of the help command to reflect this distinction.
 
-### Finding 5: Run dry run does present a model different than the one defined in the configuration file
+### Finding 5: Run dry run does present a model different than the one defined in the configuration file ✅ (Addressed)
 
 ```
-@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --plan PLAN.md --dry-run
+@rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --file PLAN.md --dry-run
 ℹ Loaded 11 tasks from PLAN.md
 ℹ Selected task from plan: Create calculator.sh with basic structure
 
@@ -261,7 +261,9 @@ Create calculator.sh with basic structure
   branchPrefix: ghcralph/
 ```
 
-When running `ghcralph run --dry-run`, the model presented in the summary is `gpt-4`, while the configuration file indicates `gpt-5.2-codex` as the default model. It indicates either the dry run is not reading the configuration file correctly, or the model value is hardcoded in the dry run output or worse is not being used at all by the run command (hypothesis confirmed running run without the dry-run flag).
+When running `ghcralph run --dry-run`, the model presented in the summary is `gpt-4`, while the configuration file indicates `gpt-5.2-codex` as the default model. It indicates either the dry run is not reading the configuration file correctly, or the model value is hardcoded in the dry run output or worse is not being used at all by the run command.
+
+**Update (2026-01-26):** `ghcralph run` now always loads config and uses `defaultModel` for both dry-run output and actual runs.
 
 ### Finding 6: First simple run generates an error
 

From 3206b6583b1a9f595a8480880e74823be74c4872 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 02:11:36 +0000
Subject: [PATCH 10/13] Fix Finding 6: git hooks + shutdown

---
 JOURNAL.md                             | 12 +++++++
 plans/v0-1-0_REFINEMENT_PLAN.md        |  8 +++--
 src/commands/run.ts                    | 22 ++++++++++---
 src/core/git-branch-manager.test.ts    | 22 +++++++++++++
 src/core/git-branch-manager.ts         | 28 ++++++++++++++++
 src/integrations/copilot-agent.test.ts | 45 +++++++++++---------------
 src/integrations/copilot-agent.ts      | 26 ++-------------
 7 files changed, 107 insertions(+), 56 deletions(-)

diff --git a/JOURNAL.md b/JOURNAL.md
index aafb3f6..b24ff3f 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -201,6 +201,18 @@
 - Keyword extraction filters common stop words
 - Limits to 5 relevant files and 3 top keywords for efficiency
 
+## 2026-01-26 - Finding 6: Fix first-run branch error + clean shutdown
+
+### Completed
+- Git branch creation/switch now tolerates failing git hooks (e.g. Git LFS hooks when git-lfs is missing) when the branch is actually checked out, and prints guidance instead of hard-failing.
+- Copilot agent execution now uses `session.sendAndWait()` to avoid leaking session event handlers.
+- `ghcralph run` now removes SIGINT/SIGTERM handlers and destroys the Copilot agent before exit.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- `npm run build`
+
 ## 2026-01-24 - Issue #11: Git Branch Isolation
 
 ### Completed
diff --git a/plans/v0-1-0_REFINEMENT_PLAN.md b/plans/v0-1-0_REFINEMENT_PLAN.md
index 4bd1136..8e3d6d8 100644
--- a/plans/v0-1-0_REFINEMENT_PLAN.md
+++ b/plans/v0-1-0_REFINEMENT_PLAN.md
@@ -265,7 +265,7 @@ When running `ghcralph run --dry-run`, the model presented in the summary is `gp
 
 **Update (2026-01-26):** `ghcralph run` now always loads config and uses `defaultModel` for both dry-run output and actual runs.
 
-### Finding 6: First simple run generates an error
+### Finding 6: First simple run generates an error ✅ (Addressed)
 
 ```
 @rpothin ➜ /workspaces/ghc-ralph-cli-demo (main) $ ghcralph run --plan PLAN.md
@@ -370,4 +370,8 @@ Error [ERR_STREAM_DESTROYED]: Cannot call write after a stream was destroyed
 Node.js v24.12.0
 ```
 
-This indicates that the run process does not terminate correctly after completing the task, leading to a situation where the user has to manually interrupt the process. The CLI should ensure that it exits gracefully after task completion, returning control to the user without requiring manual intervention.
\ No newline at end of file
+This indicates that the run process does not terminate correctly after completing the task, leading to a situation where the user has to manually interrupt the process. The CLI should ensure that it exits gracefully after task completion, returning control to the user without requiring manual intervention.
+
+**Update (2026-01-26):**
+- Git branch creation/switch now tolerates failing git hooks (e.g. Git LFS hooks when git-lfs is missing) when the branch was actually checked out, and prints guidance instead of throwing.
+- Copilot session handling now uses `sendAndWait()` (which unsubscribes its event handler) to avoid leaking listeners; `ghcralph run` also cleans up SIGINT/SIGTERM handlers and destroys the agent on exit.
\ No newline at end of file
diff --git a/src/commands/run.ts b/src/commands/run.ts
index 63d9c91..fafb7c4 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -106,7 +106,7 @@ async function createTask(options: RunOptions): Promise<Task> {
 /**
  * Handle graceful shutdown on Ctrl+C
  */
-function setupSignalHandlers(engine: LoopEngine): void {
+function setupSignalHandlers(engine: LoopEngine): () => void {
   let shutdownRequested = false;
 
   const handler = (): void => {
@@ -122,6 +122,11 @@ function setupSignalHandlers(engine: LoopEngine): void {
 
   process.on('SIGINT', handler);
   process.on('SIGTERM', handler);
+
+  return () => {
+    process.off('SIGINT', handler);
+    process.off('SIGTERM', handler);
+  };
 }
 
 export function registerRunCommand(program: Command): void {
@@ -421,7 +426,7 @@ See also:
       await fileSafeguard.initialize();
 
       // Setup signal handlers for graceful shutdown
-      setupSignalHandlers(engine);
+      const cleanupSignalHandlers = setupSignalHandlers(engine);
 
       // Setup event listeners
       const events = engine.getEvents();
@@ -476,6 +481,8 @@ See also:
       const loopSpinner = spinner('Running agentic loop...');
       loopSpinner.start();
 
+      let exitCode = 0;
+
       try {
         const finalState = await engine.start(task);
 
@@ -509,12 +516,19 @@ See also:
             await planManager.failTask(task.id);
           }
           error('Loop failed');
-          process.exit(1);
+          exitCode = 1;
         }
       } catch (err) {
         loopSpinner.fail('Loop failed');
         error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        exitCode = 1;
+      } finally {
+        cleanupSignalHandlers();
+        await agent.destroy();
+      }
+
+      if (exitCode !== 0) {
+        process.exit(exitCode);
       }
     });
 }
diff --git a/src/core/git-branch-manager.test.ts b/src/core/git-branch-manager.test.ts
index 642cb02..597ae26 100644
--- a/src/core/git-branch-manager.test.ts
+++ b/src/core/git-branch-manager.test.ts
@@ -144,6 +144,28 @@ describe('GitBranchManager', () => {
       const currentBranch = await manager.getCurrentBranch();
       expect(currentBranch.name).toBe('ghcralph/test-new-branch');
     });
+
+    (process.platform === 'win32' ? it.skip : it)(
+      'should not fail when a post-checkout hook fails but branch is created',
+      async () => {
+        // Configure a failing post-checkout hook (simulates missing git-lfs)
+        const hooksDir = path.join(tempDir, '.githooks');
+        await fs.mkdir(hooksDir, { recursive: true });
+        await fs.writeFile(
+          path.join(hooksDir, 'post-checkout'),
+          '#!/bin/sh\necho "This repository is configured for Git LFS but git-lfs was not found on your path."\nexit 1\n'
+        );
+        await execAsync(`chmod +x "${path.join(hooksDir, 'post-checkout')}"`, { cwd: tempDir });
+        await execAsync('git config core.hooksPath .githooks', { cwd: tempDir });
+
+        const branchName = 'ghcralph/hook-failure-branch';
+        const success = await manager.createAndSwitchBranch(branchName);
+        expect(success).toBe(true);
+
+        const currentBranch = await manager.getCurrentBranch();
+        expect(currentBranch.name).toBe(branchName);
+      }
+    );
   });
 
   describe('stashChanges', () => {
diff --git a/src/core/git-branch-manager.ts b/src/core/git-branch-manager.ts
index 5f25446..9036e1d 100644
--- a/src/core/git-branch-manager.ts
+++ b/src/core/git-branch-manager.ts
@@ -184,6 +184,21 @@ export class GitBranchManager {
       debug(`Created and switched to branch: ${branchName}`);
       return true;
     } catch (err) {
+      // Some repos have failing hooks (e.g. Git LFS hooks when git-lfs isn't installed)
+      // but the branch may still have been created and checked out.
+      try {
+        const current = await this.getCurrentBranch();
+        if (current.name === branchName) {
+          warn(
+            `Branch '${branchName}' was created, but a git hook failed during checkout. ` +
+              `If you use Git LFS, install git-lfs or disable the failing hook.`
+          );
+          return true;
+        }
+      } catch {
+        // ignore and surface original error
+      }
+
       const message = err instanceof Error ? err.message : String(err);
       throw new Error(`Failed to create branch: ${message}`);
     }
@@ -198,6 +213,19 @@ export class GitBranchManager {
       debug(`Switched to branch: ${branchName}`);
       return true;
     } catch (err) {
+      try {
+        const current = await this.getCurrentBranch();
+        if (current.name === branchName) {
+          warn(
+            `Switched to '${branchName}', but a git hook failed during checkout. ` +
+              `If you use Git LFS, install git-lfs or disable the failing hook.`
+          );
+          return true;
+        }
+      } catch {
+        // ignore and surface original error
+      }
+
       const message = err instanceof Error ? err.message : String(err);
       throw new Error(`Failed to switch branch: ${message}`);
     }
diff --git a/src/integrations/copilot-agent.test.ts b/src/integrations/copilot-agent.test.ts
index 31ab731..d3f5f00 100644
--- a/src/integrations/copilot-agent.test.ts
+++ b/src/integrations/copilot-agent.test.ts
@@ -1,10 +1,9 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { CopilotAgent } from './copilot-agent.js';
 
-let mockOn:
-  | ((handler: (event: { type: string; data: { content?: string; message?: string } }) => void) => void)
+let mockSendAndWait:
+  | ((args: { prompt: string }) => Promise<{ type: string; data: { content?: string } } | undefined>)
   | null = null;
-let mockSend: ((args: { prompt: string }) => Promise<void>) | null = null;
 
 vi.mock(
   '@github/copilot-sdk',
@@ -13,8 +12,10 @@ vi.mock(
       start: () => Promise<void>;
       stop: () => Promise<void>;
       createSession: () => Promise<{
-        on: (handler: (event: { type: string; data: { content?: string; message?: string } }) => void) => void;
-        send: (args: { prompt: string }) => Promise<void>;
+        sendAndWait: (
+          args: { prompt: string },
+          timeout?: number
+        ) => Promise<{ type: string; data: { content?: string } } | undefined>;
         destroy: () => Promise<void>;
       }>;
     };
@@ -24,20 +25,18 @@ vi.mock(
         async start(): Promise<void> {}
         async stop(): Promise<void> {}
         async createSession(): Promise<{
-          on: (handler: (event: { type: string; data: { content?: string; message?: string } }) => void) => void;
-          send: (args: { prompt: string }) => Promise<void>;
+          sendAndWait: (
+            args: { prompt: string },
+            timeout?: number
+          ) => Promise<{ type: string; data: { content?: string } } | undefined>;
           destroy: () => Promise<void>;
         }> {
           return {
-            on: (
-              handler: (event: { type: string; data: { content?: string; message?: string } }) => void
-            ): void => {
-              mockOn = handler;
-            },
-            send: async (args: { prompt: string }): Promise<void> => {
-              if (mockSend) {
-                await mockSend(args);
+            sendAndWait: async (args: { prompt: string }): Promise<{ type: string; data: { content?: string } } | undefined> => {
+              if (mockSendAndWait) {
+                return await mockSendAndWait(args);
               }
+              return undefined;
             },
             destroy: async (): Promise<void> => {},
           };
@@ -60,8 +59,7 @@ vi.mock(
 
 describe('CopilotAgent', () => {
   beforeEach((): void => {
-    mockOn = null;
-    mockSend = null;
+    mockSendAndWait = null;
   });
 
   afterEach((): void => {
@@ -74,11 +72,8 @@ describe('CopilotAgent', () => {
     const initialized = await agent.initialize();
     expect(initialized).toBe(true);
 
-    mockSend = async (): Promise<void> => {
-      if (mockOn) {
-        mockOn({ type: 'assistant.message', data: { content: 'Hello' } });
-        mockOn({ type: 'session.idle', data: {} });
-      }
+    mockSendAndWait = async (): Promise<{ type: string; data: { content?: string } } | undefined> => {
+      return { type: 'assistant.message', data: { content: 'Hello' } };
     };
 
     const result = await agent.execute('Say hello');
@@ -93,10 +88,8 @@ describe('CopilotAgent', () => {
 
     await agent.initialize();
 
-    mockSend = async (): Promise<void> => {
-      if (mockOn) {
-        mockOn({ type: 'session.error', data: { message: 'Boom' } });
-      }
+    mockSendAndWait = async (): Promise<{ type: string; data: { content?: string } } | undefined> => {
+      throw new Error('Boom');
     };
 
     const result = await agent.execute('fail');
diff --git a/src/integrations/copilot-agent.ts b/src/integrations/copilot-agent.ts
index 78c942a..6beea23 100644
--- a/src/integrations/copilot-agent.ts
+++ b/src/integrations/copilot-agent.ts
@@ -190,30 +190,8 @@ export class CopilotAgent {
     let responseContent = '';
 
     try {
-      // Create a promise that resolves when the session becomes idle
-      const done = new Promise<void>((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new CopilotError('Session timeout', 'TIMEOUT', true));
-        }, 120000); // 2 minute timeout
-
-        this.session?.on((event) => {
-          if (event.type === 'assistant.message') {
-            responseContent += event.data.content ?? '';
-          } else if (event.type === 'session.idle') {
-            clearTimeout(timeout);
-            resolve();
-          } else if (event.type === 'session.error') {
-            clearTimeout(timeout);
-            reject(new CopilotError(event.data.message ?? 'Unknown error', 'SDK_ERROR', true));
-          }
-        });
-      });
-
-      // Send the prompt
-      await this.session.send({ prompt });
-
-      // Wait for completion
-      await done;
+      const response = await this.session.sendAndWait({ prompt }, 120000);
+      responseContent = response?.data.content ?? '';
 
       const completionTokens = estimateTokens(responseContent);
       this.tokenTracker.addUsage(promptTokens, completionTokens);

From a6135adb95eb69076c9186b99bb6afcf774182c2 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 02:43:06 +0000
Subject: [PATCH 11/13] Docs: remove devcontainer git-lfs

---
 .devcontainer/devcontainer.json |  2 +-
 JOURNAL.md                      | 14 ++++++++++++++
 docs/cookbook.md                | 22 ++++++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index e3799cc..d6b1363 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -24,7 +24,7 @@
 	// "forwardPorts": [],
 
 	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "npm install @github/copilot-sdk && sudo apt-get update && sudo apt-get install -y git-lfs && git lfs install"
+	"postCreateCommand": "npm install"
 
 	// Configure tool-specific properties.
 	// "customizations": {},
diff --git a/JOURNAL.md b/JOURNAL.md
index b24ff3f..b59766d 100644
--- a/JOURNAL.md
+++ b/JOURNAL.md
@@ -1212,3 +1212,17 @@ The Ralph realignment is working! The CLI now:
 - `npm test`
 - `npm run build`
 - Manual check: `node bin/ghcralph.js init --help`
+
+## 2026-01-26 - Docs/devcontainer: avoid Git LFS requirement
+
+### Problem
+- Some environments install Git LFS hooks (e.g. `.git/hooks/post-checkout`) without ensuring `git-lfs` is available, which can make `git checkout` return a non-zero exit code and confuse first-time `ghcralph run` users.
+
+### Fix
+- Removed `git-lfs` install and `git lfs install` from `.devcontainer/devcontainer.json`.
+- Documented the Git LFS hook error and mitigation steps in `docs/cookbook.md`.
+
+### Validation
+- `npm run typecheck`
+- `npm test`
+- `npm run build`
diff --git a/docs/cookbook.md b/docs/cookbook.md
index 26aa452..e8275ca 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -290,6 +290,28 @@ gh auth login
 export GITHUB_TOKEN=your_token
 ```
 
+### Git LFS hook error when creating/switching branches
+
+If you see an error like:
+
+> This repository is configured for Git LFS but 'git-lfs' was not found on your path
+
+It means your repository has Git LFS **git hooks** installed (e.g. `.git/hooks/post-checkout`) but the `git-lfs` binary is not installed.
+
+Ralph does **not** require Git LFS by itself, but it uses `git checkout` to create/switch branches, which triggers those hooks.
+
+Fix options:
+
+```bash
+# Option A: install Git LFS
+# (Debian/Ubuntu)
+sudo apt-get update && sudo apt-get install -y git-lfs
+git lfs install
+
+# Option B: remove the offending hooks (per-repo)
+rm -f .git/hooks/post-checkout .git/hooks/post-merge .git/hooks/post-commit
+```
+
 ---
 
 ## When NOT to Use Ralph

From 51617ca00db70cad330b7cd0c46b8207a2498d75 Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 03:11:41 +0000
Subject: [PATCH 12/13] Update GitHub Issues command to use config for
 repository; add config command for setting GitHub repo

---
 src/cli.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/cli.ts b/src/cli.ts
index 123ea09..7aebb2a 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -34,7 +34,8 @@ ${dim('Examples:')}
   $ ghcralph init                          # Initialize GitHub Copilot Ralph in your project
   $ ghcralph run --task "Add tests"        # Run a coding loop for a task
   $ ghcralph run --file TODO.md            # Execute tasks from a plan file
-  $ ghcralph run --github owner/repo       # Work through GitHub Issues
+  $ ghcralph run --github                 # Work through GitHub Issues (repo set in config)
+  $ ghcralph config set githubRepo owner/repo
   $ ghcralph status                        # Check current session status
   $ ghcralph rollback --iterations 2       # Undo last 2 iterations
   $ ghcralph config list                   # View current configuration

From b1f9b5332711900122c88c5e5f66e57bb5e9e9de Mon Sep 17 00:00:00 2001
From: Raphael Pothin <raphael.pothin@gmail.com>
Date: Mon, 26 Jan 2026 03:28:49 +0000
Subject: [PATCH 13/13] Bump version to 0.1.1 in package.json and
 package-lock.json

---
 package-lock.json | 4 ++--
 package.json      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 0a7da8f..58ef21c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "ghcralph",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ghcralph",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "license": "MIT",
       "dependencies": {
         "@github/copilot-sdk": "^0.1.17",
diff --git a/package.json b/package.json
index d8d07e9..93fbda2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ghcralph",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "GitHub Copilot Ralph - A cross-platform CLI for running autonomous agentic coding loops using the Ralph Wiggum pattern with GitHub Copilot",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",