rafcode 3.2.1 → 3.8.0

package/RAF/42-patch-parade/plans/3-fix-codex-error-event-rendering.md

@@ -0,0 +1,32 @@
+---
+effort: low
+---
+# Task: Fix Codex Error Event Rendering
+
+## Objective
+Render the remaining real-world Codex error event shapes so verbose output shows the actual failure text instead of empty or generic messages.
+
+## Context
+The scoped “minor bugs” come from `/Users/eremeev/projects/RAF/RAF/41-echo-chamber/outcomes/2-e2e-test-codex-provider.md`. Two minor renderer gaps remain: `item.completed` events with `item.type: "error"` produce no output, and `turn.failed` events that carry `error.message` fall back to the generic `Turn failed` text.
+
+## Requirements
+- Handle `item.completed` events where `item.type === "error"` and render the embedded error message.
+- Handle `turn.failed` events that carry `error.message` and prefer that message over the generic fallback text.
+- Preserve existing rendering behavior for already-supported Codex event types.
+- Add focused tests that use the real event shapes documented in the outcome report.
+
+## Implementation Steps
+1. Update the Codex stream renderer switch logic to cover the missing error event variants.
+2. Reuse existing formatting conventions so new error output matches current verbose output style.
+3. Add focused unit tests for both missing event shapes.
+4. Verify no existing renderer tests regress.
+
+## Acceptance Criteria
+- [ ] `item.completed` with `item.type: "error"` renders a visible error line.
+- [ ] `turn.failed.error.message` is surfaced in the rendered output.
+- [ ] Existing supported Codex event rendering remains unchanged.
+- [ ] Focused renderer tests cover both real-world bug cases.
+- [ ] All tests pass
+
+## Notes
+Keep this task narrowly scoped to the two bugs from the referenced outcome report.

package/RAF/42-patch-parade/plans/4-update-cli-help-docs.md

@@ -0,0 +1,31 @@
+---
+effort: low
+---
+# Task: Update CLI Help Docs
+
+## Objective
+Align user-facing CLI help text and `README.md` with the removal of the `--worktree` and `--no-worktree` flags.
+
+## Context
+The user wants the help/docs surface updated to reflect that these flags are removed. In this task, scope is limited to CLI help text and `README.md`; prompt artifacts and archived RAF project docs should not be updated.
+
+## Requirements
+- Remove stale references to the removed `--worktree` / `--no-worktree` flags from CLI help text.
+- Update `README.md` so supported flags and usage examples match the actual CLI behavior.
+- Check for both the typo form `--worktreee` and the real flag names while cleaning up docs.
+- Limit documentation changes to CLI help text and `README.md`.
+
+## Implementation Steps
+1. Inspect the current command definitions to identify which option declarations still drive stale help output.
+2. Remove or update the relevant help text so `raf ... --help` matches the intended flag surface.
+3. Update the flag tables and any related usage notes in `README.md`.
+4. Verify there are no remaining user-facing references to the removed flags in the scoped files.
+
+## Acceptance Criteria
+- [ ] CLI help output no longer lists the removed `--worktree` / `--no-worktree` flags.
+- [ ] `README.md` no longer documents the removed flags.
+- [ ] No prompt docs or archived `RAF/*` artifacts are changed for this task.
+- [ ] All tests pass
+
+## Notes
+If removing the help text requires deleting stale Commander option declarations, keep the change tightly scoped to the flag removal.

package/RAF/42-patch-parade/plans/5-update-default-codex-models-to-gpt-5-4.md

@@ -0,0 +1,35 @@
+---
+effort: low
+---
+# Task: Update Default Codex Models to GPT-5.4
+
+## Objective
+Set every Codex default model entry in RAF's current config schema to the literal model string `gpt-5.4`.
+
+## Context
+RAF currently stores Codex defaults in `codexModels` and `codexEffortMapping` under `DEFAULT_CONFIG`. The user wants every Codex slot to use the same default model string `gpt-5.4`, including planning, execution, name generation, failure analysis, PR generation, config assistance, and effort-based task routing. This task is intentionally narrow and updates the existing split-provider schema without redesigning it.
+
+## Dependencies
+1
+
+## Requirements
+- Update every `DEFAULT_CONFIG.codexModels.*` entry to `gpt-5.4`.
+- Update every `DEFAULT_CONFIG.codexEffortMapping.*` entry to `gpt-5.4`.
+- Keep Claude defaults unchanged.
+- Update any config docs, examples, or tests that currently assert older Codex defaults such as `gpt-5.3-codex`.
+- Do not preserve scenario-specific Codex exceptions; all Codex defaults should be the same literal model string.
+
+## Implementation Steps
+1. Update `src/types/config.ts` so every Codex default model slot and Codex effort-mapping slot resolves to `gpt-5.4`.
+2. Search for docs, prompt docs, and tests that embed the previous Codex defaults and update them to match the new default config.
+3. Verify that provider-aware resolution still reads the same config keys and now returns `gpt-5.4` for every default Codex path.
+
+## Acceptance Criteria
+- [ ] `DEFAULT_CONFIG.codexModels.plan`, `.execute`, `.nameGeneration`, `.failureAnalysis`, `.prGeneration`, and `.config` are all `gpt-5.4`.
+- [ ] `DEFAULT_CONFIG.codexEffortMapping.low`, `.medium`, and `.high` are all `gpt-5.4`.
+- [ ] Claude defaults remain unchanged.
+- [ ] Any documentation or tests that mention old Codex defaults are updated.
+- [ ] All tests pass
+
+## Notes
+Task 6 is expected to replace this split-provider schema later. Keep this task focused on default values only and avoid schema changes here.

