# Advisory Personas Domain

**Status:** Approved target-state baseline  
**First product realization:** I3  
**Architecture:** `../architecture/advisory-agents.md`

## Target State

AWP models reusable stored advisor roles and their durable conversations explicitly so `Project Manager`, `AWP Advisor`, `DBA`, `CI Expert` and future expert roles are configuration/data, not hard-coded UI branches.

```text
AdvisorPersona
  -> AdvisorThread*
       -> AdvisorTurn*
            -> AdvisorContextSnapshot
            -> SourceReference*
            -> ProposalReference*
```

Built-in and user-created personas use the same lifecycle and authority model.

## Core Primitives

### AdvisorPersona

Versioned advisor definition.

Conceptual fields:

```text
id
name
role
purpose
description
scopePolicy
instructionTemplate
modelSelectionPolicy
allowedQueryCapabilities
allowedCommandCapabilities
defaultContextPolicy
threadRetentionPolicy
status
version
createdBy
updatedBy
createdAt
updatedAt
```

The persona references Account/Model/Provider selection policy; it never stores provider credentials.

### AdvisorThread

Durable conversation identity.

```text
id
principalId
personaId
personaVersion
scopeType
projectId?
title?
status
createdAt
updatedAt
archivedAt?
```

Changing persona/scope can create a new thread when the meaning/authorization context materially changes. UI can offer deliberate `Start new thread with ...` rather than silently reinterpreting historical messages.

### AdvisorTurn

One user/advisor/system tool-response turn with immutable attribution.

```text
id
threadId
actor
content / structured blocks
personaVersion
model/provider/account provenance?
contextSnapshotId
sourceRefs[]
proposalRefs[]
status
createdAt
```

Provider retry/fallback does not rewrite previous completed turn attribution.

### AdvisorContextSnapshot

Persisted description of what contextual UI scope a turn used:

```text
route
projectId?
primitiveRefs[]
filters/timeRange?
explicit attachments
observedAt
```

It is provenance, not authorization.

### AdvisorSourceReference

Typed link to the canonical primitive/evidence used to support a material assertion.

```text
primitiveType
primitiveId
revision/version?
observedAt
label?
```

### ProposalReference

Links an advisor recommendation/action card to a canonical draft/proposal/command target such as Decision proposal, Planning continuation or Task creation request.

It does not create a second generic Decision model.

## Built-in Personas

### Project Manager

```text
scope            ProjectScoped
primary job      understand/manage one Project across all Plans and lifecycle state
language         project/product-management first
recommended data ProjectVision, GOLIVE, Plans, Work, Runs, Decisions, quality/delivery/health
```

### AWP Advisor

```text
scope            SystemScoped
primary job      portfolio/AWP system analysis across all resources visible to Principal
language         portfolio/system-management first
recommended data Project summaries, Attention, cross-project delivery/CI/agent/cluster/health trends
```

Both are versioned built-ins and may expose owner-configurable settings without making their canonical identity mutable history.

## Custom Personas

Users can create/clone advisor definitions such as:

```text
DBA
CI Expert
Release Expert
Security Advisor
Architecture Advisor
```

Creation validates requested query/action capabilities against the current Principal/system ceilings. Saving an instruction that says “ignore policy and deploy” cannot grant deploy capability.

## Scope Policy

Minimum target classes:

```text
ProjectScoped
SystemScoped
```

A future persona may permit explicit scope choice, but every active thread stores the resolved scope.

`SystemScoped` means all resources authorized to the Principal, not all database rows.

## Persona Versioning

Material persona changes create a new version:

```text
instructions
scope policy
capability set
model policy
retention behavior
```

Historical turns retain the version that produced them.

Display-only metadata can update without rewriting behavioral provenance where safe.

## Persona Status

```text
active
inactive
archived
```

Deleting a persona with historical threads normally archives/deactivates it; historical attribution remains resolvable.

## Thread Status

```text
active
archived
```

Optional later states such as pinned/favorite are presentation metadata, not lifecycle authority.

## Commands

Conceptual application commands:

```text
CreateAdvisorPersona
CloneAdvisorPersona
UpdateAdvisorPersona
Activate/DeactivateAdvisorPersona
ArchiveAdvisorPersona
CreateAdvisorThread
ArchiveAdvisorThread
SendAdvisorTurn
RetryAdvisorTurn
ProposeAdvisorAction
ExecuteAcceptedAdvisorAction
```

Exact transport names may differ; all use shared control-surface/application semantics.

## Queries

```text
ListAdvisorPersonas
GetAdvisorPersona
ListAdvisorPersonaVersions
ListAdvisorThreads
GetAdvisorThread
GetAdvisorTurnSources
SearchAdvisorThreads
```

Thread search must reuse the product search/security model rather than expose a second unrestricted index.

## Canonical Truth Boundary

AdvisorThread is canonical conversation history, but not canonical software-delivery intent/state.

Material project facts must be promoted to existing primitives:

```text
ProjectVision
Decision
PlanRevision
Task
Policy / Configuration
ProjectPlanningDefaults
Incident / ResolutionRecipe
```

An advisor saying “we should change PostgreSQL policy” does not change policy until the user/authorized flow accepts the appropriate canonical command/Decision.

## Invariants From Day 1

- persona definition is versioned;
- thread stores resolved persona version and explicit scope;
- custom persona instructions cannot grant capability/data access;
- raw secrets never live on persona/thread records;
- important factual assertions can reference canonical sources/freshness;
- historical turns remain attributable after persona changes;
- thread memory never silently becomes ProjectVision/Decision/Plan truth;
- advisor write proposals route through existing command/policy/audit boundaries.

## Configuration / Policy

Configurable defaults can include:

```text
default Project advisor persona
default Home/system advisor persona
model/account selection profile
thread retention
page-context default on/off
source citation/detail level
whether particular safe proposal types are enabled
```

System policy can narrow allowed persona capabilities and data categories.

## Audit / Privacy

Persona create/update, thread scope changes and accepted proposal execution are audited. Chat content retention/export/delete follows configured policy and applicable tenant/user controls.

Do not log unredacted thread content into ordinary telemetry by default.

## Failure / Recovery

A provider/model failure does not corrupt the thread. User can retry according to model policy with explicit failure/provenance. Partial source-query failure is retained as a failed/partial turn state with retry; it is not silently converted to an authoritative answer.

## Increment Realization

| Increment | Persona realization |
|---|---|
| I1 | not active. |
| I2 | no generic persona product required. |
| I3 | AdvisorPersona/Thread/Turn + Project Manager + persistence/configuration/Decision integration. |
| I4 | AWP Advisor + richer cross-project operational sources. |
| I5–I8 | additional expert built-ins/custom capability sets consume active domains. |
| I9 | org/tenant sharing/ownership/retention/governance. |

## Current Implementation State

Target specification only.

## Deferred Realization

Persona marketplaces, autonomous scheduled advisor reports, shared organization templates and external support-bot personas are later productization decisions.

## Temporary Dogfood Behavior

No unversioned hard-coded “project manager prompt” stored only in frontend code. The first implementation uses the final Persona/Thread identities even if only one built-in advisor is exposed.

## UI Implications

Settings exposes Advisors: built-in/custom, scope, model policy, capabilities and versions. Project/global AdvisorShell displays current persona/scope and saved threads. History makes old persona version attribution understandable.

## Decisions / ADRs

Advisors are a new bounded control-plane agent role. The domain intentionally reuses existing Decision/Policy/Account/Connection semantics instead of creating advisor-specific authority or credential models.