feat: Agent Improvement Engine (insights, improve, evolve)

.entire/settings.json

@@ -6,6 +6,9 @@
     "checkpoint_remote": {
       "provider": "github",
       "repo": "entireio/cli-checkpoints"
+    },
+    "summarize": {
+      "enabled": true
     }
   }
 }

.superset/config.json

@@ -0,0 +1,5 @@
+{
+  "setup": [],
+  "teardown": [],
+  "run": []
+}

cmd/entire/cli/agent/capabilities.go

@@ -27,7 +27,7 @@ type DeclaredCaps struct {
 
 // AsHookSupport returns the agent as HookSupport if it both implements the
 // interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsHookSupport(ag Agent) (HookSupport, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsHookSupport(ag Agent) (HookSupport, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -43,7 +43,7 @@ func AsHookSupport(ag Agent) (HookSupport, bool) { //nolint:ireturn // type-asse
 
 // AsTranscriptAnalyzer returns the agent as TranscriptAnalyzer if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsTranscriptAnalyzer(ag Agent) (TranscriptAnalyzer, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsTranscriptAnalyzer(ag Agent) (TranscriptAnalyzer, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -59,7 +59,7 @@ func AsTranscriptAnalyzer(ag Agent) (TranscriptAnalyzer, bool) { //nolint:iretur
 
 // AsTranscriptPreparer returns the agent as TranscriptPreparer if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsTranscriptPreparer(ag Agent) (TranscriptPreparer, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsTranscriptPreparer(ag Agent) (TranscriptPreparer, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -75,7 +75,7 @@ func AsTranscriptPreparer(ag Agent) (TranscriptPreparer, bool) { //nolint:iretur
 
 // AsTokenCalculator returns the agent as TokenCalculator if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsTokenCalculator(ag Agent) (TokenCalculator, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsTokenCalculator(ag Agent) (TokenCalculator, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -91,7 +91,7 @@ func AsTokenCalculator(ag Agent) (TokenCalculator, bool) { //nolint:ireturn // t
 
 // AsTextGenerator returns the agent as TextGenerator if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsTextGenerator(ag Agent) (TextGenerator, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsTextGenerator(ag Agent) (TextGenerator, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -107,7 +107,7 @@ func AsTextGenerator(ag Agent) (TextGenerator, bool) { //nolint:ireturn // type-
 
 // AsHookResponseWriter returns the agent as HookResponseWriter if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsHookResponseWriter(ag Agent) (HookResponseWriter, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsHookResponseWriter(ag Agent) (HookResponseWriter, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -126,7 +126,7 @@ func AsHookResponseWriter(ag Agent) (HookResponseWriter, bool) { //nolint:iretur
 // ExtractPrompts is conceptually part of transcript analysis, so it shares the same
 // capability gate — this prevents calling extract-prompts on external agent binaries
 // that never declared transcript_analyzer support.
-func AsPromptExtractor(ag Agent) (PromptExtractor, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsPromptExtractor(ag Agent) (PromptExtractor, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}
@@ -142,7 +142,7 @@ func AsPromptExtractor(ag Agent) (PromptExtractor, bool) { //nolint:ireturn // t
 
 // AsSubagentAwareExtractor returns the agent as SubagentAwareExtractor if it both
 // implements the interface and (for CapabilityDeclarer agents) has declared the capability.
-func AsSubagentAwareExtractor(ag Agent) (SubagentAwareExtractor, bool) { //nolint:ireturn // type-assertion helper must return interface
+func AsSubagentAwareExtractor(ag Agent) (SubagentAwareExtractor, bool) { //nolint:ireturn // type-assertion helper
 	if ag == nil {
 		return nil, false
 	}

cmd/entire/cli/checkpoint/checkpoint.go

@@ -232,6 +232,12 @@ type WriteCommittedOptions struct {
 	// AuthorEmail is the email to use for commits
 	AuthorEmail string
 
+	// OwnerName and OwnerEmail identify who owned the session when it started.
+	// Unlike AuthorName/AuthorEmail, these are durable session-attribution fields,
+	// not metadata-branch commit authorship.
+	OwnerName  string
+	OwnerEmail string
+
 	// MetadataDir is a directory containing additional metadata files to copy
 	// If set, all files in this directory will be copied to the checkpoint path
 	// This is useful for copying task metadata files, subagent transcripts, etc.
@@ -374,6 +380,10 @@ type CommittedMetadata struct {
 	// Model is the LLM model used during the session (e.g., "claude-sonnet-4-20250514")
 	Model string `json:"model,omitempty"`
 
+	// OwnerName and OwnerEmail identify who owned the session when it started.
+	OwnerName  string `json:"owner_name,omitempty"`
+	OwnerEmail string `json:"owner_email,omitempty"`
+
 	// TurnID correlates checkpoints from the same agent turn.
 	// When a turn's work spans multiple commits, each gets its own checkpoint
 	// but they share the same TurnID for future aggregation/deduplication.

cmd/entire/cli/checkpoint/checkpoint_test.go

@@ -219,6 +219,61 @@ func TestWriteCommitted_AgentField(t *testing.T) {
 	}
 }
 
+func TestWriteCommitted_OwnerFieldsPersisted(t *testing.T) {
+	tempDir := t.TempDir()
+
+	repo, err := git.PlainInit(tempDir, false)
+	require.NoError(t, err)
+
+	worktree, err := repo.Worktree()
+	require.NoError(t, err)
+
+	readmeFile := filepath.Join(tempDir, "README.md")
+	require.NoError(t, os.WriteFile(readmeFile, []byte("# Test"), 0o644))
+	_, err = worktree.Add("README.md")
+	require.NoError(t, err)
+	_, err = worktree.Commit("Initial commit", &git.CommitOptions{
+		Author: &object.Signature{Name: "Test", Email: "test@test.com"},
+	})
+	require.NoError(t, err)
+
+	store := NewGitStore(repo)
+	checkpointID := id.MustCheckpointID("b1b2c3d4e5f6")
+
+	err = store.WriteCommitted(context.Background(), WriteCommittedOptions{
+		CheckpointID: checkpointID,
+		SessionID:    "test-session-owner-meta",
+		Strategy:     "manual-commit",
+		Transcript:   []byte("test transcript content"),
+		AuthorName:   "Condense Author",
+		AuthorEmail:  "condense@example.com",
+		OwnerName:    "Session Owner",
+		OwnerEmail:   "owner@example.com",
+	})
+	require.NoError(t, err)
+
+	ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
+	require.NoError(t, err)
+	commit, err := repo.CommitObject(ref.Hash())
+	require.NoError(t, err)
+	tree, err := commit.Tree()
+	require.NoError(t, err)
+
+	checkpointTree, err := tree.Tree(checkpointID.Path())
+	require.NoError(t, err)
+	sessionTree, err := checkpointTree.Tree("0")
+	require.NoError(t, err)
+	sessionMetadataFile, err := sessionTree.File(paths.MetadataFileName)
+	require.NoError(t, err)
+	sessionContent, err := sessionMetadataFile.Contents()
+	require.NoError(t, err)
+
+	var sessionMetadata CommittedMetadata
+	require.NoError(t, json.Unmarshal([]byte(sessionContent), &sessionMetadata))
+	require.Equal(t, "Session Owner", sessionMetadata.OwnerName)
+	require.Equal(t, "owner@example.com", sessionMetadata.OwnerEmail)
+}
+
 // readLatestSessionMetadata reads the session-specific metadata from the latest session subdirectory.
 // This is where session-specific fields like Summary are stored.
 func readLatestSessionMetadata(t *testing.T, repo *git.Repository, checkpointID id.CheckpointID) CommittedMetadata {

cmd/entire/cli/checkpoint/committed.go

@@ -374,6 +374,8 @@ func (s *GitStore) writeSessionToSubdirectory(ctx context.Context, opts WriteCom
 		FilesTouched:                opts.FilesTouched,
 		Agent:                       opts.Agent,
 		Model:                       opts.Model,
+		OwnerName:                   opts.OwnerName,
+		OwnerEmail:                  opts.OwnerEmail,
 		TurnID:                      opts.TurnID,
 		IsTask:                      opts.IsTask,
 		ToolUseID:                   opts.ToolUseID,

cmd/entire/cli/checkpoint/v2_committed.go

@@ -321,6 +321,8 @@ func (s *V2GitStore) writeMainSessionToSubdirectory(opts WriteCommittedOptions,
 		FilesTouched:                opts.FilesTouched,
 		Agent:                       opts.Agent,
 		Model:                       opts.Model,
+		OwnerName:                   opts.OwnerName,
+		OwnerEmail:                  opts.OwnerEmail,
 		TurnID:                      opts.TurnID,
 		IsTask:                      opts.IsTask,
 		ToolUseID:                   opts.ToolUseID,

cmd/entire/cli/evolve/evolve.go

@@ -0,0 +1,28 @@
+// Package evolve implements the evolution loop that tracks sessions since the
+// last improvement run and triggers suggestions after a configurable threshold.
+package evolve
+
+import "time"
+
+// State tracks the evolution loop's progress.
+// Stored in SQLite and mirrored to insights/evolution.json on the checkpoint branch.
+type State struct {
+	LastRunAt            time.Time `json:"last_run_at"`
+	SessionsSinceLastRun int       `json:"sessions_since_last_run"`
+	TotalRuns            int       `json:"total_runs"`
+	SuggestionsGenerated int       `json:"suggestions_generated"`
+	SuggestionsAccepted  int       `json:"suggestions_accepted"`
+}
+
+// SuggestionRecord tracks a suggestion through its lifecycle.
+type SuggestionRecord struct {
+	ID           string     `json:"id"`
+	Title        string     `json:"title"`
+	FileType     string     `json:"file_type"`
+	Priority     string     `json:"priority"`
+	Status       string     `json:"status"` // "pending", "accepted", "rejected"
+	CreatedAt    time.Time  `json:"created_at"`
+	ResolvedAt   *time.Time `json:"resolved_at,omitempty"`
+	PreAvgScore  *float64   `json:"pre_avg_score,omitempty"`
+	PostAvgScore *float64   `json:"post_avg_score,omitempty"`
+}

cmd/entire/cli/evolve/notify.go

@@ -0,0 +1,19 @@
+package evolve
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/entireio/cli/cmd/entire/cli/settings"
+)
+
+// CheckAndNotify increments the session counter and notifies the user
+// when the evolution threshold is reached. Called after session condensation.
+func CheckAndNotify(w io.Writer, config settings.EvolveSettings, state *State) {
+	IncrementSessionCount(state)
+	if !ShouldTrigger(config, *state) {
+		return
+	}
+	fmt.Fprintf(w, "\n  Tip: %d sessions since last improvement analysis.\n", state.SessionsSinceLastRun)
+	fmt.Fprintln(w, "  Run `entire improve` to get context file suggestions.")
+}

cmd/entire/cli/evolve/notify_test.go

@@ -0,0 +1,66 @@
+package evolve_test
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/entireio/cli/cmd/entire/cli/evolve"
+	"github.com/entireio/cli/cmd/entire/cli/settings"
+)
+
+func TestCheckAndNotify_ThresholdMet(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	config := settings.EvolveSettings{Enabled: true, SessionThreshold: 5}
+	state := evolve.State{SessionsSinceLastRun: 4} // will become 5 after increment
+
+	evolve.CheckAndNotify(&buf, config, &state)
+
+	if state.SessionsSinceLastRun != 5 {
+		t.Errorf("expected SessionsSinceLastRun=5, got %d", state.SessionsSinceLastRun)
+	}
+	output := buf.String()
+	if !strings.Contains(output, "entire improve") {
+		t.Errorf("expected output to mention 'entire improve', got: %q", output)
+	}
+	if !strings.Contains(output, "5") {
+		t.Errorf("expected output to mention session count 5, got: %q", output)
+	}
+}
+
+func TestCheckAndNotify_BelowThreshold(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	config := settings.EvolveSettings{Enabled: true, SessionThreshold: 5}
+	state := evolve.State{SessionsSinceLastRun: 2} // will become 3 after increment
+
+	evolve.CheckAndNotify(&buf, config, &state)
+
+	if state.SessionsSinceLastRun != 3 {
+		t.Errorf("expected SessionsSinceLastRun=3, got %d", state.SessionsSinceLastRun)
+	}
+	if buf.Len() != 0 {
+		t.Errorf("expected no output below threshold, got: %q", buf.String())
+	}
+}
+
+func TestCheckAndNotify_Disabled(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	config := settings.EvolveSettings{Enabled: false, SessionThreshold: 5}
+	state := evolve.State{SessionsSinceLastRun: 10}
+
+	evolve.CheckAndNotify(&buf, config, &state)
+
+	// Counter still increments even when disabled
+	if state.SessionsSinceLastRun != 11 {
+		t.Errorf("expected SessionsSinceLastRun=11, got %d", state.SessionsSinceLastRun)
+	}
+	if buf.Len() != 0 {
+		t.Errorf("expected no output when disabled, got: %q", buf.String())
+	}
+}

cmd/entire/cli/evolve/tracker.go

@@ -0,0 +1,78 @@
+package evolve
+
+import (
+	"fmt"
+	"time"
+)
+
+// Tracker manages the lifecycle of improvement suggestions.
+type Tracker struct {
+	Records map[string]*SuggestionRecord
+}
+
+func NewTracker() *Tracker {
+	return &Tracker{Records: make(map[string]*SuggestionRecord)}
+}
+
+func (t *Tracker) AddSuggestion(rec SuggestionRecord) {
+	t.Records[rec.ID] = &rec
+}
+
+func (t *Tracker) Get(id string) *SuggestionRecord {
+	return t.Records[id]
+}
+
+// Accept marks a suggestion as accepted and records the resolution time.
+func (t *Tracker) Accept(id string) error {
+	return t.resolve(id, "accepted")
+}
+
+// Reject marks a suggestion as rejected and records the resolution time.
+func (t *Tracker) Reject(id string) error {
+	return t.resolve(id, "rejected")
+}
+
+func (t *Tracker) resolve(id, status string) error {
+	rec, ok := t.Records[id]
+	if !ok {
+		return fmt.Errorf("suggestion %q not found", id)
+	}
+	now := time.Now()
+	rec.Status = status
+	rec.ResolvedAt = &now
+	return nil
+}
+
+// MeasureImpact sets the pre/post average scores for impact analysis.
+// Returns the updated record, or nil if the ID is not found.
+func (t *Tracker) MeasureImpact(id string, scoresBefore, scoresAfter []float64) *SuggestionRecord {
+	rec, ok := t.Records[id]
+	if !ok {
+		return nil
+	}
+	rec.PreAvgScore = avgOrNil(scoresBefore)
+	rec.PostAvgScore = avgOrNil(scoresAfter)
+	return rec
+}
+
+func (t *Tracker) Pending() []SuggestionRecord {
+	var result []SuggestionRecord
+	for _, rec := range t.Records {
+		if rec.Status == "pending" {
+			result = append(result, *rec)
+		}
+	}
+	return result
+}
+
+func avgOrNil(scores []float64) *float64 {
+	if len(scores) == 0 {
+		return nil
+	}
+	var sum float64
+	for _, s := range scores {
+		sum += s
+	}
+	avg := sum / float64(len(scores))
+	return &avg
+}