brief

Preference Maturation

This document defines the design for P4 from issue #63: preference maturation for brief --agent.

It is a design document, not an implementation document. It defines how experience may mature into onboarding preferences without changing the current brief --agent contract or allowing agents to rewrite it silently.

Core principle

Agents may propose preference changes. Humans approve them.

brief --agent remains a bounded, user-scope constitution. It is not a dump of every lesson ever learned, and it is not a task-scoped context pack. P4 exists to define how durable behavioral corrections can move toward that constitution without breaking its stability.

What P4 does and does not do

P4 does:

• define the preference-maturation lifecycle
• define how P3 maintenance primitives support that lifecycle
• define approval and hygiene rules for onboarding preferences
• define how approved changes reach brief --agent

P4 does not:

• change the brief --agent JSON shape
• add a new command in this phase
• auto-promote lessons into onboarding preferences
• make brief context responsible for onboarding behavior
• accumulate trivial corrections into unconditional-load startup context

Existing contract that P4 must preserve

From internal/cli/onboard.go, brief --agent currently loads:

• entries with category=preference and tag=onboard
• if none exist, untagged category=preference entries as a fallback
• at most default_limit entries

That remains the load-bearing contract.

P4 must preserve these rules from Context Contract:

1. brief --agent is stable and user-scoped.
2. brief context is env-scoped and must not become a second onboarding payload.
3. onboarding preferences stay bounded and intentional.

Inputs to preference maturation

Preference maturation works over memory that already exists in brief. It does not invent a parallel storage model.

Possible inputs:

• lesson entries that record concrete corrections
• decision entries that capture durable operating rules
• existing preference entries that may need consolidation, supersession, or expiry
• source-derived evidence that has first been promoted into memory via brief promote

This preserves the memory/source boundary. Crawled source material is not eligible to shape brief --agent until a human promotes it into the entries store.

P3 primitives P4 builds on

P4 depends on the primitives shipped in P3. It does not replace them.

Primitive	Role in maturation
brief stale	Surface onboarding preferences or lessons that may no longer be current.
brief duplicates	Surface repeated lessons or overlapping preferences that need consolidation.
brief promote	Move source-derived evidence into durable memory before it can influence onboarding behavior.
brief merge	Collapse repeated corrections into one canonical candidate.
brief review	Establish the approval pattern: candidates are reviewed deliberately, not auto-applied.

The current brief review TUI is a maintenance queue for stale and duplicate entries. P4 does not require preference maturation to reuse the exact same UI, but it should reuse the same human-review posture.

Lifecycle

Preference maturation has five stages.

1. Capture

Behavioral corrections are first captured as ordinary memory:

• a lesson when the agent made a concrete mistake
• a decision when a broader operating rule is established
• a promoted source-backed entry when external evidence is worth retaining

At this stage nothing changes in brief --agent.

2. Candidate identification

Candidates are identified from accumulated memory and existing preferences.

Typical triggers:

• the same correction appears repeatedly across lessons
• multiple preferences overlap or conflict
• an onboarding preference becomes stale
• a lesson is clearly load-bearing and should stop relying on ad hoc retrieval

This is where stale, duplicates, and merge provide the raw maintenance signals.

3. Synthesis proposal

A candidate preference change is drafted from one or more underlying entries.

The proposal may take one of four forms:

• add a new onboarding preference
• revise an existing onboarding preference
• merge multiple onboarding preferences into one canonical rule
• demote, archive, or remove onboarding status from a stale or superseded rule

Promotion is not enough. Synthesis is conflict-resolution, not accumulation. The goal is a smaller, sharper onboarding set, not a longer one.

Until a human approves the proposal, it must remain outside the active onboarding filter. In current repo terms, that means it must not yet be an effective category=preference + tag=onboard entry that brief --agent would load.

4. Human review

A human reviews the proposal before it changes onboarding behavior.

The review decision must answer:

• Is this correction durable enough for unconditional load?
• Is the wording precise enough to be a stable behavioral rule?
• Does it replace an existing onboarding preference?
• Should an older onboarding preference be demoted, merged, archived, or have its onboard tag removed?

No fully automatic rewrite path is allowed.

5. Approved application

After approval, the human applies the change using existing entry operations.

Possible actions with the current model:

• create or edit a category=preference entry
• add tag=onboard to an approved onboarding preference
• merge overlapping entries into a canonical preference
• archive or de-onboard superseded preferences

P4 does not require a new storage type. It uses existing entries, categories, tags, and maintenance operations.

Bounded onboarding rules

The brief --agent payload is a startup budget, not a warehouse.

Preference maturation must obey these rules:

1. Every onboarding preference must be load-bearing. If it only matters in rare tasks, it belongs in ordinary memory or brief context, not unconditional startup.
2. Promotion without pruning is failure. A new onboarding preference should trigger a check for overlap, redundancy, or supersession.
3. Demotion matters as much as promotion. Removing tag=onboard, merging redundant rules, or archiving stale preferences is part of maturation.
4. default_limit remains the hard budget. Future implementation may improve ranking or proposal flow, but it must not assume the onboarding set can grow without bound.
5. brief context does not become a pressure-release valve for bad onboarding hygiene. User-scope and env-scope remain separate.

State transitions

The intended state model is:

1. lesson / decision / promoted memory
2. candidate for synthesis
3. reviewed proposal
4. approved onboarding preference (category=preference with tag=onboard)
5. stale, merged, demoted, or archived onboarding preference

Future implementation may add more explicit workflow surfaces, but it should map back to these transitions.

Relationship to related issues

• #57 defines the agent workflow layer: when agents start, search, save, and end a session.
• #59 provides the maintenance primitives required to keep memory trustworthy.
• #62 is the problem statement for preference maturation and the reason this design exists.
• #63 is the roadmap that sequences P4 after P3 and before later retrieval work.

The relationship is sequential, not competitive:

• #59 provides the primitives
• #57 provides the workflow posture
• #62 applies both to onboarding preference maturation

Implementation guardrails for a later phase

When P4 is implemented in code, that implementation should:

• preserve the current brief --agent schema
• keep approval explicit
• prefer small, composable operations over a monolithic “dreams engine”
• treat demotion and supersession as first-class operations
• avoid vendor-specific memory assumptions

Related

• Context Contract
• Claude Code Integration