taskdetect

type Classifier interface {
	Classify(ctx context.Context, in Turn) (Proposal, bool, error)
}

type Cluster struct {
	FamilyKey string
	Family    string
	Project   string
	// Weight is confidence summed with age decay. Sessions counts DISTINCT
	// sessions, which is the part that matters: three signals in one
	// conversation is one person repeating themselves, not a pattern.
	Weight   float64
	Sessions int
	Signals  int
	// Latest is the most recent proposal, used for the offer — the newest
	// phrasing of the capability is the one to show back.
	Latest   Proposal
	Evidence []string
	LastSeen time.Time
}

type Decision struct {
	Kind     Kind
	Proposal Proposal
	// Sessions and Occasions describe the evidence behind a repeated offer.
	Sessions  int
	Occasions int
	// Why explains a decision NOT to offer, for the debug surface. Silence that
	// cannot be explained is indistinguishable from a broken detector.
	Why string
}

type Detector struct {
	Store      *Store
	Classifier Classifier
}

type Effect string

type Gap struct {
	Field    string
	Question string
	Why      string
}

type Kind string

type Offer struct {
	Headline string
	Detail   string
	Options  []Option
}

type Option struct {
	Key         string
	Label       string
	Description string
}

type Proposal struct {
	// Family is the SEMANTIC identity of the capability, normalized. It is what
	// lets three differently worded requests accumulate into one recognised
	// thing, so it names a capability rather than an instance:
	// "provider-model-catalog-maintenance", not "update-anthropic-models".
	Family string `json:"task_family"`
	// Operation and Target are the parts Family is built from, kept separately
	// because they are what a human reads when asked to confirm the grouping.
	Operation string `json:"operation"`
	Target    string `json:"target"`
	// Scope and Project bound where the capability applies.
	Scope   string `json:"scope"`
	Project string `json:"project,omitempty"`
	// Constraints are the conditions that must hold for the work to be correct
	// ("verify prices against the vendor's page"). Part of identity: the same
	// operation under materially different constraints is different work.
	Constraints []string `json:"constraints,omitempty"`

	Name         string   `json:"name"`
	Reason       string   `json:"reason"`
	Instructions string   `json:"instructions"`
	Verify       []string `json:"verify,omitempty"`

	// SuggestedEvery is a Go duration ("168h") and SuggestedCron a 5-field
	// expression; at most one is set.
	SuggestedEvery string `json:"suggested_every,omitempty"`
	SuggestedCron  string `json:"suggested_cron,omitempty"`

	Effect Effect `json:"code_changes"`
	// Confidence that the work is well-shaped enough to automate at all.
	Confidence float64 `json:"confidence"`
	// Recurrence is the causal claim about whether it will be needed again.
	// Separate from Confidence on purpose: work can be perfectly automatable and
	// still never need doing twice.
	Recurrence Recurrence `json:"recurrence"`
	// ExplicitRequest is the user actually asking for this to be automated,
	// which needs no inference at all.
	ExplicitRequest bool `json:"explicit_request,omitempty"`
	// ClarifyingQuestions are decisions the model could not make for the user —
	// usually scope or side effects. "Should major version bumps be included?"
	// is a different task depending on the answer, and guessing it silently is
	// how an autonomous job does something nobody asked for.
	ClarifyingQuestions []string `json:"clarifying_questions,omitempty"`

	// The four eligibility gates. Repetition alone is NOT enough: a password
	// reset recurs, a vague "make this better" recurs, an emotionally repetitive
	// question recurs, and none of them is a capability worth handing to an
	// unattended machine.
	Bounded        bool `json:"bounded"`
	Reproducible   bool `json:"reproducible"`
	UnattendedSafe bool `json:"unattended_safe"`
	Evaluable      bool `json:"evaluable"`
}

type Recurrence struct {
	Kind RecurrenceKind `json:"kind"`
	// Cause states WHAT makes it recur, in the model's own words. Required for
	// a prospective offer: an offer that cannot say why is a guess, and it goes
	// in the message so the user can judge the reasoning rather than the verdict.
	Cause string `json:"cause,omitempty"`
	// Confidence in the causal claim, distinct from confidence that the work is
	// well-shaped.
	Confidence float64 `json:"confidence"`
	// Value is what automating it buys — usually "notice X without you having
	// to remember to look".
	Value string `json:"value,omitempty"`
}

type RecurrenceKind string

type Signal struct {
	ID          string
	SessionID   string
	ObservedAt  time.Time
	Project     string
	Family      string
	FamilyKey   string
	Fingerprint string
	Operation   string
	Target      string
	Scope       string
	Confidence  float64
	Evidence    string
	Proposal    Proposal
}

type Store struct {
	// contains filtered or unexported fields
}

type Turn struct {
	SessionID string
	Project   string
	// Request is what the user asked for, Summary what was done.
	Request string
	Summary string
	// Changed reports whether the turn actually altered the repository — weak
	// but real evidence that the work was substantive.
	Changed bool
}