feat: add task_header_patterns config option with preset/regex support

adds task_header_patterns config option (comma-separated list of preset
names or raw Go regexes) that controls which headers the plan parser
recognizes as task sections. supports built-in presets (default,
openspec) and arbitrary raw regexes for custom plan formats.

- preset registry in pkg/plan/presets.go with DefaultHeaderPatterns(),
  ResolveHeaderPattern(), ResolveHeaderPatterns(), PresetDescription()
- ParsePlan/ParsePlanFile accept []*regexp.Regexp; nil/empty falls back
  to DefaultHeaderPatterns()
- {{TASK_HEADER_PATTERNS}} template variable expands to human-readable
  descriptions of configured patterns in task.txt
- raw regexes validated at config load time via regexp.Compile so users
  get a clear error instead of a silent fallback to defaults
- web dashboard plan panel updated to pass patterns from config
- docs and embedded config template updated

Author: bronislav

.golangci.yml

@@ -141,6 +141,10 @@ linters:
           - noctx
           - usestdlibvars
         path: _test\.go$
+      - linters:
+          - gosec
+        text: "G704: SSRF via taint analysis"
+        path: _test\.go$
       - linters:
           - errcheck
         text: "Error return value of .*.Close.*is not checked"

CLAUDE.md

@@ -291,6 +291,7 @@ GOOS=windows GOARCH=amd64 go build ./...
 - `session_timeout` config option: per-session timeout for claude (e.g., "30m", "1h"). Kills hanging sessions and continues to next iteration. CLI flag `--session-timeout` takes precedence. Disabled by default
 - `idle_timeout` config option: kills claude sessions when no output for specified duration (e.g., "5m"). Resets on each output line, only fires when session goes silent. CLI flag `--idle-timeout` takes precedence. Disabled by default
 - `move_plan_on_completion` config option: controls whether completed plans move to `docs/plans/completed/` on success. Default `true`. Disable for workflows that manage plan lifecycle externally (spec-driven tooling with separate archive steps)
+- `task_header_patterns` config option: comma-separated list of preset names (`default`, `openspec`) or raw Go regexes controlling which headers the plan parser recognizes as task sections. Capture group 1 = task id (required), capture group 2 = title (optional). Default: `default` (matches `### Task N: title` and `### Iteration N: title`). Use `openspec` or a raw regex for spec-driven workflows that use different header shapes. Resolved via `plan.ResolveHeaderPatterns` in `pkg/plan/presets.go`. Key files: `pkg/plan/presets.go` (preset registry, `ResolveHeaderPattern`, `ResolveHeaderPatterns`, `DefaultHeaderPatterns`, `PresetDescription`); `pkg/plan/parse.go` (`ParsePlan(content string, patterns []*regexp.Regexp)`, `ParsePlanFile(path string, patterns []*regexp.Regexp)` — callers resolve `[]string` config values via `plan.ResolveHeaderPatterns` before passing; `nil`/empty slice falls back to `DefaultHeaderPatterns()`)
 
 ### Local Project Config (.ralphex/)
 
@@ -372,6 +373,7 @@ Implementation:
 - `{{DEFAULT_BRANCH}}` - detected default branch (main, master, origin/main, etc.), overridable via `--base-ref` CLI flag or `default_branch` config option
 - `{{DIFF_INSTRUCTION}}` - git diff command for current iteration (first: `git diff main...HEAD`, subsequent: `git diff`)
 - `{{PREVIOUS_REVIEW_CONTEXT}}` - previous review context block for external review iterations (empty on first iteration, formatted context on subsequent)
+- `{{TASK_HEADER_PATTERNS}}` - human-readable descriptions of configured `task_header_patterns` (preset descriptions or raw regex patterns, quoted, `or`-joined; used in `task.txt`)
 - `{{agent:name}}` - expands to Task tool instructions for the named agent
 
 Variables are also expanded inside agent content, so custom agents can use `{{DEFAULT_BRANCH}}` etc.

