feat: raid doctor runs verify entries with self-heal (closes #42) (#87)

* feat: raid doctor runs verify entries with self-heal (closes #42)

Every verify: entry on the active profile and per-repo raid.yaml files
now runs as part of `raid doctor` and produces a finding:

  - first-try pass         → ok
  - failure → onFail → pass → warn (remediated by onFail)
  - failure that can't be healed → error

RunVerify now returns (VerifyOutcome, error) so doctor can distinguish
a clean pass from a successful self-heal — the latter is a warning so
the user knows something silently fixed itself. The remediated state
maps to the doctor warn severity; failures don't short-circuit
subsequent entries, so one run reports the full picture.

The cmd/doctor JSON shape is unchanged — verify findings flow through
the existing Finding type.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: address Copilot review on doctor verify

- doctor: load per-repo raid.yaml verify entries before running them.
  Previously the doctor path never invoked buildRepo/ExtractRepo on the
  repo, so verify blocks defined only in raid.yaml were silently skipped
  (BuildSingleRepoProfile keeps only name/path/branch; ExtractProfile
  only sees what's in the wrapping profile).
- verify: fix VerifyOutcome doc comment — describe the real tri-state
  enum rather than implying failed is a separate "fourth state".
- docs: clarify that verify tasks/onFail can be any task type
  (HTTP, Git, Template, Prompt/Confirm, SetVar, …), not just shell.
  Updates doctor.mdx warning, whats-new.mdx release note, and the
  embedded verifyArray schema description (which still said verify
  entries were inert / doctor integration was future work).
- tests: replace the pre-populated repo.Verify test with one that
  exercises the load-from-raid.yaml path, and add a merge case that
  covers both profile-level and raid.yaml verify entries.

Co-Authored-By: Copilot <copilot@github.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Mr. Meeseeks <alex.salerno+meeseeks@me.com>
Co-authored-by: Copilot <copilot@github.com>

Author: 4 people

schemas/raid-defs.schema.json

@@ -636,7 +636,7 @@
         },
         "verifyArray": {
             "type": "array",
-            "description": "Declarative precondition checks. Each entry runs `tasks:` to assert a dependency or environmental precondition; if any task exits non-zero and `onFail:` is provided, raid runs the remediation once and re-runs `tasks:` exactly once. Verify entries are inert at the CLI today — `raid doctor` (#42) surfaces them as findings. Keep checks small and fast: each entry is run on every doctor invocation.",
+            "description": "Declarative precondition checks. Each entry runs `tasks:` to assert a dependency or environmental precondition; if any task exits non-zero and `onFail:` is provided, raid runs the remediation once and re-runs `tasks:` exactly once. `raid doctor` runs every verify entry on the active profile and per-repo `raid.yaml` files and surfaces each as a finding (ok / warn / error). Keep checks small and fast: each entry is run on every doctor invocation.",
             "items": {
                 "type": "object",
                 "properties": {

site/docs/references/schema.mdx

@@ -211,7 +211,7 @@ install:
 
 Declarative precondition checks. Each entry runs `tasks:` to assert that a dependency or environmental requirement is in place. An optional `onFail:` remediation gets exactly one chance to fix things — if remediation succeeds, raid re-runs `tasks:` once; if that pass succeeds the verify is reported as remediated, otherwise it fails.
 
-Verify entries are accepted on both profiles and per-repo `raid.yaml` files. They share execution context with `install:` — the active environment, raid vars, and task options all apply. The schema accepts verify entries today; a future release will surface them through `raid doctor` (and, longer-term, a dedicated `raid verify` command).
+Verify entries are accepted on both profiles and per-repo `raid.yaml` files. They share execution context with `install:` — the active environment, raid vars, and task options all apply. `raid doctor` runs every verify entry and surfaces each as a finding: a first-try pass is an `ok` finding, a successful self-heal is a `warn` (the precondition holds now, but didn't before — worth knowing), and a failure is an `error` carrying the underlying task error.
 
 ```yaml
 verify:

site/docs/usage/doctor.mdx

@@ -27,6 +27,23 @@ Checks include:
 - Referenced task groups exist
 - Environment names are unique
 - Custom command names don't shadow built-in commands
+- Every [`verify:`](../references/schema#verify) entry on the profile and per-repo `raid.yaml` files
+
+## Verify entries
+
+If your profile or any repo's `raid.yaml` defines a [`verify:`](../references/schema#verify) block, doctor runs every entry and surfaces each as its own finding:
+
+| Outcome | Severity | What it means |
+|---|---|---|
+| First-try pass | `ok` | The verify's `tasks:` exited cleanly on the first try. |
+| Remediated | `warn` | `tasks:` failed, the optional `onFail:` block ran, and the re-run of `tasks:` then passed. The precondition holds *now* — but it didn't before, so doctor warns you to investigate why. |
+| Failed | `error` | Either no `onFail:` was defined, `onFail:` itself failed, or the retry of `tasks:` failed again. The underlying task error is included in the finding's message. |
+
+Doctor runs verify tasks with the same execution context as `install:` — the active environment, raid vars, and task options all apply. A failure on one verify entry does not prevent subsequent entries from running, so you see the full health picture in a single pass.
+
+:::warning Verify tasks execute real work
+Doctor invokes the actual `tasks:` and `onFail:` blocks you've defined — that's any task type raid supports (shell commands, HTTP, Git, Template, Prompt/Confirm, SetVar, …), not just shell. Non-shell tasks can still make network calls, mutate files, or prompt for input. Keep verify checks small, fast, and side-effect-light (a `node --version` probe, a `test -f`, a `Wait` against a local port). Heavy bootstrap work belongs in `install:`.
+:::
 
 ## When to run it
 

site/docs/whats-new.mdx

@@ -11,7 +11,9 @@ User-visible changes per release, latest first. For full commit history see the
 
 ## 0.14.0 — upcoming
 
-**Declarative `verify:` blocks.** Profiles and per-repo `raid.yaml`s now accept a top-level `verify:` list. Each entry runs `tasks:` to assert a precondition (a tool is installed, a port is reachable, a credentials file exists), and an optional `onFail:` remediation gets exactly one chance to fix things — if it succeeds, raid re-runs `tasks:` once and the verify is reported as remediated; otherwise it surfaces as a structured `VERIFY_FAILED` error. Verify entries share execution context with `install:` tasks (active env + raid vars + task options). `raid doctor` integration to surface verify entries as health-report findings follows in [#42](https://github.com/8bitAlex/raid/issues/42). See [Schema → Verify](/docs/references/schema#verify). Closes [#38](https://github.com/8bitAlex/raid/issues/38).
+**`raid doctor` runs `verify:` entries with self-heal.** Every `verify:` entry on the active profile and per-repo `raid.yaml` files now runs as part of `raid doctor` and produces its own finding: `ok` for a first-try pass, `warn` when the optional `onFail:` block recovered a failing precondition (the verify holds *now*, but didn't before — worth knowing), and `error` when the precondition can't be made to hold. Failures don't short-circuit subsequent entries, so a single `raid doctor` run reports the full picture. Doctor invokes the actual `tasks:` and `onFail:` blocks — any task type raid supports (shell, HTTP, Git, Template, Prompt/Confirm, SetVar, …), not just shell. Keep verify checks small and fast, since they'll run every time you (or CI, or an agent) checks raid's health. See [Doctor → Verify entries](/docs/usage/doctor#verify-entries). Closes [#42](https://github.com/8bitAlex/raid/issues/42).
+
+**Declarative `verify:` blocks.** Profiles and per-repo `raid.yaml`s now accept a top-level `verify:` list. Each entry runs `tasks:` to assert a precondition (a tool is installed, a port is reachable, a credentials file exists), and an optional `onFail:` remediation gets exactly one chance to fix things — if it succeeds, raid re-runs `tasks:` once and the verify is reported as remediated; otherwise it surfaces as a structured `VERIFY_FAILED` error. Verify entries share execution context with `install:` tasks (active env + raid vars + task options). `raid doctor` integration is now wired (see entry above). See [Schema → Verify](/docs/references/schema#verify). Closes [#38](https://github.com/8bitAlex/raid/issues/38).
 
 **Shared `options:` block on every task type.** A new `options:` block on the base task definition composes uniformly across every task type (and on user-defined commands) so cross-cutting fields don't have to be re-declared per type. The initial field, `showExeTime: bool`, prints a dim line to stderr after a task or command completes with the elapsed time: `task-name complete in 1.2s`. Omitting `options` (or any field within it) leaves current behavior unchanged, so the addition is fully backwards compatible. Additional fields (`quiet`, `timeout`, …) will ship additively. Closes [#54](https://github.com/8bitAlex/raid/issues/54).
 

src/internal/lib/doctor.go

@@ -88,6 +88,8 @@ func checkProfile() []Finding {
 			})
 		}
 		findings = append(findings, Finding{Severity: SeverityOK, Check: "profile schema", Message: "valid (single-repo)"})
+		// In single-repo mode, verify entries live on the synthesized
+		// repo, not the wrapper profile — checkRepo picks them up.
 		for _, repo := range fullProfile.Repositories {
 			findings = append(findings, checkRepo(repo)...)
 		}
@@ -113,6 +115,8 @@ func checkProfile() []Finding {
 		})
 	}
 
+	findings = append(findings, checkVerify("verify", fullProfile.Verify)...)
+
 	if len(fullProfile.Repositories) == 0 {
 		return append(findings, Finding{
 			Severity:   SeverityWarn,
@@ -177,12 +181,81 @@ func checkRepo(repo Repo) []Finding {
 			Message:    err.Error(),
 			Suggestion: fmt.Sprintf("fix %s to match the repo schema", raidFile),
 		})
-	} else {
+		return findings
+	}
+	findings = append(findings, Finding{
+		Severity: SeverityOK,
+		Check:    fmt.Sprintf("repo/%s raid.yaml", repo.Name),
+		Message:  "valid",
+	})
+
+	// Merge verify entries from the per-repo raid.yaml. The profile-level
+	// Repo only carries what's in the wrapping profile (or, for
+	// BuildSingleRepoProfile, just name/path/branch), so without this
+	// merge per-repo verify blocks would be silently skipped.
+	repoConfig, err := ExtractRepo(repo.Path)
+	if err != nil {
 		findings = append(findings, Finding{
-			Severity: SeverityOK,
+			Severity: SeverityError,
 			Check:    fmt.Sprintf("repo/%s raid.yaml", repo.Name),
-			Message:  "valid",
+			Message:  err.Error(),
 		})
+		return findings
+	}
+	repo.Verify = append(repo.Verify, repoConfig.Verify...)
+
+	findings = append(findings, checkVerify(fmt.Sprintf("repo/%s verify", repo.Name), repo.Verify)...)
+	return findings
+}
+
+// checkVerify runs each verify entry and converts the outcome into a
+// finding. label is the check-name prefix ("verify" for profile-level,
+// "repo/<name> verify" for repo-level). The entry's Name is appended
+// so each finding has a unique, human-readable label.
+//
+// Outcomes map to severities:
+//   - VerifyOutcomeOK         → SeverityOK
+//   - VerifyOutcomeRemediated → SeverityWarn (the verify holds now, but
+//     it didn't on the first try — worth surfacing so the user knows
+//     something silently fixed itself)
+//   - VerifyOutcomeFailed     → SeverityError
+//
+// Failures don't short-circuit subsequent entries — doctor reports every
+// verify so the user sees the full picture in one pass.
+func checkVerify(label string, entries []Verify) []Finding {
+	var findings []Finding
+	for _, v := range entries {
+		if v.IsZero() {
+			continue
+		}
+		check := fmt.Sprintf("%s/%s", label, v.Name)
+		outcome, err := RunVerify(v)
+		switch outcome {
+		case VerifyOutcomeOK:
+			findings = append(findings, Finding{
+				Severity: SeverityOK,
+				Check:    check,
+				Message:  "passed",
+			})
+		case VerifyOutcomeRemediated:
+			findings = append(findings, Finding{
+				Severity:   SeverityWarn,
+				Check:      check,
+				Message:    "remediated by onFail",
+				Suggestion: "investigate why the precondition wasn't already in place",
+			})
+		case VerifyOutcomeFailed:
+			msg := "failed"
+			if err != nil {
+				msg = err.Error()
+			}
+			findings = append(findings, Finding{
+				Severity:   SeverityError,
+				Check:      check,
+				Message:    msg,
+				Suggestion: "fix the underlying dependency or update the verify block to match reality",
+			})
+		}
 	}
 	return findings
 }

src/internal/lib/doctor_test.go

@@ -330,6 +330,234 @@ func TestCheckProfile_singleRepoInvalid(t *testing.T) {
 	}
 }
 
+// --- checkVerify ---
+
+func TestCheckVerify_passingEntryProducesOKFinding(t *testing.T) {
+	entries := []Verify{
+		{
+			Name:  "echo-works",
+			Tasks: []Task{{Type: Shell, Cmd: "exit 0"}},
+		},
+	}
+	findings := checkVerify("verify", entries)
+	if len(findings) != 1 {
+		t.Fatalf("checkVerify: got %d findings, want 1", len(findings))
+	}
+	f := findings[0]
+	if f.Severity != SeverityOK {
+		t.Errorf("severity = %v, want SeverityOK", f.Severity)
+	}
+	if f.Check != "verify/echo-works" {
+		t.Errorf("check = %q, want %q", f.Check, "verify/echo-works")
+	}
+}
+
+func TestCheckVerify_remediatedEntryProducesWarnFinding(t *testing.T) {
+	marker := filepath.Join(t.TempDir(), "fix")
+	entries := []Verify{
+		{
+			Name:   "needs-fix",
+			Tasks:  []Task{{Type: Shell, Cmd: "test -f " + marker}},
+			OnFail: []Task{{Type: Shell, Cmd: "touch " + marker}},
+		},
+	}
+	findings := checkVerify("verify", entries)
+	if len(findings) != 1 {
+		t.Fatalf("checkVerify: got %d findings, want 1", len(findings))
+	}
+	f := findings[0]
+	if f.Severity != SeverityWarn {
+		t.Errorf("severity = %v, want SeverityWarn for remediated outcome", f.Severity)
+	}
+	if f.Suggestion == "" {
+		t.Error("remediated finding should carry a suggestion")
+	}
+}
+
+func TestCheckVerify_failedEntryProducesErrorFinding(t *testing.T) {
+	entries := []Verify{
+		{
+			Name:  "broken",
+			Tasks: []Task{{Type: Shell, Cmd: "exit 1"}},
+		},
+	}
+	findings := checkVerify("verify", entries)
+	if len(findings) != 1 {
+		t.Fatalf("checkVerify: got %d findings, want 1", len(findings))
+	}
+	f := findings[0]
+	if f.Severity != SeverityError {
+		t.Errorf("severity = %v, want SeverityError", f.Severity)
+	}
+	if f.Suggestion == "" {
+		t.Error("failed finding should carry a suggestion")
+	}
+}
+
+func TestCheckVerify_skipsZeroEntries(t *testing.T) {
+	// Zero-value verify (from a stray YAML list item) should be ignored
+	// rather than producing a "passed" finding for an empty check.
+	findings := checkVerify("verify", []Verify{{}, {Name: "real", Tasks: []Task{{Type: Shell, Cmd: "exit 0"}}}})
+	if len(findings) != 1 {
+		t.Fatalf("checkVerify: got %d findings, want 1 (zero entry skipped)", len(findings))
+	}
+	if findings[0].Check != "verify/real" {
+		t.Errorf("check = %q, want %q", findings[0].Check, "verify/real")
+	}
+}
+
+func TestCheckVerify_failureDoesNotShortCircuitSubsequent(t *testing.T) {
+	// A failing verify must not prevent later entries from running —
+	// doctor needs to surface every finding in a single pass.
+	entries := []Verify{
+		{Name: "first-fails", Tasks: []Task{{Type: Shell, Cmd: "exit 1"}}},
+		{Name: "second-passes", Tasks: []Task{{Type: Shell, Cmd: "exit 0"}}},
+	}
+	findings := checkVerify("verify", entries)
+	if len(findings) != 2 {
+		t.Fatalf("checkVerify: got %d findings, want 2", len(findings))
+	}
+	if findings[0].Severity != SeverityError {
+		t.Errorf("first finding severity = %v, want SeverityError", findings[0].Severity)
+	}
+	if findings[1].Severity != SeverityOK {
+		t.Errorf("second finding severity = %v, want SeverityOK", findings[1].Severity)
+	}
+}
+
+func TestCheckVerify_emptyEntriesIsNoOp(t *testing.T) {
+	findings := checkVerify("verify", nil)
+	if len(findings) != 0 {
+		t.Errorf("expected 0 findings, got %d", len(findings))
+	}
+}
+
+// --- checkProfile with verify entries ---
+
+func TestCheckProfile_runsProfileLevelVerify(t *testing.T) {
+	setupTestConfig(t)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "profile.yaml")
+	// Profile-level verify with one passing and one failing entry.
+	body := `name: vp
+verify:
+  - name: ok
+    tasks:
+      - type: Shell
+        cmd: exit 0
+  - name: broken
+    tasks:
+      - type: Shell
+        cmd: exit 1
+`
+	if err := os.WriteFile(path, []byte(body), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if err := AddProfile(Profile{Name: "vp", Path: path}); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetProfile("vp"); err != nil {
+		t.Fatal(err)
+	}
+
+	findings := checkProfile()
+	var sawOK, sawError bool
+	for _, f := range findings {
+		if f.Check == "verify/ok" && f.Severity == SeverityOK {
+			sawOK = true
+		}
+		if f.Check == "verify/broken" && f.Severity == SeverityError {
+			sawError = true
+		}
+	}
+	if !sawOK {
+		t.Error("expected 'verify/ok' OK finding")
+	}
+	if !sawError {
+		t.Error("expected 'verify/broken' error finding")
+	}
+}
+
+// TestCheckRepo_loadsVerifyFromRaidYaml covers the doctor path's
+// responsibility for loading verify entries from the per-repo raid.yaml
+// itself. The Repo passed in has an empty Verify — production code paths
+// like BuildSingleRepoProfile only carry name/path/branch — so doctor
+// must read raid.yaml to surface its verify findings.
+func TestCheckRepo_loadsVerifyFromRaidYaml(t *testing.T) {
+	dir := t.TempDir()
+	os.MkdirAll(filepath.Join(dir, ".git"), 0755)
+	repoYaml := `name: r
+branch: main
+verify:
+  - name: hello
+    tasks:
+      - type: Shell
+        cmd: exit 0
+`
+	if err := os.WriteFile(filepath.Join(dir, RaidConfigFileName), []byte(repoYaml), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	repo := Repo{
+		Name: "r",
+		Path: dir,
+		URL:  "http://example.com/r.git",
+	}
+	findings := checkRepo(repo)
+	var sawVerify bool
+	for _, f := range findings {
+		if f.Check == "repo/r verify/hello" && f.Severity == SeverityOK {
+			sawVerify = true
+		}
+	}
+	if !sawVerify {
+		t.Errorf("expected 'repo/r verify/hello' OK finding from raid.yaml, got %+v", findings)
+	}
+}
+
+// TestCheckRepo_mergesProfileAndRaidYamlVerify covers the case where the
+// profile-level Repo entry has its own verify and the per-repo raid.yaml
+// has additional verify entries — both should surface as findings.
+func TestCheckRepo_mergesProfileAndRaidYamlVerify(t *testing.T) {
+	dir := t.TempDir()
+	os.MkdirAll(filepath.Join(dir, ".git"), 0755)
+	repoYaml := `name: r
+branch: main
+verify:
+  - name: from-file
+    tasks:
+      - type: Shell
+        cmd: exit 0
+`
+	if err := os.WriteFile(filepath.Join(dir, RaidConfigFileName), []byte(repoYaml), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	repo := Repo{
+		Name:   "r",
+		Path:   dir,
+		URL:    "http://example.com/r.git",
+		Verify: []Verify{{Name: "from-profile", Tasks: []Task{{Type: Shell, Cmd: "exit 0"}}}},
+	}
+	findings := checkRepo(repo)
+	var sawProfile, sawFile bool
+	for _, f := range findings {
+		if f.Check == "repo/r verify/from-profile" && f.Severity == SeverityOK {
+			sawProfile = true
+		}
+		if f.Check == "repo/r verify/from-file" && f.Severity == SeverityOK {
+			sawFile = true
+		}
+	}
+	if !sawProfile {
+		t.Errorf("expected 'repo/r verify/from-profile' OK finding, got %+v", findings)
+	}
+	if !sawFile {
+		t.Errorf("expected 'repo/r verify/from-file' OK finding, got %+v", findings)
+	}
+}
+
 // severitySet returns a set of all severities present in findings.
 func severitySet(findings []Finding) map[Severity]bool {
 	out := make(map[Severity]bool, len(findings))