package/RAF/42-patch-parade/plans/6-unify-model-config-schema.md

@@ -0,0 +1,46 @@
+---
+effort: high
+---
+# Task: Unify Model Config Schema
+
+## Objective
+Replace RAF's provider-split model configuration with a single provider-aware object schema that stores `model`, `reasoningEffort`, and `provider` together.
+
+## Context
+RAF currently spreads model selection across a top-level `provider`, string-valued `models`, string-valued `effortMapping`, and separate Codex-specific `codexModels` / `codexEffortMapping` sections. Existing pending tasks 1 and 2 make that split work correctly, but the user now wants a breaking schema change: every configurable model entry should become an object such as `{ model: "opus", reasoningEffort: "high", provider: "claude" }`, with no top-level `provider` field and no separate Codex-only config branches. This task should preserve the decision from task 5 that Codex defaults use `gpt-5.4`, while removing support for the old config shape and the RAF CLI model-selection flags such as `--model` and `--sonnet`.
+
+## Dependencies
+1, 2, 5
+
+## Requirements
+- Change the config schema so model-bearing entries are objects with `model`, `reasoningEffort`, and `provider`.
+- Remove the top-level `provider` config field.
+- Remove `codexModels` and `codexEffortMapping`.
+- Remove the old string-only model config shape instead of supporting both schemas in parallel.
+- Remove RAF CLI flags that let users pick a model directly, including `--model`, `--sonnet`, and related validation/help text.
+- Preserve the remaining command behavior by resolving provider and model from the selected config object for each scenario.
+- Keep the config provider-agnostic so users can mix Claude and Codex entries freely across scenarios and effort levels.
+- Add new tests for the new config schema covering validation, default resolution, effort-based resolution, merge behavior, and rejection of removed legacy keys/flags.
+- Update user-facing docs and config docs to reflect the breaking schema change and the removed model-selection flags.
+
+## Implementation Steps
+1. Redesign the config types in `src/types/config.ts` around a reusable provider-aware model object and update `DEFAULT_CONFIG` to the new shape.
+2. Rewrite config validation and merge logic in `src/utils/config.ts` to accept only the new schema, reject removed keys, and resolve scenario/effort selections from structured model objects.
+3. Refactor callers such as `src/commands/plan.ts`, `src/commands/do.ts`, name generation, failure analysis, and PR generation so they consume provider/model pairs from the new config objects instead of top-level provider plus split mappings.
+4. Remove RAF CLI model override flags and the related validation paths, while keeping internal provider-runner calls intact.
+5. Carry forward task 5's default decision by making every default Codex-backed config entry use `gpt-5.4` within the new object schema.
+6. Update `README.md`, config documentation, and command help to document the new schema and removed flags.
+7. Add focused automated coverage for the new schema and resolution paths, including failure cases for legacy keys and removed CLI flags.
+
+## Acceptance Criteria
+- [ ] Config defaults use provider-aware model objects instead of plain strings.
+- [ ] `provider`, `codexModels`, and `codexEffortMapping` are removed from the supported config schema.
+- [ ] RAF no longer accepts `--model`, `--sonnet`, or equivalent user-facing model-selection flags.
+- [ ] Scenario-based model resolution and effort-based task resolution both read the new object schema correctly.
+- [ ] Default Codex-backed entries in the new schema use `gpt-5.4`.
+- [ ] New tests cover the new schema, merge behavior, resolution behavior, and rejection of removed legacy keys/flags.
+- [ ] User-facing docs describe the new schema and no longer document removed flags.
+- [ ] All tests pass
+
+## Notes
+This is an intentional breaking change. Do not add migration compatibility or fallback support for the removed config keys. Assume the existing `--provider` command flag remains unless implementation shows it is fully redundant; the explicit user request only removed direct model-selection flags.

