fix: address code review findings

- document {{TASK_HEADER_PATTERNS}} in CLAUDE.md and README.md variable lists
- update CLAUDE.md 'Plan format' key pattern to reflect configurable headers
  and the removal of the package-level taskHeaderPattern regex
- rename TestDefaultPatternsMatchLegacyRegex and rewrite its comment to be
  honest: the template-driven compiler is stricter than the legacy regex
  about whitespace, so the test only covers canonical inputs
- exclude gosec G704 (SSRF taint) in *_test.go files; false positive on
  httptest server URLs in pkg/web/watcher_test.go

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

@@ -61,7 +61,7 @@ docs/plans/         # plan files location
 
 ## Key Patterns
 
-- Plan format: Checkboxes (`- [ ]` / `- [x]`) belong only in Task sections (`### Task N:` or `### Iteration N:`). The `Task` / `Iteration` keywords are structural tokens matched by `pkg/plan/parse.go` (`taskHeaderPattern`) and MUST stay in English even when plan content is written in another language — task titles and body text may be localized, but the section header keyword is fixed. Success criteria, Overview, and Context should not use checkboxes — they cause extra loop iterations. The task prompt handles them when present, but plan authors should avoid them.
+- Plan format: Checkboxes (`- [ ]` / `- [x]`) belong only in Task sections. By default, headers matching `### Task {N}: {title}` or `### Iteration {N}: {title}` are recognized; the `Task` / `Iteration` keywords are structural tokens and MUST stay in English even when plan content is written in another language — task titles and body text may be localized, but the default section header keywords are fixed. Recognized header shapes are configurable via `task_header_patterns` (compiled by `pkg/plan/patterns.go`, passed to `pkg/plan/parse.go` `ParsePlan`/`ParsePlanFile` as a variadic `patterns ...string`; empty falls back to `plan.DefaultTaskHeaderPatterns`). Success criteria, Overview, and Context should not use checkboxes — they cause extra loop iterations. The task prompt handles them when present, but plan authors should avoid them.
 - Signal-based completion detection (COMPLETED, FAILED, REVIEW_DONE signals) — constants in `pkg/status/`
 - Plan creation signals: QUESTION (with JSON payload) and PLAN_READY
 - Streaming output with timestamps
@@ -373,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}}` - quoted, `or`-joined list of configured `task_header_patterns` templates (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

@@ -692,6 +692,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}}` | Quoted, `or`-joined list of configured `task_header_patterns` templates (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:**

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 headerPatterns []string
+		if req.Config != nil {
+			headerPatterns = 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,
+			NoColor:            o.NoColor,
+			TaskHeaderPatterns: headerPatterns,
 		}, 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,
+		NoColor:            o.NoColor,
+		TaskHeaderPatterns: req.Config.TaskHeaderPatterns,
 	}, 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,
