# M7 — Reflection Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add the fourth AI role — the **Reviewer** — so that when a session ends the daemon reflects on it (read against recent sessions), shows a one-line recap on the Review screen, and carries a one-line takeaway forward to ground the coach on the next planning cycle.

**Architecture:** A new leaf `ai.Reviewer` role (primitives only) mirrors Coach/DriftJudge/Nudge. The `session.Controller` fetches a reflection asynchronously on entering Review (generation-guarded, non-blocking, graceful), caches the recap, and stores a latest-wins `carryForward` that rides the existing snapshot and composes into the coach's existing free-form `grounding` string — so `ai.Coach`'s signature is unchanged. The two short lines are display data, so they cross the wire (unlike the M6 profile). Persistence is snapshot-only; no audit-chain changes.

**Tech Stack:** Go 1.26, stdlib only (`context`, `encoding/json`, `fmt`, `strings`); `go test` for tests; vanilla JS/CSS for the UI.

**Design spec:** `docs/superpowers/specs/2026-06-01-m7-reflection-design.md`

---

## File Structure

- **Create** `internal/ai/reflection.go` — the `Reflection` struct, `Reviewer` interface, `Service.Review`, prompt builder, parser.
- **Create** `internal/ai/reflection_test.go` — prompt + parser + service tests.
- **Modify** `internal/store/audit.go` — add exported `RecentSessions(path, n)`.
- **Modify** `internal/store/audit_test.go` — test `RecentSessions`.
- **Modify** `internal/store/store.go` — add reflection fields to `Snapshot`.
- **Modify** `internal/session/session.go` — reviewer field/constants, `SetReviewer`, `startReflectionFetchLocked`, `enterReview` hook, projection (Review + Planning), snapshot persist/restore, grounding composition in `RequestCoach`.
- **Modify** `internal/session/session_test.go` — reviewer fakes + reflection tests.
- **Modify** `cmd/antidriftd/main.go` — wire the reviewer (`ctrl.SetReviewer`).
- **Modify** `internal/web/web_test.go` — assert the reflection crosses the wire.
- **Modify** `internal/web/static/app.js` — render recap on Review, carry-forward on Planning.
- **Modify** `internal/web/static/app.css` — one styling line.
- **Modify** `README.md` — M7 Status paragraph.

> **Note on intermediate build state:** No task changes an existing exported signature, so the tree builds green after every task. (M7 adds to the `ai`/`store`/`session` APIs; it changes none.)

---

## Task 1: The `ai.Reviewer` role

**Files:**
- Create: `internal/ai/reflection.go`
- Test: `internal/ai/reflection_test.go`

The `ai` package is a leaf: it takes only primitive strings. The controller (Task 3) builds the `finished` and `history` strings. The existing `fakeBackend` (in `coach_test.go`, same package) is reused by the tests here — do **not** redefine it.

- [ ] **Step 1: Write the failing tests**

Create `internal/ai/reflection_test.go`:

```go
package ai

import (
	"context"
	"errors"
	"strings"
	"testing"
)

func TestReviewPromptIncludesSessionAndHistory(t *testing.T) {
	fb := &fakeBackend{out: `{"recap":"r","carry_forward":"c"}`}
	if _, err := NewService(fb).Review(context.Background(), "FINISHED-BLOCK", "HISTORY-BLOCK"); err != nil {
		t.Fatalf("review: %v", err)
	}
	if !strings.Contains(fb.gotPrompt, "FINISHED-BLOCK") {
		t.Fatalf("prompt missing finished session: %s", fb.gotPrompt)
	}
	if !strings.Contains(fb.gotPrompt, "HISTORY-BLOCK") || !strings.Contains(fb.gotPrompt, "Recent sessions") {
		t.Fatalf("prompt missing history block: %s", fb.gotPrompt)
	}
}

func TestReviewPromptOmitsEmptyHistory(t *testing.T) {
	fb := &fakeBackend{out: `{"recap":"r","carry_forward":"c"}`}
	if _, err := NewService(fb).Review(context.Background(), "FINISHED-BLOCK", ""); err != nil {
		t.Fatalf("review: %v", err)
	}
	if strings.Contains(fb.gotPrompt, "Recent sessions") {
		t.Fatalf("empty history must not add a history header: %s", fb.gotPrompt)
	}
}

func TestReviewServiceParsesReflection(t *testing.T) {
	fb := &fakeBackend{out: `sure: {"recap":"held focus on the port","carry_forward":"start in the editor next time"}`}
	refl, err := NewService(fb).Review(context.Background(), "f", "h")
	if err != nil {
		t.Fatalf("review: %v", err)
	}
	if refl.Recap != "held focus on the port" || refl.CarryForward != "start in the editor next time" {
		t.Fatalf("bad reflection: %+v", refl)
	}
}

func TestReviewServiceBackendError(t *testing.T) {
	fb := &fakeBackend{err: errors.New("boom")}
	if _, err := NewService(fb).Review(context.Background(), "f", "h"); err == nil {
		t.Fatal("want backend error")
	}
}

func TestParseReflectionEmpty(t *testing.T) {
	if _, err := parseReflection(""); !errors.Is(err, ErrEmptyResponse) {
		t.Fatalf("want ErrEmptyResponse, got %v", err)
	}
}

func TestParseReflectionNoJSON(t *testing.T) {
	if _, err := parseReflection("I cannot help."); !errors.Is(err, ErrNoJSON) {
		t.Fatalf("want ErrNoJSON, got %v", err)
	}
}

func TestParseReflectionRequiresRecap(t *testing.T) {
	if _, err := parseReflection(`{"recap":"  ","carry_forward":"x"}`); !errors.Is(err, ErrInvalidReflection) {
		t.Fatalf("blank recap should be invalid, got %v", err)
	}
}

func TestParseReflectionAllowsEmptyCarryForward(t *testing.T) {
	refl, err := parseReflection(`{"recap":"did the thing","carry_forward":""}`)
	if err != nil {
		t.Fatalf("carry_forward may be empty: %v", err)
	}
	if refl.Recap != "did the thing" || refl.CarryForward != "" {
		t.Fatalf("bad reflection: %+v", refl)
	}
}
```