package/RAF/43-swiss-army/decisions.md

@@ -0,0 +1,34 @@
+# Project Decisions
+
+## How should the project name appear in commit messages?
+Use the folder name as-is (kebab-case, without the number prefix). E.g., '43-swiss-army' → 'swiss-army'.
+
+## Where should plan/amend commit descriptions come from?
+Auto-generated from plan content. Plan descriptions should be a project summary derived from input.md (e.g., 'Plan: Swiss army knife utilities for config and CLI').
+
+## Should commit format templates be configurable?
+Yes — add template strings to raf.config.json with {projectName}, {description} placeholders.
+
+## Should model validation keep legacy string-based validation or fully clean up?
+Full cleanup — remove all legacy string-based model validation, only accept ModelEntry objects.
+
+## How should config presets be stored and switched?
+Named JSON files stored as ~/.raf/presets/<name>.json, switched with 'raf preset <name>'.
+
+## What preset commands are needed?
+Full CRUD: 'raf preset save/load/list/delete <name>'.
+
+## Should --provider flag be removed immediately or deprecated?
+Remove immediately — no users, greenfield project.
+
+## Should 'fast' be per-model or global?
+Per model entry — each ModelEntry gets fast: true/false, allowing fast planning but thorough execution.
+
+## How should the config wizard validate model names?
+Hardcoded list of known-good models in config-docs.md, supplemented with web search guidance in the wizard prompt.
+
+## How should reasoning effort be documented?
+General guidance — mention that reasoning effort is available for supporting models, link to provider docs.
+
+## What should 'Plan:' commit descriptions look like?
+Project summary style, e.g., 'Plan: Swiss army knife utilities for config and CLI' — summarized from input.md.

package/RAF/43-swiss-army/input.md

@@ -0,0 +1,7 @@
+- [ ] update commit message format. instead of project id it should put project name (every commit type change). also for plan it should follow with short plan description like "Plan: doing important stuff like this, this and this", for "Amend:" should also describe that was amended exactly but short. check if we can describe this format in our config. 
+- [ ] reasoningEffort isn't wired to the actual CLI invocation anyway - should be wired
+- [ ] add in src/prompts/config-docs.md and/or config wizard prompt so it validates exact model names and if reasoning effort available, it should search web for these cases.
+- [ ] get rid of --provider flag and relly on model object to always provide it, validate config so provider always either codex or claude
+- [ ] support config presets so i can easily switch between codex and claude configuration. like save user config presets as copy of config file and add preset command to switch
+- [ ] extend model config object with fast: true/false option, research web how to pass fast to claude and codex and wire in the code 
+- [ ] getting error in "raf config" after configuring to model objects:    Config validation warning: models.plan must be a short alias (sonnet, haiku, opus) or a full  model ID (e.g., claude-sonnet-4-5-20250929) <- this is not correct, now we support model objects only

package/RAF/43-swiss-army/outcomes/1-fix-model-validation.md

@@ -0,0 +1,21 @@
+# Outcome: Fix Config Validation for Model Objects
+
+## Summary
+
+The config validation in `src/utils/config.ts` was already correctly updated to validate ModelEntry objects (the `validateModelEntry` function properly rejects strings and requires `{ model, provider }` objects). The prior `config improvements` commit had already implemented the correct validation logic.
+
+The one remaining issue was in `src/prompts/config-docs.md`: the LLM session instructions example showed setting a model to a string `"sonnet"` rather than the correct ModelEntry format `{ "model": "sonnet", "provider": "claude" }`. This would cause the config-session LLM to write invalid configs that would then fail validation.
+
+## Changes Made
+
+- **`src/prompts/config-docs.md`**: Updated the "Explaining Changes" example in the LLM session instructions from `"sonnet"` (string) to `{ "model": "sonnet", "provider": "claude" }` (ModelEntry object).
+
+## Acceptance Criteria Status
+
+- [x] No validation warnings when config uses ModelEntry objects with valid model names — validation correctly accepts `{ model, provider }` objects
+- [x] Validation correctly rejects malformed ModelEntry objects — errors for missing `model`, missing `provider`, invalid `provider`
+- [x] Error messages reference ModelEntry object format — says "must be a model entry object (e.g. { \"model\": \"opus\", \"provider\": \"claude\" })"
+- [x] Legacy string-based model values are rejected with a helpful migration message — same error message above
+- [x] All existing tests pass — 141 tests pass
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/outcomes/2-update-commit-format.md

