diff --git a/internal/author/skill/references/debugging.md b/internal/author/skill/references/debugging.md index 1c111d06..2db65635 100644 --- a/internal/author/skill/references/debugging.md +++ b/internal/author/skill/references/debugging.md @@ -5,11 +5,12 @@ Debug from **retained evidence**, never from an agent's summary. Open the run wi diagnostics, file changes and artifacts. Each completed step also carries a `verdict`: the chosen option (`outcome → target`), a one-line reason with its provenance (`model`, `fallback` or `absent`), and the recorded artifacts the reason -refers to. Treat the reason as a claim to check against the step's output, never as -evidence in itself. Identify evidence-supported causes and say what remains -unknown. Never fix a run's symptom by editing the project by hand: fix -the pipeline definition or the Pipelines/harness service, or record the failure and -continue. +refers to. In the TUI, selecting a stage shows that verdict at the top of the +stage's result, above its output and evidence. Treat the reason as a claim to check +against the step's output, never as evidence in itself. Identify evidence-supported +causes and say what remains unknown. Never fix a run's symptom by editing the +project by hand: fix the pipeline definition or the Pipelines/harness service, or +record the failure and continue. Each playbook is *symptom → how to confirm → what to do*. diff --git a/internal/tui/run_detail.go b/internal/tui/run_detail.go index 682cd3f6..dbea91d2 100644 --- a/internal/tui/run_detail.go +++ b/internal/tui/run_detail.go @@ -284,6 +284,36 @@ func runDuration(start, end string) string { return max(time.Duration(0), last.Sub(first)).Round(time.Second).String() } +// stageVerdictLines renders a completed stage visit's derived verdict for the +// stage view: one line naming the chosen option and its concise reason, and a +// second naming the recorded artifacts the reason refers to. It returns nil for a +// nil verdict, so the view gains nothing rather than an empty heading, and it +// always states the option even when the reason is absent, so the derived choice +// is never hidden. +func stageVerdictLines(verdict *protocol.StageVerdict) []string { + if verdict == nil { + return nil + } + option := strings.TrimSpace(verdict.Option) + reason := strings.TrimSpace(verdict.Reason) + line := "Verdict:" + switch { + case option != "" && reason != "": + line += " " + option + " · " + reason + case option != "": + line += " " + option + case reason != "": + line += " " + reason + default: + return nil + } + lines := []string{line} + if len(verdict.Artifacts) > 0 { + lines = append(lines, "Referenced artifacts: "+strings.Join(verdict.Artifacts, ", ")) + } + return lines +} + func valueLines(values map[string]any) []string { if len(values) == 0 { return []string{"No data yet."} @@ -470,16 +500,6 @@ func (m Model) runSectionLines(width int) []string { step := r.Steps[m.runStepIndex-1] titles[runSectionProgress] = "Stage progress" summary = []string{m.progress(m.stepProgressStatus(step)) + " · " + runDuration(step.StartedAt, step.FinishedAt), "Route: " + outcomeLabel(step.Outcome, step.Outcome) + " → " + step.Target} - if step.Verdict != nil { - reason := strings.TrimSpace(step.Verdict.Reason) - if reason == "" { - reason = step.Verdict.Option - } - summary = append(summary, "Verdict: "+reason) - if len(step.Verdict.Artifacts) > 0 { - summary = append(summary, "Referenced artifacts: "+strings.Join(step.Verdict.Artifacts, ", ")) - } - } var stageOutput, stageInput, evidence []string if !m.runSectionClosed(runSectionResult) { stageOutput = resultDocument(step.Output, max(1, width-2)) @@ -494,7 +514,15 @@ func (m Model) runSectionLines(width int) []string { if step.Outcome != "" && step.Target != "" { stageState += " · " + outcomeLabel(step.Outcome, step.Outcome) + " → " + step.Target } - stageOutput = append([]string{stageState, ""}, stageOutput...) + // The verdict leads the stage's result: it states the chosen option and its + // concise reason and names the recorded artifacts the reason refers to, so + // the derived choice is at the top of the stage view, complementing the + // state and output below it without adding a section. + head := []string{stageState, ""} + if verdict := stageVerdictLines(step.Verdict); len(verdict) > 0 { + head = append(head, verdict...) + } + stageOutput = append(head, stageOutput...) if step.Status == "running" { stageOutput = append([]string{m.loading("Working on " + step.Stage + " · result pending"), ""}, stageOutput...) } diff --git a/internal/tui/runs_test.go b/internal/tui/runs_test.go index 8b61f913..2c47f7f8 100644 --- a/internal/tui/runs_test.go +++ b/internal/tui/runs_test.go @@ -245,9 +245,10 @@ func TestPipelineRunShortcutFiltersAndReturns(t *testing.T) { } } -// TestRunStepVerdictRenderedWhenPresent proves a step with a verdict renders the -// reason and its referenced artifacts around the progress summary, and a step -// with a nil verdict shows no verdict line. +// TestRunStepVerdictRenderedWhenPresent proves the rendered run detail states a +// completed visit's chosen option and its reason and names its referenced +// artifacts, that an absent reason still states the option, and that a step with a +// nil verdict shows no verdict line at all. func TestRunStepVerdictRenderedWhenPresent(t *testing.T) { m := runInspectionModel() m.runDetail.Steps[0].Verdict = &protocol.StageVerdict{ @@ -257,16 +258,23 @@ func TestRunStepVerdictRenderedWhenPresent(t *testing.T) { Artifacts: []string{"captures/shot.png", "report.txt"}, } m.runStepIndex = 1 - m.toggleRunSection(runSectionProgress) - text := ansi.Strip(strings.Join(m.runSectionLines(90), "\n")) - for _, want := range []string{"Verdict: Tests passed and the evidence is retained", "Referenced artifacts: captures/shot.png, report.txt"} { - if !strings.Contains(text, want) { - t.Fatalf("verdict detail missing %q:\n%s", want, text) + view := ansi.Strip(m.runsDetailsView(24)) + for _, want := range []string{ + "Verdict: success → verifier · Tests passed and the evidence is retained", + "Referenced artifacts: captures/shot.png, report.txt", + } { + if !strings.Contains(view, want) { + t.Fatalf("verdict detail missing %q:\n%s", want, view) } } + // An absent reason still states the chosen option rather than dropping it. + optionOnly := &protocol.StageVerdict{Option: "success → verifier", ReasonSource: protocol.VerdictReasonAbsent} + if got := ansi.Strip(strings.Join(stageVerdictLines(optionOnly), "\n")); got != "Verdict: success → verifier" { + t.Fatalf("option-only verdict = %q", got) + } m.runDetail.Steps[0].Verdict = nil - text = ansi.Strip(strings.Join(m.runSectionLines(90), "\n")) - if strings.Contains(text, "Verdict:") || strings.Contains(text, "Referenced artifacts:") { - t.Fatalf("nil verdict must show no verdict line:\n%s", text) + view = ansi.Strip(m.runsDetailsView(24)) + if strings.Contains(view, "Verdict:") || strings.Contains(view, "Referenced artifacts:") { + t.Fatalf("nil verdict must show no verdict line:\n%s", view) } }