- [ ] **Step 2: Run the tests to verify they fail**

Run: `go test ./internal/ai/ -run Refl -v`
Expected: build failure — `undefined: parseReflection`, `undefined: ErrInvalidReflection`, `Review` not a method of `*Service`.

- [ ] **Step 3: Write the implementation**

Create `internal/ai/reflection.go`:

```go
package ai

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"strings"
)

// Reflection is the reviewer's output: two short, single-line fields.
type Reflection struct {
	Recap        string // backward-looking: how the session went (shown on Review)
	CarryForward string // forward-looking: one takeaway for the next session
}

// Reviewer reflects on a just-finished session, read against recent history. It
// takes primitives, not domain/store types, so ai stays a leaf package.
//
//	finished: a compact description of the session that just ended.
//	history:  a compact description of the last few prior sessions ("" if none).
type Reviewer interface {
	Review(ctx context.Context, finished, history string) (Reflection, error)
}

// ErrInvalidReflection marks output that parsed as JSON but lacked a usable
// recap, so callers can distinguish "no attempt" from "bad attempt".
var ErrInvalidReflection = errors.New("ai: invalid reflection")

// Review makes Service satisfy Reviewer over the same backend as Coach.
func (s *Service) Review(ctx context.Context, finished, history string) (Reflection, error) {
	out, err := s.backend.Run(ctx, buildReviewPrompt(finished, history))
	if err != nil {
		return Reflection{}, err
	}
	return parseReflection(out)
}

func buildReviewPrompt(finished, history string) string {
	preamble := `You are a focus reviewer. A work session just ended. Reflect on it in two short lines.

Respond with ONLY a JSON object, no prose and no code fences, exactly this shape:
{"recap": "<one sentence: how this session went>", "carry_forward": "<one sentence: the single most useful thing to do differently next session>"}

Rules:
- recap: one short sentence, backward-looking, grounded in the session below.
- carry_forward: one short, actionable sentence for the next session. It may reference patterns across the recent sessions if any are given.
- Keep each field to a single short sentence.`

	hist := ""
	if strings.TrimSpace(history) != "" {
		hist = "\n\n## Recent sessions (oldest first)\n" + history
	}
	return preamble + "\n\n## Session that just ended\n" + finished + hist
}

type rawReflection struct {
	Recap        string `json:"recap"`
	CarryForward string `json:"carry_forward"`
}

// parseReflection extracts a Reflection from raw CLI output. A blank recap is
// rejected (ErrInvalidReflection); an empty carry_forward is allowed.
func parseReflection(s string) (Reflection, error) {
	if strings.TrimSpace(s) == "" {
		return Reflection{}, ErrEmptyResponse
	}
	if strings.IndexByte(s, '{') < 0 {
		return Reflection{}, ErrNoJSON
	}
	jsonStr, err := extractJSON(s)
	if err != nil {
		return Reflection{}, fmt.Errorf("%w: %v", ErrInvalidReflection, err)
	}
	var raw rawReflection
	if err := json.Unmarshal([]byte(jsonStr), &raw); err != nil {
		return Reflection{}, fmt.Errorf("%w: %v", ErrInvalidReflection, err)
	}
	recap := strings.TrimSpace(raw.Recap)
	if recap == "" {
		return Reflection{}, ErrInvalidReflection
	}
	return Reflection{Recap: recap, CarryForward: strings.TrimSpace(raw.CarryForward)}, nil
}
```

- [ ] **Step 4: Run the tests to verify they pass**

Run: `go test ./internal/ai/ -v`
Expected: PASS (all existing `ai` tests plus the new reflection tests).

- [ ] **Step 5: Commit**