@@ -0,0 +1,31 @@
+# Outcome: Update Commit Message Format
+
+## Summary
+
+Changed commit messages to use project name (from folder) instead of numeric project ID, and added auto-generated descriptions for Plan and Amend commits.
+
+## Changes Made
+
+- **`src/types/config.ts`**: Updated DEFAULT_CONFIG commit format templates from `{projectId}` to `{projectName}`, and changed plan/amend templates to use `{description}` for auto-generated summaries
+- **`src/core/git.ts`**: Added `extractPlanDescription()` (reads first line of input.md) and `extractAmendDescription()` (generates description from plan file names). Updated `commitPlanningArtifacts()` to pass `projectName` for both `{projectName}` and `{projectId}` (backwards compat), plus auto-generated `{description}`
+- **`src/prompts/execution.ts`**: Updated `getExecutionPrompt()` to extract project name from path and pass it as both `projectName` and `projectId` variables
+- **`src/prompts/config-docs.md`**: Updated template variable documentation and examples to reflect new format
+- **Tests**: Updated all commit format assertions in `commit-planning-artifacts.test.ts`, `commit-planning-artifacts-worktree.test.ts`, `config.test.ts`, and `execution-prompt.test.ts`
+
+## New Commit Format Examples
+
+- Task: `RAF[swiss-army:1] Fix auth validation`
+- Plan: `RAF[swiss-army] Plan: update commit message format...`
+- Amend: `RAF[swiss-army] Amend: fix-bug, add-tests`
+
+## Acceptance Criteria Status
+
+- [x] Task commits use project name: `RAF[swiss-army:01] Description`
+- [x] Plan commits include auto-generated summary: `RAF[swiss-army] Plan: summary from input.md`
+- [x] Amend commits include description: `RAF[swiss-army] Amend: task-names or "updated plans"`
+- [x] Commit format templates are configurable via `commitFormat` in config
+- [x] `{projectName}` placeholder is documented and works in templates
+- [x] Old `{projectId}` placeholder still works for backwards compatibility (resolves to projectName)
+- [x] All existing tests pass (1227 pass, 2 pre-existing failures unrelated to this change)
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/outcomes/3-wire-reasoning-effort.md

