overview

Documentation

Overview

Package overview synthesizes a CANONICAL current-state overview of a project — the answer to "what is this now?" — from fresh signals (recent commits, active objectives, current claims, recent-active subsystems) rather than rebuilding it from random old docs/memories each time. The result is cached keyed by HEAD, so the overview is stable between commits and regenerated when work moves on.

This exists to fix "sounding smart while being stale": a current-state question is a SYNTHESIS task over current evidence, not a recall over old framing.

Index

• func Arch(root string) string
• type Overview
  • func Get(ctx context.Context, st store.Store, runner llm.ModelRunner, ...) (Overview, error)
  • func Load(ctx context.Context, st store.Store, root string) (Overview, bool)
  • func Synthesize(ctx context.Context, st store.Store, runner llm.ModelRunner, ...) (Overview, error)

Functions

func Arch

func Arch(root string) string

Arch renders the project's architecture/flow — by EXTRACTING existing diagrams from the repo's own docs (README, ARCH.md, …), verbatim. It never synthesizes a flow: a generated diagram would hallucinate or go stale, and the runtime topology (cli → api → providers) isn't reliably derivable from disk (it's not the import graph; an env scan false-positives on commented-out vars). So the rule is find-and-quote, not generate — present when documented, absent otherwise.

Types

type Overview

type Overview struct {
	Text        string    `json:"text"`
	HeadSHA     string    `json:"head_sha"`
	Branch      string    `json:"branch,omitempty"`
	DirtyHash   string    `json:"dirty_hash,omitempty"` // hash of `git status --porcelain`; "" = clean
	GeneratedAt time.Time `json:"generated_at"`
}

Overview is the synthesized current-state summary, cached in current_state. It records the git SNAPSHOT it was generated against (branch + HEAD + a hash of the dirty working tree). The overview is a DERIVED artifact of git truth: any change to that snapshot — a commit, a branch switch, an edit — invalidates it. Git state is the freshness boundary, never time. "verified green but not yet committed" must never survive a commit.

func Get

func Get(ctx context.Context, st store.Store, runner llm.ModelRunner, root, model string) (Overview, error)

Get returns a fresh overview: the cache if HEAD-current, else a fresh synthesis.

func Load

func Load(ctx context.Context, st store.Store, root string) (Overview, bool)

Load returns the cached overview and whether it's still fresh — fresh meaning it was generated against the CURRENT git snapshot (branch + HEAD + dirty state). A commit, branch switch, or edit since generation makes it stale.

func Synthesize

func Synthesize(ctx context.Context, st store.Store, runner llm.ModelRunner, root, model string) (Overview, error)

Synthesize gathers current-state evidence, makes one model call to produce a concise current overview, caches it keyed by the git snapshot, and returns it. Synthesize builds the overview. It is now a DETERMINISTIC cockpit briefing — rendered from facts (root README identity, the subsystem topology + each component's own doc, the parsed StackFacts, recent commits, churn-hot dirs), NOT a model summary. The model used to flatten these same facts into a prose blurb and invent component internals ("Firestore: conversation history"); rendering facts directly is crisp like `memcode stack` and can't hallucinate. runner/model are unused (kept for the cache-API signature).