```bash
git add internal/ai/reflection.go internal/ai/reflection_test.go
git commit -m "Add reviewer role to the ai port

A fourth leaf role: Review(finished, history) returns a two-line
Reflection (recap + carry_forward) over the same CLI backend as the
coach. Primitive-only, with a JSON prompt and a tolerant parser that
rejects a blank recap but allows an empty carry_forward.

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

---

## Task 2: `store.RecentSessions`

**Files:**
- Modify: `internal/store/audit.go`
- Test: `internal/store/audit_test.go`

`readSummaries` is unexported. Add a bounded, exported reader returning the last *n* summaries in **oldest-first** order. The controller formats these into the `history` string.

- [ ] **Step 1: Write the failing test**

Append to `internal/store/audit_test.go`:

```go
func TestRecentSessionsReturnsLastNOldestFirst(t *testing.T) {
	path := auditFixture(t)
	for _, id := range []string{"a", "b", "c"} {
		if err := AppendSession(path, sampleSummary("session-"+id)); err != nil {
			t.Fatalf("append %s: %v", id, err)
		}
	}
	got, err := RecentSessions(path, 2)
	if err != nil {
		t.Fatalf("recent: %v", err)
	}
	if len(got) != 2 {
		t.Fatalf("want 2 summaries, got %d", len(got))
	}
	if got[0].SessionID != "session-b" || got[1].SessionID != "session-c" {
		t.Fatalf("want [b c] oldest-first, got [%s %s]", got[0].SessionID, got[1].SessionID)
	}
}

func TestRecentSessionsFewerThanN(t *testing.T) {
	path := auditFixture(t)
	_ = AppendSession(path, sampleSummary("session-a"))
	got, err := RecentSessions(path, 5)
	if err != nil {
		t.Fatalf("recent: %v", err)
	}
	if len(got) != 1 || got[0].SessionID != "session-a" {
		t.Fatalf("want [a], got %+v", got)
	}
}

func TestRecentSessionsMissingOrZero(t *testing.T) {
	if got, err := RecentSessions(auditFixture(t), 5); err != nil || got != nil {
		t.Fatalf("missing chain: want (nil,nil), got (%+v,%v)", got, err)
	}
	path := auditFixture(t)
	_ = AppendSession(path, sampleSummary("session-a"))
	if got, err := RecentSessions(path, 0); err != nil || got != nil {
		t.Fatalf("n=0: want (nil,nil), got (%+v,%v)", got, err)
	}
}
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `go test ./internal/store/ -run RecentSessions -v`
Expected: build failure — `undefined: RecentSessions`.

- [ ] **Step 3: Write the implementation**

Add to `internal/store/audit.go` (after the `readSummaries` function):

```go
// RecentSessions returns up to n most-recent summaries from the audit chain in
// oldest-first order. A missing/empty chain or n <= 0 yields (nil, nil).
func RecentSessions(path string, n int) ([]SessionSummary, error) {
	if n <= 0 {
		return nil, nil
	}
	all, err := readSummaries(path)
	if err != nil {
		return nil, err
	}
	if len(all) == 0 {
		return nil, nil
	}
	if len(all) > n {
		all = all[len(all)-n:]
	}
	return all, nil
}
```

- [ ] **Step 4: Run the tests to verify they pass**

Run: `go test ./internal/store/ -v`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add internal/store/audit.go internal/store/audit_test.go
git commit -m "Add RecentSessions reader over the audit chain

Exposes the last n session summaries (oldest-first) for the reviewer to
read as recent-history context. Missing/empty chain or n<=0 yields nil.

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

---

## Task 3: Controller reflection wiring

**Files:**
- Modify: `internal/store/store.go` (snapshot fields)
- Modify: `internal/session/session.go`
- Test: `internal/session/session_test.go`

This is the integration task: the reviewer is fetched on entering Review, the result is cached and rides the snapshot, the `carryForward` composes into the coach's grounding, and the projection exposes a recap (Review) and carry-forward (Planning). The fetch's generation guard is **generation-only** (no runtime-state gate) because the `carryForward` must still apply if the user clicks **End** before the reviewer returns — only a superseded *review* should be discarded.

- [ ] **Step 1: Add the snapshot fields**

In `internal/store/store.go`, extend the `Snapshot` struct (add the three fields after `AllowedWindowClasses`):

```go
	AllowedWindowClasses []string `json:"allowed_window_classes,omitempty"`

	ReflectionStatus string `json:"reflection_status,omitempty"`
	ReflectionRecap  string `json:"reflection_recap,omitempty"`
	CarryForward     string `json:"carry_forward,omitempty"`
}
```

Run: `go build ./internal/store/`
Expected: builds clean.

- [ ] **Step 2: Write the failing controller tests**

Append to `internal/session/session_test.go`. First add `"strings"` to the import block (it is not yet imported), placing it after `"sync/atomic"`:

```go
	"strings"
	"sync"
	"sync/atomic"
```

Then append the fakes, helpers, and tests:

```go
type fakeReviewer struct {
	refl  ai.Reflection
	err   error
	gate  chan struct{} // if non-nil, Review blocks until it receives
	calls int32
}

func (f *fakeReviewer) Review(ctx context.Context, finished, history string) (ai.Reflection, error) {
	atomic.AddInt32(&f.calls, 1)
	if f.gate != nil {
		<-f.gate
	}
	return f.refl, f.err
}

// waitReflectionStatus polls until the reflection view reaches want, or fails after 2s.
func waitReflectionStatus(t *testing.T, c *Controller, want string) State {
	t.Helper()
	deadline := time.Now().Add(2 * time.Second)
	for time.Now().Before(deadline) {
		st := c.State()
		if st.Reflection != nil && st.Reflection.Status == want {
			return st
		}
		time.Sleep(5 * time.Millisecond)
	}
	t.Fatalf("reflection status never reached %q (last: %+v)", want, c.State().Reflection)
	return State{}
}

func driveToReview(t *testing.T, c *Controller) {
	t.Helper()
	if err := c.EnterPlanning(); err != nil {
		t.Fatalf("planning: %v", err)
	}
	if err := c.StartManualCommitment("write plan", "plan done", 25*time.Minute, nil); err != nil {
		t.Fatalf("start: %v", err)
	}
	if err := c.Complete(); err != nil {
		t.Fatalf("complete: %v", err)
	}
}

func TestReflectionFetchedOnReview(t *testing.T) {
	c, _ := newTestController(t)
	c.SetReviewer(&fakeReviewer{refl: ai.Reflection{Recap: "held focus", CarryForward: "start in the editor"}})
	driveToReview(t, c)
	st := waitReflectionStatus(t, c, "ready")
	if st.Reflection.Recap != "held focus" {
		t.Fatalf("recap not projected on Review: %+v", st.Reflection)
	}
}

func TestNoReviewerYieldsIdleReflection(t *testing.T) {
	c, _ := newTestController(t)
	driveToReview(t, c)
	st := c.State()
	if st.Reflection == nil || st.Reflection.Status != "idle" {
		t.Fatalf("nil reviewer should yield idle reflection, got %+v", st.Reflection)
	}
	if err := c.End(); err != nil {
		t.Fatalf("End must still work with no reviewer: %v", err)
	}
}

func TestCarryForwardGroundsNextCoach(t *testing.T) {
	c, _ := newTestController(t)
	c.SetReviewer(&fakeReviewer{refl: ai.Reflection{Recap: "ok", CarryForward: "begin with the hardest test"}})
	fc := &fakeCoach{prop: ai.Proposal{NextAction: "a", SuccessCondition: "b", TimeboxSecs: 1200}}
	c.SetCoach(fc)
	driveToReview(t, c)
	waitReflectionStatus(t, c, "ready")
	if err := c.End(); err != nil {
		t.Fatalf("end: %v", err)
	}
	if err := c.EnterPlanning(); err != nil {
		t.Fatalf("planning: %v", err)
	}
	if err := c.RequestCoach("ship it"); err != nil {
		t.Fatalf("request coach: %v", err)
	}
	deadline := time.Now().Add(2 * time.Second)
	for time.Now().Before(deadline) && fc.grounding() == "" {
		time.Sleep(5 * time.Millisecond)
	}
	if g := fc.grounding(); !strings.Contains(g, "begin with the hardest test") {
		t.Fatalf("carry-forward not threaded into coach grounding: %q", g)
	}
}

func TestReflectionStaleResultDiscarded(t *testing.T) {
	c, _ := newTestController(t)
	slow := &fakeReviewer{refl: ai.Reflection{Recap: "OLD", CarryForward: "old"}, gate: make(chan struct{})}
	c.SetReviewer(slow)
	driveToReview(t, c) // gen1 pending, goroutine blocks on gate
	waitReflectionStatus(t, c, "pending")

	_ = c.End() // Review -> Locked; gen1 still blocked
	fast := &fakeReviewer{refl: ai.Reflection{Recap: "NEW", CarryForward: "new"}}
	c.SetReviewer(fast)
	driveToReview(t, c) // gen2 -> ready NEW
	st := waitReflectionStatus(t, c, "ready")
	if st.Reflection.Recap != "NEW" {
		t.Fatalf("expected NEW, got %+v", st.Reflection)
	}

	close(slow.gate) // release gen1; it must be discarded
	time.Sleep(50 * time.Millisecond)
	if got := c.State().Reflection.Recap; got != "NEW" {
		t.Fatalf("stale gen1 overwrote reflection: %q", got)
	}
}

func TestCarryForwardSurvivesRestart(t *testing.T) {
	path := filepath.Join(t.TempDir(), "state.json")
	first, err := New(path)
	if err != nil {
		t.Fatalf("new: %v", err)
	}
	first.SetReviewer(&fakeReviewer{refl: ai.Reflection{Recap: "ok", CarryForward: "lead with tests"}})
	if err := first.EnterPlanning(); err != nil {
		t.Fatalf("planning: %v", err)
	}
	if err := first.StartManualCommitment("a", "b", 25*time.Minute, nil); err != nil {
		t.Fatalf("start: %v", err)
	}
	if err := first.Complete(); err != nil {
		t.Fatalf("complete: %v", err)
	}
	waitReflectionStatus(t, first, "ready")
	if err := first.End(); err != nil {
		t.Fatalf("end: %v", err)
	}

	second, err := New(path)
	if err != nil {
		t.Fatalf("reopen: %v", err)
	}
	if err := second.EnterPlanning(); err != nil {
		t.Fatalf("planning: %v", err)
	}
	st := second.State()
	if st.Reflection == nil || st.Reflection.CarryForward != "lead with tests" {
		t.Fatalf("carry-forward not restored onto planning: %+v", st.Reflection)
	}
}
```