README.md

@@ -172,6 +172,21 @@ Set `move_plan_on_completion = false` in `~/.config/ralphex/config` or `.ralphex
 
 **When to disable:** workflows that manage plan file lifecycle externally (e.g. spec-driven tooling where the plan lives inside a bundle that a separate archive step consumes) should opt out so ralphex doesn't fight the external tool's file layout.
 
+### Plan Header Patterns (optional)
+
+By default, ralphex recognizes `### Task N: ...` and `### Iteration N: ...` as task section headers. Set `task_header_patterns` to a comma-separated list of preset names or raw Go regexes to support alternative plan formats (e.g. OpenSpec-style `## 1. Phase Name`). Each entry is either a known preset (`default`, `openspec`) or a raw Go regexp where capture group 1 is the task id and capture group 2 is the optional title.
+
+```ini
+# in ~/.config/ralphex/config or .ralphex/config
+# use built-in openspec preset
+task_header_patterns = openspec
+
+# or a raw regex
+task_header_patterns = ^## (\d+)\.\s*(.*)$
+```
+
+**When to use:** spec-driven workflows (OpenSpec etc.) whose `tasks.md` uses different header conventions than the ralphex defaults. Leaving the option unset preserves today's behavior.
+
 ### Review-Only Mode
 
 Review-only mode (`--review`) runs the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already present on the current branch. This is useful when changes were made outside ralphex — via Claude Code's built-in plan mode, manual edits, other AI agents, or any other workflow.
