v0.1.1: Refinements — interactive init, config-backed run, Git LFS hook tolerance, graceful shutdown

.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": {},

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
@@ -1035,6 +1047,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
@@ -1066,3 +1098,131 @@ The Ralph realignment is working! The CLI now:
 - `npm run lint`
 - `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
+- 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
+- `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
+
+## 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`
+
+## 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
+- 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`
+
+## 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`

README.md

@@ -107,13 +107,14 @@ 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
 ```bash
 ghcralph init --github
-ghcralph run --github owner/repo --label "ready"
+# Configure githubRepo (and optional filters) via .ghcralph/config.json
+ghcralph run --github
 ```
 
 ## Usage
@@ -144,17 +145,17 @@ 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"
+# 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"
@@ -192,6 +193,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 +209,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 +225,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"
 }
 ```
 
@@ -288,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

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

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
@@ -59,11 +59,11 @@ 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
+# (set maxIterations in .ghcralph/config.json)
 ghcralph run --task "Implement user authentication with JWT" \
-  --max-iterations 15 \
   --context "src/auth/**/*.ts"
 ```
 
@@ -203,11 +203,12 @@ 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
+# (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
@@ -287,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

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",