Grade against a stale baseline, or say why not (#173)

The Stop hook emitted only on a regression, so a baseline that could not be
compared was indistinguishable from a clean change.

- shouldAutoPin refreshes a baseline that is blocking-incomparable, not just
  one whose tree moved. Previously an upgrade left an unusable baseline in
  place on a clean tree, and the session was never graded. Auto-pinned
  baselines only; a deliberate pin is left alone.
- The hook now emits on StatusIncomparable, naming the cause and the remedy.
  Verdict.DeclineReason reuses the table `enola check` prints from, so both
  surfaces give the same explanation.
- Reported once per cause. hookstate records the decline identity; a
  successful grade clears it, so a recurrence is reported again.
- doctor reports baseline usability from metadata, before a session rather
  than after.
- Updated the installed instruction, which said the hook stays silent unless
  something regressed.

Advisory warnings are unchanged: a stale baseline still grades.

Author: dejo1307

cmd/enola/doctor.go

@@ -8,7 +8,11 @@ import (
 	"path/filepath"
 	"time"
 
+	"github.com/enola-labs/enola/internal/diff"
+	"github.com/enola-labs/enola/internal/engine"
 	"github.com/enola-labs/enola/internal/hookstate"
+	"github.com/enola-labs/enola/pkg/bootstrap"
+	"github.com/enola-labs/enola/pkg/check"
 )
 
 // runDoctor is `enola doctor`: does the loop actually run in this repository?
@@ -61,12 +65,14 @@ func runDoctor(args []string) {
 	outDir := hookOutputDir(repoDir)
 	state := hookstate.Load(outDir)
 	installed := hooksConfigured(repoDir)
+	baselineIssue := baselineUsability(repoDir, outDir)
 
 	if *asJSON {
 		out := map[string]any{
-			"repo":             repoDir,
-			"hooks_configured": installed,
-			"state":            state,
+			"repo":              repoDir,
+			"hooks_configured":  installed,
+			"state":             state,
+			"baseline_unusable": baselineIssue,
 		}
 		enc := json.NewEncoder(os.Stdout)
 		enc.SetIndent("", "  ")
@@ -75,6 +81,20 @@ func runDoctor(args []string) {
 	}
 
 	fmt.Printf("enola doctor: %s\n\n", repoDir)
+
+	// Asked and answered BEFORE a session ends, which is the difference between this
+	// and reading the last outcome below: an unusable baseline makes the hooks decline
+	// to grade, and they decline quietly. Knowing now beats finding out afterwards.
+	fmt.Println("Baseline")
+	if baselineIssue == "" {
+		fmt.Println("  comparable — the gate can grade against it")
+	} else {
+		fmt.Printf("  NOT COMPARABLE: %s\n", baselineIssue)
+		fmt.Println("  Nothing will be graded against it until it is re-pinned:")
+		fmt.Println("      enola baseline pin")
+	}
+	fmt.Println()
+
 	fmt.Println("Session hooks")
 
 	if !installed {
@@ -137,6 +157,27 @@ func runDoctor(args []string) {
 	}
 }
 
+// baselineUsability returns why the pinned baseline could not be graded against, or
+// "" when it can. It answers from metadata alone — no files are parsed — so `doctor`
+// stays a report rather than becoming a snapshot.
+func baselineUsability(repoDir, outDir string) string {
+	base, err := bootstrap.LoadSnapshotDir(engine.ResolveBaselineDir(outDir, "pinned"))
+	if err != nil {
+		return "" // no baseline pinned; the hooks section covers that case
+	}
+	eng, cfg, err := bootstrap.NewEngine(bootstrap.Options{ConfigPath: configForRepo(repoDir)})
+	if err != nil {
+		return ""
+	}
+	cfg.Repo, cfg.Repos = repoDir, nil
+	current := eng.CurrentMeta(repoDir)
+	if current == nil {
+		return ""
+	}
+	v := check.Evaluate(&diff.SnapshotDiff{Comparability: diff.CompareMeta(base.Meta, *current)}, check.Policy{})
+	return v.DeclineReason()
+}
+
 // hooksConfigured reports whether .claude/settings.json carries an entry enola owns.
 //
 // Deliberately a shallow scan for the marker rather than a shape check: whether the

cmd/enola/hook.go

@@ -77,18 +77,44 @@ func runStopHook(ctx context.Context) {
 	// paths are the ones worth recording: a hook that never fires and a hook that fires
 	// and finds nothing are indistinguishable in a session, and only one of them is
 	// broken. See internal/hookstate and DEFECTS_FOUND.md.
-	hookstate.RecordFired(outDir, hookstate.EventStop, stopOutcome(verdict, ok))
+	declineKey := ""
+	if ok {
+		declineKey = verdict.DeclineKey()
+	}
+	// ShouldReport is asked BEFORE recording, because recording is what makes the next
+	// identical decline a repeat.
+	sayDecline := ok && declineKey != "" && hookstate.ShouldReport(outDir, hookstate.EventStop, declineKey)
+	hookstate.RecordFiredWithReason(outDir, hookstate.EventStop, stopOutcome(verdict, ok), declineKey)
+
+	var context string
+	switch {
+	case ok && verdict.Status == check.StatusRegression:
+		context = "enola graded the architectural change made in this session and found a structural " +
+			"regression. This was not necessarily intended — review it before considering the task " +
+			"finished, and either fix it or say why it is deliberate.\n\n" + verdict.Render()
 
-	if !ok || verdict.Status != check.StatusRegression {
+	case sayDecline:
+		// The gate could not grade at all, and saying nothing would be indistinguishable
+		// from grading it clean. `enola check` spends a whole exit code (3) keeping those
+		// apart so "I refuse to grade this" is never read as "your change is bad"; a hook
+		// that stays silent collapses the same distinction in the other direction, and
+		// leaves someone believing the loop is protecting them when it is not.
+		//
+		// Said once per distinct reason, not once per session — see hookstate.ShouldReport.
+		context = "enola could NOT grade the architectural change made in this session: " +
+			verdict.DeclineReason() + ".\n\n" +
+			"This is NOT a statement about your change — the comparison itself was untrustworthy, " +
+			"so no verdict was reached in either direction. Re-pin the baseline to restore grading " +
+			"(`enola baseline pin`, or the set_baseline tool), and `enola doctor` reports whether " +
+			"the hooks are grading again."
+
+	default:
 		return
 	}
 
 	var out stopHookOutput
 	out.HookSpecificOutput.HookEventName = "Stop"
-	out.HookSpecificOutput.AdditionalContext =
-		"enola graded the architectural change made in this session and found a structural " +
-			"regression. This was not necessarily intended — review it before considering the task " +
-			"finished, and either fix it or say why it is deliberate.\n\n" + verdict.Render()
+	out.HookSpecificOutput.AdditionalContext = context
 
 	encoded, err := json.Marshal(out)
 	if err != nil {
@@ -189,7 +215,7 @@ func pinBaselineSingleFlight(ctx context.Context, repoDir string) {
 	defer lock.Release()
 
 	baselineDir := engine.ResolveBaselineDir(outDir, "pinned")
-	if !shouldAutoPin(baselineDir, anchor, cfg.Output.Dir) {
+	if !shouldAutoPin(baselineDir, anchor, cfg.Output.Dir, eng.CurrentMeta(anchor)) {
 		return
 	}
 
@@ -225,14 +251,29 @@ func pinBaselineSingleFlight(ctx context.Context, repoDir string) {
 //
 // A dirty tree is never treated as current: "dirty" says the content is not identified by
 // the commit, so two dirty trees at the same commit may differ arbitrarily.
-func shouldAutoPin(baselineDir, repoDir, outputDir string) bool {
+//
+// The third rule is about usefulness rather than freshness: an auto-pinned baseline that
+// can no longer be COMPARED to a current snapshot — a different enola version, a changed
+// extractor set or ignore globs — is not a baseline at all, and refreshing it costs one
+// snapshot where leaving it costs the session's entire grading, silently. Tree movement
+// alone missed this: a session starting on a clean unchanged tree after an upgrade
+// graded against an unusable baseline and said nothing.
+//
+// Still only ever applied to baselines this hook created. A deliberate pin stays
+// untouched even when unusable — replacing it would discard the "before" of a refactor
+// that may span days, which is a worse outcome than a Stop hook that has to explain
+// itself. That case is reported instead.
+func shouldAutoPin(baselineDir, repoDir, outputDir string, current *facts.SnapshotMeta) bool {
 	base, err := bootstrap.LoadSnapshotDir(baselineDir)
 	if err != nil {
 		return true // no baseline yet — this is exactly what the hook is for
 	}
 	if _, err := os.Stat(filepath.Join(baselineDir, autoPinMarker)); err != nil {
 		return false // deliberately pinned; not ours to replace
 	}
+	if current != nil && baselineIsUnusable(base.Meta, *current) {
+		return true
+	}
 	now := engine.GitState(repoDir, outputDir)
 	if now == nil || base.Meta.Git == nil {
 		return true // cannot prove it is current, so refresh
@@ -262,6 +303,16 @@ func stopOutcome(v check.Verdict, ok bool) hookstate.Outcome {
 	}
 }
 
+// baselineIsUnusable reports whether a BLOCKING comparability warning stands between
+// these two snapshots — the same classification `enola check` uses to decline, so the
+// hook refreshes exactly what the gate would have refused to grade against. Advisory
+// warnings (a stale baseline) are deliberately not included: those still grade, and
+// re-pinning on staleness would destroy the multi-day baseline the staleness warning
+// exists to permit.
+func baselineIsUnusable(base, current facts.SnapshotMeta) bool {
+	return len(check.BlockingKinds(diff.CompareMeta(base, current))) > 0
+}
+
 // gradeQuietly runs the gate, returning ok=false for every reason a hook should stay
 // silent rather than report a problem.
 //

cmd/enola/hook_sessionstart_test.go

@@ -45,14 +45,14 @@ func TestShouldAutoPin_NeverReplacesADeliberatePin(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "baseline")
 	writeBaseline(t, dir, &facts.GitInfo{Commit: "deadbeef"}, false) // no auto marker
 
-	if shouldAutoPin(dir, t.TempDir(), ".enola") {
+	if shouldAutoPin(dir, t.TempDir(), ".enola", nil) {
 		t.Error("a deliberately pinned baseline was scheduled for replacement")
 	}
 }
 
 // TestShouldAutoPin_WithNoBaselineYet — the case the hook exists for.
 func TestShouldAutoPin_WithNoBaselineYet(t *testing.T) {
-	if !shouldAutoPin(filepath.Join(t.TempDir(), "baseline"), t.TempDir(), ".enola") {
+	if !shouldAutoPin(filepath.Join(t.TempDir(), "baseline"), t.TempDir(), ".enola", nil) {
 		t.Error("no baseline exists, so one should be pinned")
 	}
 }
@@ -67,7 +67,7 @@ func TestShouldAutoPin_SkipsWhenTreeHasNotMoved(t *testing.T) {
 
 	// GitState cannot read a non-git directory, so the decision must fail toward
 	// refreshing rather than toward silently keeping a baseline that may be wrong.
-	if !shouldAutoPin(dir, repo, ".enola") {
+	if !shouldAutoPin(dir, repo, ".enola", nil) {
 		t.Error("with git state unavailable, the baseline must be refreshed rather than trusted")
 	}
 }
@@ -79,7 +79,7 @@ func TestShouldAutoPin_DirtyTreeIsNeverCurrent(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "baseline")
 	writeBaseline(t, dir, &facts.GitInfo{Commit: "deadbeef", Dirty: true}, true)
 
-	if !shouldAutoPin(dir, t.TempDir(), ".enola") {
+	if !shouldAutoPin(dir, t.TempDir(), ".enola", nil) {
 		t.Error("a dirty baseline must never be treated as current")
 	}
 }
@@ -96,7 +96,7 @@ func TestSessionStartHook_IsSilentOnEveryFailurePath(t *testing.T) {
 			dir := filepath.Join(t.TempDir(), "baseline")
 			// shouldAutoPin is the only part reachable without spawning; exercising it
 			// with hostile inputs must not panic.
-			_ = shouldAutoPin(dir, cwd, ".enola")
+			_ = shouldAutoPin(dir, cwd, ".enola", nil)
 		})
 	}
 }