- [ ] **Step 3: Run the tests to verify they fail**

Run: `go test ./internal/session/ -run 'Reflection|CarryForward|Reviewer' -v`
Expected: build failure — `undefined: (*Controller).SetReviewer`, `st.Reflection` undefined.

- [ ] **Step 4: Add reflection constants**

In `internal/session/session.go`, add `"fmt"` to the import block (after `"errors"`):

```go
	"context"
	"errors"
	"fmt"
	"log"
```

Then add the constants after the `knowledge` const block (after line ~59):

```go
const reflectionTimeout = 30 * time.Second

const reflectionHistoryN = 5

const (
	reflectionIdle    = "idle"
	reflectionPending = "pending"
	reflectionReady   = "ready"
	reflectionAbsent  = "absent"
)
```

- [ ] **Step 5: Add controller fields**

In the `Controller` struct, add a reflection block after the `knowledge` block (after `knowledgeGen int`):

```go
	reviewer         ai.Reviewer
	reflectionStatus string
	reflectionRecap  string
	carryForward     string // latest-wins takeaway; grounds the next coach
	reflectionGen    int
```

- [ ] **Step 6: Add the `ReflectionView` and the `State` field**

After the `KnowledgeView` type, add:

```go
// ReflectionView projects the reviewer's output. Recap is shown on Review;
// CarryForward is shown on the next Planning screen. Unlike the knowledge
// profile, these short lines exist to be displayed, so they cross the wire.
type ReflectionView struct {
	Status       string `json:"status,omitempty"`
	Recap        string `json:"recap,omitempty"`
	CarryForward string `json:"carry_forward,omitempty"`
}
```

In the `State` struct, add the field after `Knowledge`:

```go
	Knowledge    *KnowledgeView      `json:"knowledge,omitempty"`
	Reflection   *ReflectionView     `json:"reflection,omitempty"`
	Drift        *DriftView          `json:"drift,omitempty"`
```

- [ ] **Step 7: Restore reflection fields in `New`**

In `New`, extend the `Controller` literal (after `outcomePending: s.OutcomePending,`):

```go
		clock:          time.Now,
		outcomePending: s.OutcomePending,
		reflectionStatus: s.ReflectionStatus,
		reflectionRecap:  s.ReflectionRecap,
		carryForward:     s.CarryForward,
	}
```

- [ ] **Step 8: Persist reflection fields in `persistLocked`**

In `persistLocked`, after `snap.AllowedWindowClasses = c.allowedClasses`:

```go
	snap.AllowedWindowClasses = c.allowedClasses
	snap.ReflectionStatus = c.reflectionStatus
	snap.ReflectionRecap = c.reflectionRecap
	snap.CarryForward = c.carryForward
	return store.Save(c.snapshotPath, snap)
```

- [ ] **Step 9: Project reflection in `stateLocked`**

Inside `stateLocked`, in the `if c.runtimeState == domain.RuntimePlanning {` block, after the knowledge projection (`st.Knowledge = ...` closing brace), add:

```go
		if c.carryForward != "" {
			st.Reflection = &ReflectionView{CarryForward: c.carryForward}
		}
	}
```

Then, after that planning block closes (before `if c.runtimeState == domain.RuntimeActive {`), add a Review block:

```go
	if c.runtimeState == domain.RuntimeReview {
		rstatus := c.reflectionStatus
		if rstatus == "" {
			rstatus = reflectionIdle
		}
		st.Reflection = &ReflectionView{Status: rstatus, Recap: c.reflectionRecap}
	}
```

- [ ] **Step 10: Add `SetReviewer`, `startReflectionFetchLocked`, and the input builders**

After the `SetKnowledge`/`SetKnowledgePath`/`startKnowledgeFetchLocked` group (after `startKnowledgeFetchLocked` closes, ~line 539), add:

```go
// SetReviewer injects the AI reviewer. A nil reviewer keeps reflection idle and
// leaves the coach ungrounded by any carry-forward.
func (c *Controller) SetReviewer(r ai.Reviewer) {
	c.mu.Lock()
	c.reviewer = r
	c.mu.Unlock()
}

// startReflectionFetchLocked kicks off an asynchronous reflection when a
// reviewer is set, on entering Review. Unlike the tasks/knowledge fetches, the
// completion guard is generation-only (not state-gated): the carry-forward must
// still apply if the user clicks End before the reviewer returns. A superseded
// review (a later session's fetch) bumps the generation and discards this one.
// The recap and carry-forward are cleared up front so a failed/slow reviewer
// never leaves stale data from the previous session. Caller holds mu.
func (c *Controller) startReflectionFetchLocked() {
	c.reflectionRecap = ""
	c.carryForward = ""
	if c.reviewer == nil {
		c.reflectionStatus = reflectionIdle
		return
	}
	c.reflectionGen++
	gen := c.reflectionGen
	c.reflectionStatus = reflectionPending
	reviewer := c.reviewer
	finished := c.buildReflectionFinishedLocked()
	history := buildReflectionHistory(c.auditPath) // small, bounded file read
	go func() {
		ctx, cancel := context.WithTimeout(context.Background(), reflectionTimeout)
		defer cancel()
		refl, err := reviewer.Review(ctx, finished, history)

		c.mu.Lock()
		if gen != c.reflectionGen {
			c.mu.Unlock()
			return // superseded review: discard
		}
		if err != nil || strings.TrimSpace(refl.Recap) == "" {
			c.reflectionStatus = reflectionAbsent
			c.reflectionRecap = ""
			c.carryForward = ""
		} else {
			c.reflectionStatus = reflectionReady
			c.reflectionRecap = refl.Recap
			c.carryForward = refl.CarryForward
		}
		_ = c.persistLocked()
		c.mu.Unlock()
		c.notify()
	}()
}

// buildReflectionFinishedLocked renders the just-finished session as a compact
// block for the reviewer. Caller holds mu; c.stats/c.commitment are still set
// (End clears them, but enterReview runs before End). Reuses bucketViews for the
// per-window totals, already sorted desc by seconds.
func (c *Controller) buildReflectionFinishedLocked() string {
	var na, sc string
	if c.commitment != nil {
		na, sc = c.commitment.NextAction, c.commitment.SuccessCondition
	}
	outcome := c.outcomePending
	if outcome == "" {
		outcome = "completed"
	}
	var b strings.Builder
	fmt.Fprintf(&b, "Next action: %s\n", na)
	fmt.Fprintf(&b, "Success condition: %s\n", sc)
	fmt.Fprintf(&b, "Outcome: %s\n", outcome)
	if c.stats != nil {
		fmt.Fprintf(&b, "Context switches: %d\n", c.stats.SwitchCount)
		for i, bv := range bucketViews(c.stats.Buckets) {
			if i >= 3 {
				break
			}
			fmt.Fprintf(&b, "- %s · %s: %dm\n", bv.Class, bv.Title, bv.Seconds/60)
		}
	}
	return strings.TrimRight(b.String(), "\n")
}

// buildReflectionHistory renders the last few prior sessions as compact lines.
// The just-finished session is not yet in the chain (End appends it), so it is
// not double-counted. Returns "" when there is no usable history.
func buildReflectionHistory(auditPath string) string {
	sums, err := store.RecentSessions(auditPath, reflectionHistoryN)
	if err != nil || len(sums) == 0 {
		return ""
	}
	var b strings.Builder
	for _, s := range sums {
		top := ""
		if len(s.Buckets) > 0 {
			top = fmt.Sprintf(", top %s %dm", s.Buckets[0].Class, s.Buckets[0].Seconds/60)
		}
		fmt.Fprintf(&b, "- %s: %s (%d switches%s)\n", s.Outcome, s.NextAction, s.SwitchCount, top)
	}
	return strings.TrimRight(b.String(), "\n")
}
```

- [ ] **Step 11: Fire the fetch on entering Review**

In `enterReview`, insert the fetch after `c.outcomePending = outcome` and before the final `return c.persistLocked()`:

```go
	c.runtimeState = next
	c.outcomePending = outcome
	c.startReflectionFetchLocked()
	return c.persistLocked()
```

- [ ] **Step 12: Compose the carry-forward into the coach grounding**

Add a helper near `RequestCoach`:

```go
// composedGroundingLocked combines the standing profile (knowledge port) with
// the latest carry-forward takeaway into the single free-form grounding string
// the coach already accepts. Caller holds mu.
func (c *Controller) composedGroundingLocked() string {
	g := c.knowledgeText
	if c.carryForward != "" {
		if g != "" {
			g += "\n\n"
		}
		g += "Last session's takeaway: " + c.carryForward
	}
	return g
}
```

Then in `RequestCoach`, replace the line `grounding := c.knowledgeText` with:

```go
	grounding := c.composedGroundingLocked()
```

- [ ] **Step 13: Run the tests to verify they pass**

Run: `go test ./internal/session/ -run 'Reflection|CarryForward|Reviewer' -v`
Expected: PASS (5 new tests).

- [ ] **Step 14: Run the full session + store + ai suites with the race detector**

Run: `go test -race ./internal/session/ ./internal/store/ ./internal/ai/`
Expected: PASS. (`TestCoachReceivesCachedGrounding` still passes: with no reviewer set, `carryForward` is "" and the composed grounding equals the profile text exactly.)

- [ ] **Step 15: Commit**

```bash
git add internal/store/store.go internal/session/session.go internal/session/session_test.go
git commit -m "Reflect on entering Review and ground the next coach

The controller fetches a reflection asynchronously on enterReview
(generation-guarded, non-blocking, graceful) and caches a one-line
recap plus a latest-wins carry-forward. The recap projects onto Review,
the carry-forward onto the next Planning, and both ride the snapshot.
RequestCoach composes the carry-forward into the coach's existing
free-form grounding string, so ai.Coach is unchanged.

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

---

## Task 4: Daemon wiring + web payload test

**Files:**
- Modify: `cmd/antidriftd/main.go`
- Test: `internal/web/web_test.go`

- [ ] **Step 1: Write the failing web test**

Append to `internal/web/web_test.go`:

```go
type stubReviewer struct {
	refl ai.Reflection
}