@@ -0,0 +1,28 @@
+# Outcome: Wire reasoningEffort to CLI Invocations
+
+## Summary
+
+Wired the `reasoningEffort` field from ModelEntry config through to actual Claude and Codex CLI invocations. Previously, this field existed in the config type and validation but was never passed to the CLI processes.
+
+## Changes Made
+
+- **`src/core/runner-types.ts`**: Added `reasoningEffort?: string` to `RunnerConfig` interface
+- **`src/core/claude-runner.ts`**: Store `reasoningEffort` from config; pass as `--effort <level>` flag in interactive, resume, and non-interactive (stream-json) modes
+- **`src/core/codex-runner.ts`**: Store `reasoningEffort` from config; pass as `-c model_reasoning_effort="<level>"` in interactive and exec modes
+- **`src/commands/plan.ts`**: Pass `reasoningEffort` from ModelEntry through to `createRunner()` (3 call sites)
+- **`src/commands/config.ts`**: Pass `reasoningEffort` from ModelEntry through to `createRunner()`
+- **`src/commands/do.ts`**: Pass `reasoningEffort` from ModelEntry through to `createRunner()`
+
+## CLI Flags Used
+
+- **Claude CLI**: `--effort <level>` (discovered via `claude --help`)
+- **Codex CLI**: `-c model_reasoning_effort="<level>"` (discovered via codex config.toml format)
+
+## Acceptance Criteria Status
+
+- [x] Claude CLI invocations include reasoning effort flag when configured (`--effort`)
+- [x] Codex CLI invocations include reasoning effort flag when configured (`-c model_reasoning_effort`)
+- [x] No reasoning effort flag is passed when not configured (undefined/omitted) — guarded by `if (this.reasoningEffort)`
+- [x] Existing CLI invocations still work when reasoningEffort is not set — all 1227 tests pass (2 pre-existing failures unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/outcomes/4-remove-provider-flag.md

@@ -0,0 +1,27 @@
+# Outcome: Remove --provider Flag
+
+## Summary
+
+Removed the `--provider` / `-p` CLI flag from both `raf plan` and `raf do` commands. Provider is now exclusively determined by the `provider` field in each ModelEntry in the config file.
+
+## Changes Made
+
+- **`src/commands/plan.ts`**: Removed `-p, --provider` option, removed `provider` from `PlanCommandOptions` interface, removed provider override from `getModel()` calls
+- **`src/commands/do.ts`**: Removed `-p, --provider` option, removed `providerOverride` from `SingleProjectOptions`, `resolveTaskModel()`, and all `getModel()`/`resolveEffortToModel()` calls
+- **`src/utils/config.ts`**: Simplified `getModel()`, `getEffortMapping()`, and `resolveEffortToModel()` — removed `providerOverride` parameter from all three
+- **`src/types/config.ts`**: Removed `provider` field from `PlanCommandOptions` and `DoCommandOptions` interfaces
+- **`src/core/codex-runner.ts`**: Updated `getModel('execute')` call (was passing `'codex'` as provider override)
+- **`README.md`**: Removed `--provider` from command reference tables and feature descriptions
+- **`src/prompts/config-docs.md`**: Removed CLI precedence section about `--provider` override
+- **`tests/unit/plan-command-auto-flag.test.ts`**: Updated test to verify `--provider` is no longer present
+
+## Acceptance Criteria Status
+
+- [x] `raf plan --provider` no longer accepted — option removed
+- [x] `raf do --provider` no longer accepted — option removed
+- [x] `getModel()` no longer accepts a provider override parameter — simplified to single `scenario` arg
+- [x] All model resolution uses the provider from ModelEntry config — no override paths remain
+- [x] Documentation updated — README and config-docs cleaned up
+- [x] No dead code related to provider override remains — `providerOverride` grep returns zero results
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/outcomes/5-config-wizard-validation.md

@@ -0,0 +1,23 @@
+# Outcome: Add Model Name & Reasoning Effort Validation to Config Wizard
+
+## Summary
+
+Added comprehensive model name lists, reasoning effort guidance, and wizard validation instructions to `src/prompts/config-docs.md`. The config wizard agent now has all the information it needs to validate model names against known lists and guide users on reasoning effort configuration.
+
+## Changes Made
+
+- **`src/prompts/config-docs.md`**:
+  - Added "Valid Model Names" section with tables of Claude aliases (opus, sonnet, haiku) and Codex aliases (spark, codex, gpt54), their resolved model IDs, and notes on full model ID patterns
+  - Added "Prefixed Format" subsection documenting `provider/model` syntax
+  - Added "Reasoning Effort" section with valid values per provider, model support notes, and practical guidance on when to adjust effort levels
+  - Added "Validating Model Names" subsection in the Config Editing Session Instructions, instructing the wizard agent to check names against the known list, suggest web search for unknown names, catch common typos, and validate reasoning effort values per provider
+
+## Acceptance Criteria Status
+
+- [x] config-docs.md contains a list of known valid model names for Claude and Codex — tables with aliases and full IDs for both providers
+- [x] config-docs.md contains general reasoning effort guidance — valid values per provider, support notes, and usage guidance
+- [x] Config wizard prompt instructs the agent to validate model names — "Validating Model Names" section with 3-step validation flow
+- [x] Config wizard prompt instructs web search for unknown model names — step 2 suggests WebSearch tool when available
+- [x] Documentation is clear and concise — organized with tables, grouped by provider, practical guidance included
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/outcomes/6-add-fast-mode.md

@@ -0,0 +1,32 @@
+# Outcome: Add Fast Mode to Model Config
+
+## Summary
+
+Extended ModelEntry with a `fast?: boolean` option and wired it to Claude CLI invocations via `--settings '{"fastMode": true}'`. Codex does not support fast mode — documented accordingly.
+
+## Changes Made
+
+- **`src/types/config.ts`**: Added `fast?: boolean` to `ModelEntry` interface
+- **`src/core/runner-types.ts`**: Added `fast?: boolean` to `RunnerConfig` interface
+- **`src/utils/config.ts`**: Added `fast` to `VALID_MODEL_ENTRY_KEYS`, added boolean validation in `validateModelEntry()`, added merge support in `mergeModelEntry()`
+- **`src/core/claude-runner.ts`**: Store `fast` from config; pass as `--settings '{"fastMode": true}'` in interactive, resume, and non-interactive (stream-json) modes
+- **`src/commands/plan.ts`**: Pass `fast` from ModelEntry through to `createRunner()` (3 call sites)
+- **`src/commands/config.ts`**: Pass `fast` from ModelEntry through to `createRunner()`
+- **`src/commands/do.ts`**: Pass `fast` from ModelEntry through to `createRunner()`
+- **`src/prompts/config-docs.md`**: Added `fast` to ModelEntry shape, added "Fast Mode" section with description, example, and usage guidance
+
+## CLI Mechanism
+
+- **Claude CLI**: `--settings '{"fastMode": true}'` — enables fast mode via inline settings JSON
+- **Codex CLI**: Not supported — documented as Claude-only feature
+
+## Acceptance Criteria Status
+
+- [x] ModelEntry interface includes `fast?: boolean`
+- [x] Claude CLI invocations include the fast flag when configured (`--settings '{"fastMode": true}'`)
+- [x] Codex CLI invocations — documented as unsupported (Codex has no fast mode equivalent)
+- [x] Config validation accepts `fast: true/false` on model entries (boolean type check)
+- [x] No fast flag passed when not configured — guarded by `if (this.fast)`
+- [x] config-docs.md documents the fast option with examples
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/outcomes/7-config-preset.md

@@ -0,0 +1,31 @@
+# Outcome: Support Config Presets
+
+## Summary
+
+Added a `raf preset` command with save, load, list, and delete subcommands for managing named configuration profiles stored as JSON files in `~/.raf/presets/`.
+
+## Changes Made
+
+- **`src/commands/preset.ts`** (new): Implements the four subcommands:
+  - `save <name>`: Copies current `~/.raf/raf.config.json` to `~/.raf/presets/<name>.json` after validation
+  - `load <name>`: Validates the preset, copies it to active config, and shows a brief summary
+  - `list`: Shows all presets with provider and execute model info
+  - `delete <name>`: Removes a preset file
+  - Validates preset names (alphanumeric, hyphens, underscores only)
+  - Creates `~/.raf/presets/` directory automatically
+  - Validates config on both save and load
+- **`src/index.ts`**: Registered the `preset` command
+- **`README.md`**: Added preset command documentation in both the Commands section and the Command Reference table
+
+## Acceptance Criteria Status
+
+- [x] `raf preset save claude-setup` saves current config as a named preset
+- [x] `raf preset load claude-setup` restores the saved config
+- [x] `raf preset list` shows all available presets
+- [x] `raf preset delete claude-setup` removes a preset
+- [x] Preset files stored in `~/.raf/presets/`
+- [x] Error messages for missing presets, invalid names
+- [x] Loaded config is validated before applying
+- [x] README.md updated with preset commands
+
+<promise>COMPLETE</promise>

package/RAF/43-swiss-army/plans/1-fix-model-validation.md

@@ -0,0 +1,38 @@
+---
+effort: low
+---
+# Task: Fix Config Validation for Model Objects
+
+## Objective
+Fix the config validation error that incorrectly requires model values to be short aliases or full model IDs, when model objects (ModelEntry) are now the only supported format.
+
+## Context
+After migrating to ModelEntry objects (model + provider + optional fields), the validation in `src/utils/config.ts` still checks for string-based model values. Running `raf config` produces: "Config validation warning: models.plan must be a short alias (sonnet, haiku, opus) or a full model ID". This is the foundation fix needed before other config changes.
+
+## Requirements
+- Remove all legacy string-based model validation from `src/utils/config.ts`
+- Only accept ModelEntry objects (with `model`, `provider`, and optional fields)
+- Validate that each ModelEntry has required `model` (string) and `provider` ("claude" | "codex") fields
+- Validate optional fields like `reasoningEffort` when present
+- Update error messages to reference the ModelEntry object format
+- Update config-docs.md examples if they still show string-based model values
+
+## Implementation Steps
+1. Read `src/utils/config.ts` and locate the model validation logic (around lines 92-116 and the `validateConfig` function)
+2. Replace string-based model name validation with ModelEntry object shape validation
+3. Ensure `model` field within ModelEntry is still validated as a valid model name/alias
+4. Ensure `provider` field is validated as "claude" or "codex"
+5. Update any error messages to show correct expected format
+6. Test by reviewing what `raf config` would produce with a valid ModelEntry config
+
+## Acceptance Criteria
+- [ ] No validation warnings when config uses ModelEntry objects with valid model names
+- [ ] Validation correctly rejects malformed ModelEntry objects (missing model, missing provider, invalid provider)
+- [ ] Error messages reference ModelEntry object format, not string aliases
+- [ ] Legacy string-based model values are rejected with a helpful migration message
+- [ ] All existing tests pass (if any)
+
+## Notes
+- The ModelEntry interface is defined in `src/types/config.ts` (lines 33-40)
+- Valid model aliases: sonnet, haiku, opus (Claude); spark, codex, gpt54 (Codex)
+- Valid full IDs: claude-{family}-{version} pattern, gpt-{major}.{minor} pattern

package/RAF/43-swiss-army/plans/2-update-commit-format.md

@@ -0,0 +1,46 @@
+---
+effort: medium
+---
+# Task: Update Commit Message Format
+
+## Objective
+Change commit messages to use project name (from folder) instead of project ID, and add auto-generated descriptions for Plan and Amend commits.
+
+## Context
+Currently commits use numeric project IDs like `RAF[005:01]`. The new format should use the project folder name (kebab-case, without number prefix) and provide meaningful descriptions for plan/amend commits summarized from the project's input.md.
+
+## Dependencies
+1
+
+## Requirements
+- Extract project name from folder: `43-swiss-army` → `swiss-army` (drop numeric prefix, keep kebab-case)
+- Task commits: `RAF[swiss-army:01] Description here`
+- Plan commits: `RAF[swiss-army] Plan: <summary from input.md>` — a short project summary
+- Amend commits: `RAF[swiss-army] Amend: <description of what was amended>`
+- Update commit format templates in DEFAULT_CONFIG to use `{projectName}` placeholder
+- Make commit format templates configurable in raf.config.json (they already partially are via `commitFormat`)
+- Auto-generate plan description by summarizing plan task names or input.md content
+- Auto-generate amend description from what changed (e.g., amended task names)
+
+## Implementation Steps
+1. Read `src/types/config.ts` — update DEFAULT_CONFIG `commitFormat` templates to use `{projectName}` instead of `{projectId}`
+2. Read `src/utils/config.ts` — update `renderCommitMessage()` to populate `{projectName}` variable
+3. Add a utility to extract project name from folder path: strip numeric prefix and dash (e.g., `43-swiss-army` → `swiss-army`)
+4. Read `src/core/git.ts` — update `commitPlanningArtifacts()` and any other commit functions to pass `projectName`
+5. Read `src/prompts/execution.ts` — update the execution prompt's commit message instructions to use new format
+6. For Plan commits: generate description by summarizing plan file names or reading input.md first few lines
+7. For Amend commits: generate description from the amended plan files or changes made
+8. Update config-docs.md to document the new commit format template variables
+
+## Acceptance Criteria
+- [ ] Task commits use project name: `RAF[swiss-army:01] Description`
+- [ ] Plan commits include auto-generated summary: `RAF[swiss-army] Plan: summary here`
+- [ ] Amend commits include description: `RAF[swiss-army] Amend: what changed`
+- [ ] Commit format templates are configurable via `commitFormat` in config
+- [ ] `{projectName}` placeholder is documented and works in templates
+- [ ] Old `{projectId}` placeholder still works for backwards compatibility (resolves to same as projectName)
+
+## Notes
+- `renderCommitMessage()` in `src/utils/config.ts` (line 624) handles template variable substitution via regex `/\{(\w+)\}/g`
+- Plan description should be concise — one short sentence summarizing the project scope
+- For amend, the description could list which tasks were amended

package/RAF/43-swiss-army/plans/3-wire-reasoning-effort.md

@@ -0,0 +1,39 @@
+---
+effort: medium
+---
+# Task: Wire reasoningEffort to CLI Invocations
+
+## Objective
+Pass the `reasoningEffort` field from ModelEntry config to the actual Claude and Codex CLI invocations.
+
+## Context
+The `reasoningEffort` field exists in the ModelEntry interface and config validation, but is never passed to the CLI when spawning claude or codex processes. This makes it a no-op configuration.
+
+## Dependencies
+1
+
+## Requirements
+- Pass `reasoningEffort` to Claude CLI when invoking it (research the correct flag)
+- Pass `reasoningEffort` to Codex CLI when invoking it (research the correct flag)
+- Only include the flag when `reasoningEffort` is explicitly set in the ModelEntry
+- Valid values: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'
+
+## Implementation Steps
+1. Research how Claude CLI accepts reasoning effort — check `claude --help` or web docs for the flag name (likely `--reasoning-effort` or similar)
+2. Research how Codex CLI accepts reasoning effort — check `codex --help` or web docs
+3. Read `src/core/claude-runner.ts` — add reasoning effort flag to the CLI args array in both interactive and non-interactive modes
+4. Read `src/core/codex-runner.ts` — add reasoning effort flag to the CLI args array in both interactive and exec modes
+5. Ensure the flag is only added when `reasoningEffort` is defined in the ModelEntry
+6. Test that the args are correctly constructed
+
+## Acceptance Criteria
+- [ ] Claude CLI invocations include reasoning effort flag when configured
+- [ ] Codex CLI invocations include reasoning effort flag when configured
+- [ ] No reasoning effort flag is passed when not configured (undefined/omitted)
+- [ ] Existing CLI invocations still work when reasoningEffort is not set
+
+## Notes
+- ClaudeRunner is at `src/core/claude-runner.ts`, CodexRunner at `src/core/codex-runner.ts`
+- The runner receives model config via RunnerConfig or similar — trace how ModelEntry flows to the runner
+- Claude CLI flag is likely `--reasoning-effort <value>` but verify
+- Codex CLI flag needs research — may differ from Claude

package/RAF/43-swiss-army/plans/4-remove-provider-flag.md

@@ -0,0 +1,43 @@
+---
+effort: medium
+---
+# Task: Remove --provider Flag
+
+## Objective
+Remove the `--provider` CLI flag from all commands, relying entirely on the ModelEntry object's `provider` field in config.
+
+## Context
+The `--provider` flag is redundant now that every ModelEntry includes a `provider` field. Since this is a greenfield project with no users, it can be removed immediately without deprecation.
+
+## Dependencies
+1
+
+## Requirements
+- Remove `--provider` / `-p` option from `raf plan` command
+- Remove `--provider` / `-p` option from `raf do` command
+- Remove the `providerOverride` parameter from `getModel()` in config utils
+- Validate in config that every model entry has a `provider` field (should already be done after task 1)
+- Remove HarnessProvider type if it's only used for the flag (check usage first)
+- Clean up any code paths that handle provider override logic
+
+## Implementation Steps
+1. Read `src/commands/plan.ts` — remove `.option('-p, --provider ...')` and all references to `options.provider`
+2. Read `src/commands/do.ts` — remove `.option('-p, --provider ...')` and all references to `options.provider`
+3. Read `src/utils/config.ts` — simplify `getModel()` function to remove `providerOverride` parameter
+4. Search for any other usages of `providerOverride` or the provider flag across the codebase
+5. Check if `HarnessProvider` type is still needed elsewhere; if only used for the flag, consider keeping it for config validation only
+6. Update README.md to remove --provider flag documentation
+7. Update config-docs.md if it references --provider
+
+## Acceptance Criteria
+- [ ] `raf plan --provider` no longer accepted
+- [ ] `raf do --provider` no longer accepted
+- [ ] `getModel()` no longer accepts a provider override parameter
+- [ ] All model resolution uses the provider from ModelEntry config
+- [ ] Documentation updated
+- [ ] No dead code related to provider override remains
+
+## Notes
+- `getModel()` is at `src/utils/config.ts` line ~409
+- Provider override logic: `if (providerOverride) { return { ...entry, provider: providerOverride }; }`
+- HarnessProvider type may still be needed for the ModelEntry interface itself

package/RAF/43-swiss-army/plans/5-config-wizard-validation.md

@@ -0,0 +1,42 @@
+---
+effort: medium
+---
+# Task: Add Model Name & Reasoning Effort Validation to Config Wizard
+
+## Objective
+Update config-docs.md and the config wizard prompt to include a hardcoded list of valid model names and general reasoning effort guidance, with instructions to search the web for latest information.
+
+## Context
+The config wizard (used by `raf config`) needs to help users pick valid model names and understand reasoning effort options. Currently, config-docs.md doesn't provide enough guidance on which exact model names are valid or which models support reasoning effort.
+
+## Dependencies
+1
+
+## Requirements
+- Add a hardcoded list of known-good model names/aliases to config-docs.md for both Claude and Codex
+- Include general guidance about reasoning effort: what it does, which providers support it, valid values
+- Add instructions in the config wizard prompt to search the web for latest model names if the user wants to use a model not in the list
+- Don't document model-specific reasoning effort details — keep it general with links to provider docs
+- Validate exact model names in the config wizard conversation (the wizard agent should check names against the list)
+
+## Implementation Steps
+1. Read `src/prompts/config-docs.md` — understand current structure
+2. Add a "Valid Model Names" section with known aliases and full IDs for Claude (sonnet, haiku, opus, claude-sonnet-4-5-20250929, etc.) and Codex (spark, codex, gpt54, gpt-5.4, etc.)
+3. Add a "Reasoning Effort" section with general guidance: available for supporting models, valid values (none, minimal, low, medium, high, xhigh, max), link to Anthropic/OpenAI docs
+4. Read `src/commands/config.ts` — update the config wizard system prompt to instruct the agent to:
+   - Validate model names against the known list
+   - If user enters an unknown model name, suggest searching the web for validity
+   - Provide reasoning effort guidance when configuring model entries
+5. Ensure the wizard prompt tells the agent to use WebSearch tool if available to verify unfamiliar model names
+
+## Acceptance Criteria
+- [ ] config-docs.md contains a list of known valid model names for Claude and Codex
+- [ ] config-docs.md contains general reasoning effort guidance
+- [ ] Config wizard prompt instructs the agent to validate model names
+- [ ] Config wizard prompt instructs web search for unknown model names
+- [ ] Documentation is clear and concise
+
+## Notes
+- The config wizard runs as an interactive Claude session with config-docs.md as context
+- The wizard agent may or may not have WebSearch available — the prompt should suggest it as best-effort
+- Keep the model list maintainable — group by provider, note that aliases resolve to specific versions