feat: goal and topic phases accept the full task phase set and name it in errors

CHANGELOG.md

@@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/).
 * MINOR version when you add functionality in a backwards-compatible manner, and
 * PATCH version when you make backwards-compatible bug fixes.
 
+## Unreleased
+
+- feat: `vault-cli goal set` and `topic set` accept the full canonical task phase set (`todo`, `planning`, `execution`, `ai_review`, `human_review`, `done`), and an invalid phase now exits non-zero with the validator's message listing the accepted values, rendered from the enum collection so the list cannot drift. `in_progress` stays a task-only alias and is still rejected.
+
 ## v0.174.1
 
 - fix: `session-close` prints its open-goal status lines from a new `session-close-goals.sh` resolver and requires the closer to reproduce them, so a close can no longer drop the line silently. Measured 2026-10-20: one real close ran the phase's own lookup, received `status=in_progress`, and emitted no goal line at all.

integration/cli_test.go

@@ -4821,6 +4821,56 @@ page_type: goal
 			Expect(showPhaseField(configPath, "topic", "Phase Target")).To(Equal("execution"))
 		})
 
+		It("topic set accepts ai_review and writes it to the page on disk", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+				nil,
+			)
+			defer cleanup()
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"topic", "set", "Phase Target", "phase", "ai_review",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(0))
+
+			content, err := os.ReadFile(filepath.Join(vaultPath, "Topics", "Phase Target.md"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("phase: ai_review"))
+
+			Expect(showPhaseField(configPath, "topic", "Phase Target")).To(Equal("ai_review"))
+		})
+
+		It("topic set accepts human_review and writes it to the page on disk", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+				nil,
+			)
+			defer cleanup()
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"topic", "set", "Phase Target", "phase", "human_review",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(0))
+
+			content, err := os.ReadFile(filepath.Join(vaultPath, "Topics", "Phase Target.md"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("phase: human_review"))
+
+			Expect(showPhaseField(configPath, "topic", "Phase Target")).To(Equal("human_review"))
+		})
+
 		It("topic set refuses a non-canonical phase with the validator's wording and leaves the page byte-identical", func() {
 			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
 				"Topics",
@@ -4849,7 +4899,51 @@ page_type: goal
 			Expect(err).NotTo(HaveOccurred())
 			Eventually(session).Should(gexec.Exit(1))
 
-			Expect(string(session.Err.Contents())).To(ContainSubstring("unknown topic phase 'bogus'"))
+			stderr := string(session.Err.Contents())
+			Expect(stderr).To(ContainSubstring("unknown topic phase 'bogus'"))
+			for _, valid := range []string{
+				"todo", "planning", "execution", "ai_review", "human_review", "done",
+			} {
+				Expect(stderr).To(ContainSubstring(valid))
+			}
+			Expect(sha256OfFile(topicPath)).To(Equal(before))
+		})
+
+		It("topic set refuses in_progress as a phase and names the six accepted values", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+				nil,
+			)
+			defer cleanup()
+
+			sha256OfFile := func(path string) string {
+				data, err := os.ReadFile(path)
+				Expect(err).NotTo(HaveOccurred())
+				sum := sha256.Sum256(data)
+				return fmt.Sprintf("%x", sum)
+			}
+
+			topicPath := filepath.Join(vaultPath, "Topics", "Phase Target.md")
+			before := sha256OfFile(topicPath)
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"topic", "set", "Phase Target", "phase", "in_progress",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(1))
+
+			stderr := string(session.Err.Contents())
+			Expect(stderr).To(ContainSubstring("unknown topic phase 'in_progress'"))
+			for _, valid := range []string{
+				"todo", "planning", "execution", "ai_review", "human_review", "done",
+			} {
+				Expect(stderr).To(ContainSubstring(valid))
+			}
 			Expect(sha256OfFile(topicPath)).To(Equal(before))
 		})
 
@@ -5406,4 +5500,158 @@ page_type: goal
 		})
 	})
 