func (s stubReviewer) Review(ctx context.Context, finished, history string) (ai.Reflection, error) {
	return s.refl, nil
}

func TestReflectionFlowsToReviewThenPlanning(t *testing.T) {
	s := newTestServer(t)
	s.ctrl.SetReviewer(stubReviewer{refl: ai.Reflection{Recap: "held focus well", CarryForward: "start in the editor"}})
	r := s.Router()
	_ = post(t, r, "/planning", "")
	body := `{"next_action":"a","success_condition":"b","timebox_secs":1500}`
	if w := post(t, r, "/commitment", body); w.Code != http.StatusOK {
		t.Fatalf("/commitment code %d body %s", w.Code, w.Body.String())
	}
	if w := post(t, r, "/complete", ""); w.Code != http.StatusOK {
		t.Fatalf("/complete code %d", w.Code)
	}
	deadline := time.Now().Add(2 * time.Second)
	for time.Now().Before(deadline) {
		if rv := s.ctrl.State().Reflection; rv != nil && rv.Status == "ready" {
			break
		}
		time.Sleep(5 * time.Millisecond)
	}
	js := s.stateJSON()
	if !strings.Contains(js, `"recap":"held focus well"`) {
		t.Fatalf("review payload missing recap: %s", js)
	}

	// End -> Locked -> Planning: the carry-forward should surface on planning.
	if w := post(t, r, "/end", ""); w.Code != http.StatusOK {
		t.Fatalf("/end code %d", w.Code)
	}
	if w := post(t, r, "/planning", ""); w.Code != http.StatusOK {
		t.Fatalf("/planning code %d", w.Code)
	}
	js2 := s.stateJSON()
	if !strings.Contains(js2, `"carry_forward":"start in the editor"`) {
		t.Fatalf("planning payload missing carry-forward: %s", js2)
	}
}
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `go test ./internal/web/ -run Reflection -v`
Expected: build failure — `s.ctrl.SetReviewer` undefined is already resolved by Task 3, so the failure here is the missing daemon wiring is **not** what this tests; the test should actually compile and PASS already (the controller wiring from Task 3 is enough). If it PASSES, that is expected — proceed to Step 3 to add the daemon wiring (which the test does not exercise). If it FAILS to compile, re-check Task 3 was applied.

> Rationale: the web payload is produced by the controller, which Task 3 already wired. This test guards the wire format. The daemon change in Step 3 is the production wiring (`main.go`) that no test exercises, mirroring how the M6 tasks/knowledge adapters are wired.

- [ ] **Step 3: Wire the reviewer in `main.go`**

In `cmd/antidriftd/main.go`, in the AI block, add `ctrl.SetReviewer(svc)` alongside the other roles and update the log line:

```go
		svc := ai.NewService(backend)
		ctrl.SetCoach(svc)
		ctrl.SetDriftJudge(svc)
		ctrl.SetNudge(svc)
		ctrl.SetReviewer(svc)
		log.Printf("ai: %s backend (coach + drift judge + nudge + reviewer)", backend.Name())
```

- [ ] **Step 4: Run the test + build to verify**

Run: `go test ./internal/web/ -run Reflection -v && go build ./...`
Expected: test PASS; build clean.

- [ ] **Step 5: Commit**

```bash
git add cmd/antidriftd/main.go internal/web/web_test.go
git commit -m "Wire the reviewer and assert reflection on the wire

main injects the AI service as the reviewer alongside the other roles.
A web test drives a session to Review and asserts the recap rides the
state payload, then to the next Planning and asserts the carry-forward
does too.

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

---

## Task 5: Planning + Review UI

**Files:**
- Modify: `internal/web/static/app.js`
- Modify: `internal/web/static/app.css`
- Modify: `README.md`

No JS test harness exists in this repo (consistent with M2–M6); this task is verified by `go build`/`go vet` and a human visual check. Keep the changes small and presentational.

- [ ] **Step 1: Add the two render helpers**

In `internal/web/static/app.js`, after `updatePlanningKnowledge` (ends ~line 180), add:

```js
// reflectionBlock renders the reviewer's recap on the Review screen. idle/nil or
// an empty recap renders nothing; pending shows a quiet line; ready shows the
// one-line recap.
function reflectionBlock(refl) {
  if (!refl) return '';
  if (refl.status === 'pending') return `<div class="band"><div class="reflectline meta">reflecting…</div></div>`;
  if (refl.status === 'ready' && refl.recap) {
    return `<div class="band"><div class="reflectline">${refl.recap}</div></div>`;
  }
  return '';
}