@@ -681,6 +696,7 @@ Custom prompt files support variable expansion. All variables use the `{{VARIABL
 | `{{PROGRESS_FILE}}` | Path to the progress log file | `.ralphex/progress/progress-feature.txt` |
 | `{{GOAL}}` | Human-readable goal description | `implementation of plan at docs/plans/feature.md` |
 | `{{DEFAULT_BRANCH}}` | Default branch name (overridable via `--base-ref` or `default_branch` config) | `main`, `master`, `origin/main` |
+| `{{TASK_HEADER_PATTERNS}}` | Human-readable descriptions of configured task header patterns (preset descriptions or raw regexes, quoted, `or`-joined; used in `task.txt`) | `'### Task N: title  or  ### Iteration N: title'` |
 | `{{agent:name}}` | Expands to Task tool instructions for the named agent | (see below) |
 
 **Agent references:**
@@ -831,6 +847,7 @@ Use `--config-dir` or `RALPHEX_CONFIG_DIR` to override the global config locatio
 | `task_retry_count` | Task retry attempts | `1` |
 | `finalize_enabled` | Enable finalize step after reviews | `false` |
 | `move_plan_on_completion` | Move completed plan file into `docs/plans/completed/` on success (disable for external plan-lifecycle workflows) | `true` |
+| `task_header_patterns` | Comma-separated preset names (`default`, `openspec`) or raw Go regexes the plan parser uses to recognize task sections. Capture group 1 = task id, group 2 = title (optional) | `default` |
 | `use_worktree` | Run each plan in an isolated git worktree (full and tasks-only modes only) | `false` |
 | `plans_dir` | Plans directory | `docs/plans` |
 | `default_branch` | Override auto-detected default branch for review diffs | auto-detect |

cmd/ralphex/main.go

@@ -399,11 +399,16 @@ func setupProgressLogger(o opts, req executePlanRequest, branch string) (progres
 		baseLog = req.ProgressLog
 	} else {
 		var err error
+		var taskHeaderPatterns []string
+		if req.Config != nil {
+			taskHeaderPatterns = req.Config.TaskHeaderPatterns
+		}
 		baseLog, err = progress.NewLogger(progress.Config{
-			PlanFile: req.PlanFile,
-			Mode:     string(req.Mode),
-			Branch:   branch,
-			NoColor:  o.NoColor,
+			PlanFile:           req.PlanFile,
+			Mode:               string(req.Mode),
+			Branch:             branch,
+			TaskHeaderPatterns: taskHeaderPatterns,
+			NoColor:            o.NoColor,
 		}, req.Colors, holder)
 		if err != nil {
 			return progressLogResult{}, fmt.Errorf("create progress logger: %w", err)
@@ -514,14 +519,15 @@ func executePlan(ctx context.Context, o opts, req executePlanRequest) error {
 	var runnerLog processor.Logger = plr.baseLog
 	if o.Serve {
 		dashboard := web.NewDashboard(web.DashboardConfig{
-			BaseLog:         plr.baseLog,
-			Port:            o.Port,
-			Host:            o.Host,
-			PlanFile:        req.PlanFile,
-			Branch:          branch,
-			WatchDirs:       o.Watch,
-			ConfigWatchDirs: req.Config.WatchDirs,
-			Colors:          req.Colors,
+			BaseLog:            plr.baseLog,
+			Port:               o.Port,
+			Host:               o.Host,
+			PlanFile:           req.PlanFile,
+			Branch:             branch,
+			WatchDirs:          o.Watch,
+			ConfigWatchDirs:    req.Config.WatchDirs,
+			Colors:             req.Colors,
+			TaskHeaderPatterns: req.Config.TaskHeaderPatterns,
 		}, plr.holder)
 		var dashErr error
 		runnerLog, dashErr = dashboard.Start(ctx)
@@ -646,10 +652,11 @@ func runWithWorktree(ctx context.Context, o opts, req executePlanRequest) (err e
 	holder := &status.PhaseHolder{}
 	branch := plan.ExtractBranchName(req.PlanFile)
 	baseLog, err := progress.NewLogger(progress.Config{
-		PlanFile: req.PlanFile,
-		Mode:     string(req.Mode),
-		Branch:   branch,
-		NoColor:  o.NoColor,
+		PlanFile:           req.PlanFile,
+		Mode:               string(req.Mode),
+		Branch:             branch,
+		TaskHeaderPatterns: req.Config.TaskHeaderPatterns,
+		NoColor:            o.NoColor,
 	}, req.Colors, holder)
 	if err != nil {
 		return fmt.Errorf("create progress logger: %w", err)
@@ -767,9 +774,10 @@ func isWatchOnlyMode(o opts, configWatchDirs []string) bool {
 func runWatchOnly(ctx context.Context, o opts, cfg *config.Config, colors *progress.Colors) error {
 	dirs := web.ResolveWatchDirs(o.Watch, cfg.WatchDirs)
 	dashboard := web.NewDashboard(web.DashboardConfig{
-		Port:   o.Port,
-		Host:   o.Host,
-		Colors: colors,
+		Port:               o.Port,
+		Host:               o.Host,
+		Colors:             colors,
+		TaskHeaderPatterns: cfg.TaskHeaderPatterns,
 	}, nil)
 	if watchErr := dashboard.RunWatchOnly(ctx, dirs); watchErr != nil {
 		return fmt.Errorf("run watch-only mode: %w", watchErr)
@@ -934,10 +942,11 @@ func runPlanMode(ctx context.Context, o opts, req executePlanRequest, selector *
 
 	// create progress logger for plan mode
 	baseLog, err := progress.NewLogger(progress.Config{
-		PlanDescription: o.PlanDescription,
-		Mode:            string(processor.ModePlan),
-		Branch:          branch,
-		NoColor:         o.NoColor,
+		PlanDescription:    o.PlanDescription,
+		Mode:               string(processor.ModePlan),
+		Branch:             branch,
+		TaskHeaderPatterns: req.Config.TaskHeaderPatterns,
+		NoColor:            o.NoColor,
 	}, req.Colors, holder)
 	if err != nil {
 		return fmt.Errorf("create progress logger: %w", err)