+		NoColor:            o.NoColor,
+		TaskHeaderPatterns: req.Config.TaskHeaderPatterns,
 	}, req.Colors, holder)
 	if err != nil {
 		return fmt.Errorf("create progress logger: %w", err)

pkg/plan/parse.go

@@ -71,6 +71,37 @@ func matchTaskHeader(line string, compiled []*regexp.Regexp) (taskID, title stri
 	return "", "", false
 }
 
+// headingLevel returns the number of leading '#' characters on a line, or 0 if
+// the line is not a markdown heading. a line starting with '#' is considered a
+// heading regardless of whether a space follows (matching the legacy behavior
+// that used strings.HasPrefix without whitespace checks).
+func headingLevel(line string) int {
+	i := 0
+	for i < len(line) && line[i] == '#' {
+		i++
+	}
+	return i
+}
+
+// closesTask reports whether a non-task-matching heading at lineLevel should
+// close a task opened at taskLevel. strictly shallower headings always close
+// (they start a new top-level section). same-level headings close only when
+// the task lives at the top of the document tree (level 1 or 2), because at
+// those levels a same-level heading is a sibling section, not a sub-note; at
+// deeper levels a same-level non-matching heading is treated as a note inside
+// the task so its checkboxes remain attached. see parse_test.go cases
+// "non-matching h3 does NOT close current task" and
+// "H1 task template closes preceding task on later non-task H1".
+func closesTask(lineLevel, taskLevel int) bool {
+	if lineLevel <= 0 || taskLevel <= 0 {
+		return false
+	}
+	if lineLevel < taskLevel {
+		return true
+	}
+	return lineLevel == taskLevel && taskLevel <= 2
+}
+
 // ParsePlan parses plan markdown content into a structured Plan.
 // patterns is an optional variadic list of task-header templates (e.g.
 // "### Task {N}: {title}"). If empty, DefaultTaskHeaderPatterns is used.
@@ -86,19 +117,15 @@ func ParsePlan(content string, patterns ...string) (*Plan, error) {
 
 	scanner := bufio.NewScanner(strings.NewReader(content))
 	var currentTask *Task
+	currentTaskLevel := 0 // heading level (# count) of the currently open task
 
 	for scanner.Scan() {
 		line := scanner.Text()
+		level := headingLevel(line)
 
-		// check for plan title (first h1)
-		if p.Title == "" {
-			if matches := titlePattern.FindStringSubmatch(line); matches != nil {
-				p.Title = strings.TrimSpace(matches[1])
-				continue
-			}
-		}
-
-		// check for task header (first match wins across configured patterns)
+		// check for task header first (first match wins across configured patterns).
+		// runs before the H1 title capture so a custom H1 task template like
+		// "# {N}. {title}" is not silently consumed as the plan title.
 		if id, title, matched := matchTaskHeader(line, compiled); matched {
 			// save previous task if exists
 			if currentTask != nil {
@@ -112,22 +139,33 @@ func ParsePlan(content string, patterns ...string) (*Plan, error) {
 				Status:     TaskStatusPending,
 				Checkboxes: make([]Checkbox, 0),
 			}
+			currentTaskLevel = level
 			continue
 		}
 
-		// non-Task section header (e.g. ## Success criteria, ## Overview, ## Context):
-		// close current task so checkboxes below are not attached to it.
-		// only ## (h2) closes; ### and #### are subsections and must not orphan checkboxes.
-		// also close on # (h1) when title already set, e.g. # Overview in plans using single hash for sections.
-		isH2 := strings.HasPrefix(line, "##") && !strings.HasPrefix(line, "###")
-		isH1AfterTitle := strings.HasPrefix(line, "#") && p.Title != "" && !strings.HasPrefix(line, "##")
-		if currentTask != nil && (isH2 || isH1AfterTitle) {
+		// non-task heading: close the current task when it starts a new section at
+		// a shallower or sibling-top-level position (see closesTask). this lets
+		// deeper headings (e.g. #### inside a ### task) stay attached to the task
+		// as sub-notes, while a ## Success criteria or # Overview still closes a
+		// ### task, and a ## Phase task is not prematurely closed by a ### note.
+		if currentTask != nil && closesTask(level, currentTaskLevel) {
 			currentTask.Status = DetermineTaskStatus(currentTask.Checkboxes)
 			p.Tasks = append(p.Tasks, *currentTask)
 			currentTask = nil
+			currentTaskLevel = 0
 			continue
 		}
 
+		// check for plan title (first h1) — only when no task header matched above
+		// and no task is open, so H1-style task templates aren't swallowed here and
+		// a later # Section doesn't retroactively become the plan title.
+		if p.Title == "" && level == 1 {
+			if matches := titlePattern.FindStringSubmatch(line); matches != nil {
+				p.Title = strings.TrimSpace(matches[1])
+				continue
+			}
+		}
+
 		// check for checkbox (only if inside a task)
 		if currentTask != nil {
 			if matches := checkboxPattern.FindStringSubmatch(line); matches != nil {

pkg/plan/parse_test.go

@@ -516,6 +516,142 @@ also no checkboxes.
 		assert.Equal(t, plan.TaskStatusPending, p.Tasks[0].Status)
 	})
 
+	t.Run("H1 task template does not lose first task to title capture", func(t *testing.T) {
+		// custom template using a single hash header; the first line must be
+		// captured as a task, not silently consumed as the plan title.
+		content := `# 1. First Phase
+
+- [ ] first item
+
+# 2. Second Phase
+
+- [ ] second item
+`
+			p, err := plan.ParsePlan(content, "# {N}. {title}")
+			require.NoError(t, err)
+			assert.Empty(t, p.Title, "first H1 must not be consumed as plan title when it matches a task template")
+			require.Len(t, p.Tasks, 2)
+			assert.Equal(t, 1, p.Tasks[0].Number)
+			assert.Equal(t, "First Phase", p.Tasks[0].Title)
+			require.Len(t, p.Tasks[0].Checkboxes, 1)
+			assert.Equal(t, 2, p.Tasks[1].Number)
+			assert.Equal(t, "Second Phase", p.Tasks[1].Title)
+	})
+
+	t.Run("H1 task template closes preceding task on later non-task H1", func(t *testing.T) {
+		// with a custom H1 task template and no separate plan title,
+		// a later non-task "# Section" must close the current task
+		// instead of being swallowed as the plan title while checkboxes
+		// below silently attach to the preceding task.
+		content := `# 1. First Phase
+
+- [ ] first item
+
+# Overview
+
+- [ ] outside
+`
+		p, err := plan.ParsePlan(content, "# {N}. {title}")
+		require.NoError(t, err)
+		require.Len(t, p.Tasks, 1)
+		assert.Equal(t, 1, p.Tasks[0].Number)
+		assert.Equal(t, "First Phase", p.Tasks[0].Title)
+		require.Len(t, p.Tasks[0].Checkboxes, 1)
+		assert.Equal(t, "first item", p.Tasks[0].Checkboxes[0].Text)
+	})
+
+	t.Run("default patterns still capture H1 plan title", func(t *testing.T) {
+		// default templates (### Task/Iteration) do not match "# Title", so the
+		// first H1 must still be captured as the plan title.
+		content := `# Plan Title
+
+### Task 1: Do Stuff
+
+- [ ] item
+`
+			p, err := plan.ParsePlan(content)
+			require.NoError(t, err)
+			assert.Equal(t, "Plan Title", p.Title)
+			require.Len(t, p.Tasks, 1)
+			assert.Equal(t, "Do Stuff", p.Tasks[0].Title)
+	})
+
+	t.Run("H1 task template: later ## subsection does NOT close task", func(t *testing.T) {
+		// with H1-level task headers, a ## subsection inside the task must remain
+		// attached (it's deeper than the task heading, so it's a sub-note).
+		content := `# 1. First Phase
+
+- [ ] main item
+
+## Details
+
+- [ ] sub item
+
+# 2. Second Phase
+
+- [ ] second main
+`
+		p, err := plan.ParsePlan(content, "# {N}. {title}")
+		require.NoError(t, err)
+
+		require.Len(t, p.Tasks, 2)
+		assert.Equal(t, 1, p.Tasks[0].Number)
+		require.Len(t, p.Tasks[0].Checkboxes, 2)
+		assert.Equal(t, "main item", p.Tasks[0].Checkboxes[0].Text)
+		assert.Equal(t, "sub item", p.Tasks[0].Checkboxes[1].Text)
+
+		assert.Equal(t, 2, p.Tasks[1].Number)
+		require.Len(t, p.Tasks[1].Checkboxes, 1)
+	})
+
+	t.Run("H4 task template: higher-level ### section closes task", func(t *testing.T) {
+		// with H4-level task headers (deeper than the default), a shallower ###
+		// section must still close the task so its checkboxes don't leak.
+		content := `# Plan
+
+#### 1. Deep Task
+
+- [ ] item inside task
+
+### Sibling Section
+
+- [ ] outside task
+`
+		p, err := plan.ParsePlan(content, "#### {N}. {title}")
+		require.NoError(t, err)
+
+		require.Len(t, p.Tasks, 1)
+		require.Len(t, p.Tasks[0].Checkboxes, 1)
+		assert.Equal(t, "item inside task", p.Tasks[0].Checkboxes[0].Text)
+	})
+
+	t.Run("H2 task template: ### sub-note stays inside task", func(t *testing.T) {
+		// for a ## task, a deeper ### heading is a sub-note and must NOT close
+		// the task (regression guard: any sibling-same-level logic must not fire here).
+		content := `# Plan
+
+## 1. Phase One
+
+- [ ] main item
+
+### Notes
+
+- [ ] still inside task
+
+## 2. Phase Two
+
+- [ ] second
+`
+		p, err := plan.ParsePlan(content, "## {N}. {title}")
+		require.NoError(t, err)
+
+		require.Len(t, p.Tasks, 2)
+		require.Len(t, p.Tasks[0].Checkboxes, 2)
+		assert.Equal(t, "main item", p.Tasks[0].Checkboxes[0].Text)
+		assert.Equal(t, "still inside task", p.Tasks[0].Checkboxes[1].Text)
+		require.Len(t, p.Tasks[1].Checkboxes, 1)
+	})
+
 	t.Run("ParsePlanFile accepts patterns variadic", func(t *testing.T) {
 		content := `# Plan