+	Describe("vault-cli goal command family", func() {
+		It("goal set accepts ai_review and writes it to the page on disk", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				nil,
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+			)
+			defer cleanup()
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"goal", "set", "Phase Target", "phase", "ai_review",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(0))
+
+			content, err := os.ReadFile(filepath.Join(vaultPath, "Goals", "Phase Target.md"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("phase: ai_review"))
+
+			Expect(showPhaseField(configPath, "goal", "Phase Target")).To(Equal("ai_review"))
+		})
+
+		It("goal set accepts human_review and writes it to the page on disk", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				nil,
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+			)
+			defer cleanup()
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"goal", "set", "Phase Target", "phase", "human_review",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(0))
+
+			content, err := os.ReadFile(filepath.Join(vaultPath, "Goals", "Phase Target.md"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("phase: human_review"))
+
+			Expect(showPhaseField(configPath, "goal", "Phase Target")).To(Equal("human_review"))
+		})
+
+		It("goal set refuses a non-canonical phase with the six accepted values and leaves the page byte-identical", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				nil,
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+			)
+			defer cleanup()
+
+			sha256OfFile := func(path string) string {
+				data, err := os.ReadFile(path)
+				Expect(err).NotTo(HaveOccurred())
+				sum := sha256.Sum256(data)
+				return fmt.Sprintf("%x", sum)
+			}
+
+			goalPath := filepath.Join(vaultPath, "Goals", "Phase Target.md")
+			before := sha256OfFile(goalPath)
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"goal", "set", "Phase Target", "phase", "bogus",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(1))
+
+			stderr := string(session.Err.Contents())
+			Expect(stderr).To(ContainSubstring("unknown goal phase 'bogus'"))
+			for _, valid := range []string{
+				"todo", "planning", "execution", "ai_review", "human_review", "done",
+			} {
+				Expect(stderr).To(ContainSubstring(valid))
+			}
+			Expect(sha256OfFile(goalPath)).To(Equal(before))
+		})
+
+		It("goal set refuses in_progress as a phase and names the six accepted values", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				nil,
+				map[string]string{
+					"Phase Target": "---\nstatus: in_progress\n---\n# Phase Target\n",
+				},
+			)
+			defer cleanup()
+
+			sha256OfFile := func(path string) string {
+				data, err := os.ReadFile(path)
+				Expect(err).NotTo(HaveOccurred())
+				sum := sha256.Sum256(data)
+				return fmt.Sprintf("%x", sum)
+			}
+
+			goalPath := filepath.Join(vaultPath, "Goals", "Phase Target.md")
+			before := sha256OfFile(goalPath)
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"goal", "set", "Phase Target", "phase", "in_progress",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(1))
+
+			stderr := string(session.Err.Contents())
+			Expect(stderr).To(ContainSubstring("unknown goal phase 'in_progress'"))
+			for _, valid := range []string{
+				"todo", "planning", "execution", "ai_review", "human_review", "done",
+			} {
+				Expect(stderr).To(ContainSubstring(valid))
+			}
+			Expect(sha256OfFile(goalPath)).To(Equal(before))
+		})
+
+		It("goal get reads a hand-typed in_progress phase back unchanged", func() {
+			vaultPath, configPath, cleanup := createTempVaultWithTopicPages(
+				"Topics",
+				nil,
+				map[string]string{
+					"Legacy Phase": "---\nstatus: in_progress\nphase: in_progress\n---\n# Legacy Phase\n",
+				},
+			)
+			defer cleanup()
+
+			Expect(showPhaseField(configPath, "goal", "Legacy Phase")).To(Equal("in_progress"))
+
+			cmd := exec.Command(
+				binPath, "--config", configPath, "--vault", "test",
+				"goal", "get", "Legacy Phase", "phase",
+			)
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+			Eventually(session).Should(gexec.Exit(0))
+			Expect(string(session.Out.Contents())).To(Equal("in_progress\n"))
+
+			content, err := os.ReadFile(filepath.Join(vaultPath, "Goals", "Legacy Phase.md"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("phase: in_progress"))
+		})
+	})
+
 })

pkg/domain/goal_frontmatter.go

@@ -379,7 +379,7 @@ func (f *GoalFrontmatter) setPhaseField(ctx context.Context, value string) error
 	}
 	phase := GoalPhase(value)
 	if err := phase.Validate(ctx); err != nil {
-		return errors.Wrapf(ctx, validation.Error, "unknown goal phase '%s'", value)
+		return err
 	}
 	f.SetPhase(&phase)
 	return nil

pkg/domain/goal_frontmatter_test.go

@@ -424,6 +424,8 @@ var _ = Describe("GoalFrontmatter", func() {
 			Entry("todo", "todo"),
 			Entry("planning", "planning"),
 			Entry("execution", "execution"),
+			Entry("ai_review", "ai_review"),
+			Entry("human_review", "human_review"),
 			Entry("done", "done"),
 		)
 

pkg/domain/goal_phase.go

@@ -2,10 +2,11 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-package domain
+package domain //nolint:dupl // Goal and topic phases share the same enum shape but are distinct types
 
 import (
 	"context"
+	"strings"
 
 	"github.com/bborbe/collection"
 	"github.com/bborbe/errors"
@@ -22,6 +23,10 @@ const (
 	GoalPhasePlanning GoalPhase = "planning"
 	// GoalPhaseExecution means active work is underway.
 	GoalPhaseExecution GoalPhase = "execution"
+	// GoalPhaseAIReview means automated checks are running.
+	GoalPhaseAIReview GoalPhase = "ai_review"
+	// GoalPhaseHumanReview means manual review is required.
+	GoalPhaseHumanReview GoalPhase = "human_review"
 	// GoalPhaseDone means the goal is ready to close.
 	GoalPhaseDone GoalPhase = "done"
 )
@@ -31,6 +36,8 @@ var AvailableGoalPhases = GoalPhases{
 	GoalPhaseTodo,
 	GoalPhasePlanning,
 	GoalPhaseExecution,
+	GoalPhaseAIReview,
+	GoalPhaseHumanReview,
 	GoalPhaseDone,
 }
 
@@ -47,10 +54,20 @@ func (g GoalPhase) String() string {
 	return string(g)
 }
 
+// String returns the comma-separated list of phases in declaration order.
+func (g GoalPhases) String() string {
+	parts := make([]string, 0, len(g))
+	for _, p := range g {
+		parts = append(parts, string(p))
+	}
+	return strings.Join(parts, ", ")
+}
+
 // Validate returns an error if the phase is not a valid canonical value.
 func (g GoalPhase) Validate(ctx context.Context) error {
 	if !AvailableGoalPhases.Contains(g) {
-		return errors.Wrapf(ctx, validation.Error, "unknown goal phase '%s'", g)
+		return errors.Wrapf(ctx, validation.Error,
+			"unknown goal phase '%s' (valid: %s)", g, AvailableGoalPhases)
 	}
 	return nil
 }