// updatePlanningReflection renders last session's carry-forward takeaway as a
// quiet one-liner on the planning screen. Nothing renders without one.
function updatePlanningReflection(refl) {
  const el = document.getElementById('reflectBand');
  if (!el) return;
  if (!refl || !refl.carry_forward) { el.innerHTML = ''; return; }
  el.innerHTML = `<span class="reflectline meta">Last time: ${refl.carry_forward}</span>`;
}
```

- [ ] **Step 2: Call the planning helper in both planning render paths**

In `render`, the incremental planning branch currently reads:

```js
  if (rs === 'planning' && renderedState === 'planning') {
    updatePlanningCoach(state.coach);
    updatePlanningTasks(state.tasks);
    updatePlanningKnowledge(state.knowledge);
    return;
  }
```

Add the reflection call:

```js
  if (rs === 'planning' && renderedState === 'planning') {
    updatePlanningCoach(state.coach);
    updatePlanningTasks(state.tasks);
    updatePlanningKnowledge(state.knowledge);
    updatePlanningReflection(state.reflection);
    return;
  }
```

In the full planning render (the `} else if (rs === 'planning') {` block), add the `reflectBand` div after `knowBand`:

```js
      <div class="band" id="tasksBand"></div>
      <div class="band" id="knowBand"></div>
      <div class="band" id="reflectBand"></div>
```

and add the call alongside the other planning updaters at the end of that block:

```js
    updatePlanningCoach(state.coach);
    updatePlanningTasks(state.tasks);
    updatePlanningKnowledge(state.knowledge);
    updatePlanningReflection(state.reflection);
```

- [ ] **Step 3: Render the recap on the Review screen**

In the `} else if (rs === 'review') {` block, insert `reflectionBlock` before `reviewSummary`:

```js
      ${reflectionBlock(state.reflection)}
      ${reviewSummary(state.evidence)}
```

- [ ] **Step 4: Add the styling line**

In `internal/web/static/app.css`, after the `.knowline { opacity: 0.85; }` line, add:

```css
.reflectline { opacity: 0.85; }
```

- [ ] **Step 5: Update the README Status section**

In `README.md`, add a new paragraph at the top of the `## Status` section (above the M6 paragraph):

```markdown
M7 (reflection): when a session ends, a fourth AI role — the reviewer —
reflects on it, read against your recent sessions, and produces two short
lines: a recap shown on the Review screen, and a carry-forward takeaway that
grounds the coach the next time you plan. It runs once asynchronously on
entering Review, never blocks the End button, and degrades gracefully — with
no backend (or a slow/failed call) Review and Planning behave exactly as
before. The carry-forward is snapshot-persisted (latest-wins) and composes
into the coach's grounding; the reflection lines are short and cross the wire
by design, while the knowledge profile still does not.
```

- [ ] **Step 6: Verify build and vet**

Run: `go build ./... && go vet ./... && go test ./...`
Expected: all PASS.

- [ ] **Step 7: Commit**

```bash
git add internal/web/static/app.js internal/web/static/app.css README.md
git commit -m "Show the recap on Review and the carry-forward on Planning

The Review screen renders the reviewer's one-line recap (quiet pending
line, then the recap); the Planning screen renders last session's
carry-forward as a 'Last time: …' one-liner, mirroring the knowledge
indicator. Updates the README Status section for M7.

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

---

## Final Verification

After all tasks, confirm the milestone holds end-to-end:

- [ ] `go build ./...` — clean.
- [ ] `go vet ./...` — clean.
- [ ] `go test -race ./...` — all packages PASS.
- [ ] **Spec invariants:**
  - `ai.Coach`'s signature is unchanged (grep: `func.*Coach(ctx context.Context, intent, grounding string)` still the only Coach signature).
  - No new file or format under `~/.antidrift` beyond snapshot fields (grep `audit.go` for no new write paths; `RecentSessions` is read-only).
  - The reflection recap/carry-forward appear in `State` JSON; the knowledge profile text still does not (`TestPlanningStatePayloadCarriesKnowledge` still passes).
  - End is never blocked on the reviewer (`TestNoReviewerYieldsIdleReflection` and the stale-discard test cover the fast-End path).

---

## Self-Review Notes

- **Spec coverage:** new role (Task 1) ✓; recent-history input via `RecentSessions` (Task 2) ✓; fetch-on-Review + generation guard + graceful + non-blocking + snapshot persistence + grounding composition + projection (Task 3) ✓; daemon wiring + wire-format (Task 4) ✓; Review recap + Planning carry-forward UI + README (Task 5) ✓; "out of scope" items (no reflections.jsonl, no Coach signature change, no session.go refactor) are respected.
- **Type consistency:** `Reflection{Recap, CarryForward}`, `ReflectionView{Status, Recap, CarryForward}`, `Snapshot.{ReflectionStatus, ReflectionRecap, CarryForward}`, and controller fields `reflectionStatus/reflectionRecap/carryForward/reflectionGen/reviewer` are used identically across tasks. JSON keys `recap`/`carry_forward`/`status` match between the view tags and the JS/web assertions.
- **Generation guard difference:** documented in Task 3 Step 10 — generation-only (not state-gated) so the carry-forward applies even after a fast End, unlike tasks/knowledge which gate on `RuntimePlanning`.