# AI Persona Assistant Operating Contract

This contract defines the adapter boundary for four external systems. The local
helpers are not a replacement for those systems; they keep Company OS safe and
testable while the real dependencies are introduced behind explicit gates:

- `beads_rust`: repo-local task state, explicit mutations, JSONL export, and
  agent-readable commands.
- `beads_viewer`: graph-aware triage, ready-work selection, bottleneck analysis,
  and robot-mode summaries.
- `cass_memory_system`: episodic traces, working summaries, procedural memory,
  confidence decay, evidence gates, and anti-pattern learning.
- `asupersync`: structured concurrency, owned task regions, cancel-correct
  cleanup, two-phase effects, and deterministic replay reports.

The dependency integration policy is tracked in
`docs/company-os/PERSONA_SIDECAR_DEPENDENCY_INTEGRATION.md`. The machine-readable
policy is exposed with the production readiness contract:

```http
GET /api/company/production-readiness/contract
```

Implementation: `src/company_os/production_readiness.rs`.

## Design Principle

The persona assistant is a faithful compression of its task distribution. Keep
the high-frequency path small, resident, and very well engineered; fetch the
long tail only when evidence says the task needs it.

This means the four sidecars are not four more prompt blobs. They are the
substrate for a layered context cache:

- **L1 always resident:** common task types, approval policy, formatting rules,
  evidence policy, and tool discipline.
- **L2 curated on demand:** scoped memory, recipes, integration gotchas,
  customer context, and procedural playbooks with confidence/anti-patterns.
- **L3 raw substrate:** rare edge-case mining over traces, workspace files,
  connector docs, APIs, and raw sessions through bounded skills.

The default execution shape is one powerful `execute` / `dispatch_plan` style
surface, backed by asupersync-style owned regions, instead of many ambient tools
competing for prompt space. Background work must be joinable, cancellation must
record request/drain/finalize, and customer-visible effects must remain
two-phase: plan, approve, commit, verify.

## Flat Task Envelope Intake

Do not build a separate swarm per intake channel. Email, DM, ticket, browser,
file, API event, and manual intake adapters all normalize into one envelope
first:

```ts
type TaskEnvelope = {
  source: "email" | "dm" | "ticket" | "browser" | "file" | "api" | "manual";
  sourceRef: string;
  intent: string;
  priority: "low" | "normal" | "high" | "urgent";
  projectHint?: string;
  customerHint?: string;
  evidenceRefs: string[];
  dedupeKeys: string[];
  tags: string[];
};
```

The routing sequence is:

```text
adapter -> TaskEnvelope -> equivalence resolver -> bead router -> Swarms only after routing
```

Equivalence runs before planning or execution. The resolver should treat these
as first-class graph unification signals:

- same customer + same external ref -> equivalent
- same URL or file hash -> equivalent
- same intent + same project + close embedding -> likely equivalent
- same failure mode + same surface -> related incident cluster
- human merge/split/override remains available for ambiguous cases

Beads stay flat. Projects, epics, subtasks, workstreams, and customer views are
projections from tags and typed edges. The canonical typed edges for flat bead
routing are `blocks`, `duplicates`, `depends_on`, `evidence_for`, and
`follow_up_of`. Additional operational edges such as `related_to` or
`requires_verifier` may be derived, but the intake ledger must remain a flat
graph.

The default saved views are `Customer evidence`, `Ready work`, `Needs human`,
and `TRL proof`. Routing rules assign project, customer, and intent from the
normalized envelope before L2 planning or L3 workers see the task. This keeps
the bead graph queryable, prevents duplicated routing logic across
email/DM/ticket/API channels, and gives the product one ledger, one graph, and
many views. Swarms are reserved for execution and verification after a bead has
been routed, not for ingestion itself.

## Three-Layer Orchestrator Methodology

The assistant uses the same L1/L2/L3 context hierarchy for execution itself.
The flow invariant is:

```text
L1 define/direct -> L2 plan/adapt -> L3 execute/report -> feedback updates L2/L1
```

| Layer | Role | Company OS mapping | Required evidence |
| --- | --- | --- | --- |
| **L1 Mechanism Manager** | Global bead/project registry, system memory, flat envelope routing, graph equivalence, swarm spawning for execution, and signals. | Task envelopes, Company tasks, task events, run events, memory entries, production readiness policy, typed graph edges, and owned runtime regions. | `task_envelope.json`, `equivalence_report.json`, `bead_routing_decision.json`, `bead_registry_snapshot.json`, `tag_edge_projection.json`, `mechanism_manager_trace.jsonl` |
| **L2 Planners** | Convert goals into a living DAG: PRD -> RFC -> Epics -> Tasks -> AC & Edge Cases. | Company task dependencies, beads-viewer-style graph insight, procedural memory, customer evidence packs, approval gates, and rollback plans. | `dag_plan.json`, `ready_work_snapshot.json`, `approval_gate_plan.json` |
| **L3 Workers** | Tool Builder / Tool User / Verifier roles executing bounded work in parallel. | Skills, workspace files, connector manifests, dashboard/browser sessions, database schema catalogs, document parsing, and verifier checkpoints. | `worker_outcome_report.json`, `tool_evidence.jsonl`, `verifier_verdict.json`, `rollback_or_repair_evidence.jsonl` |

L1 is allowed to spawn and route work only when the route names the source goal,
normalized task envelope, equivalence report, bead target, tags/edges, target
planner, parent run/region, and evidence expectation. L2 is allowed to dispatch
work only when the DAG names dependencies, acceptance criteria, edge cases,
human approval gates, and rollback requirements. L3 is allowed to report
completion only when tool evidence or verifier evidence exists; a worker run
without evidence is an incomplete run, not success.

For a checkout reliability workflow, L1 registers the customer/order bead and
routes the incident to the commerce planner. L2 expands it into PRD/RFC/Epic/Task
beads with acceptance criteria such as payment idempotency, inventory
consistency, and customer notification gates. L3 then runs Tool User actions
against the dashboard, database, browser/API, and documents; a Tool Builder may
add a missing parser or connector; the Verifier checks the trace, citations,
rollback plan, and post-write query before the result is promoted back to L2/L1.

## Dependency-Backed Adaptation

| Upstream pattern | Company OS adaptation | Evidence required |
| --- | --- | --- |
| `beads_rust` | `br` is the intended task-ledger dependency. Company tasks may mirror it, but real beads claims require `br` installed, `.beads` initialized, and JSON output attached. | `sidecar_dependency_status.json`, `task_ledger.jsonl`, `ready_work_snapshot.json` |
| `beads_viewer` | `bv` is the intended graph-triage dependency. Local ready-work scoring is a fallback only until `bv -robot-next -format json` succeeds. | `sidecar_dependency_status.json`, `dependency_graph.json`, verified run timeline |
| `cass_memory_system` | External CASS must be a CLI or service dependency before we claim its memory behavior. In-repo `src/cass` remains a separate local subsystem. | `sidecar_dependency_status.json`, `persona_context.json`, `memory_promotion_evidence.json`, `anti_pattern_warning.json` |
| `asupersync` | `asupersync` must be linked behind a compile/runtime gate or isolated crate before it owns Company OS runs. Tokio regions remain a compatibility fallback. | `sidecar_dependency_status.json`, `region_run_report.json`, `cancellation_drain_report.json`, `rollback_plan.json` |

## Required Capabilities

1. Task state is local-first and exportable.
2. Ready work is dependency-aware.
3. Context cache declares L1/L2/L3 boundaries.
4. The single powerful execution surface is preferred over many ambient tools.
5. Persona context uses scoped memory instead of prompt stuffing.
6. Memory promotion has evidence, confidence, and anti-pattern handling.
7. Run children are owned by a parent run or runtime region.
8. Cancellation records drain, finalize, and cleanup budget.
9. Writes use two-phase plan, approve, commit, verify.
10. Workspace files can attach, parse, cite, and review evidence.

## Claims Blocked Without Evidence

Do not claim the assistant has durable cross-session memory, selected the
highest-leverage next work, avoided orphaned subtasks, performed lossless
cancellation, or can autonomously write to customer systems unless the evidence
artifacts above are attached to the run or customer evidence pack.

Do not claim real upstream sidecar operation unless
`sidecar_dependency_status.json` proves that dependency is installed and usable
for the current workspace.

## Product Surface

The `/workspace/files` evidence workbench includes an `Assistant` inspector tab
that shows these adaptations next to document evidence review. This keeps the
persona-assistant promise tied to files, citations, memory, task trails, and
rollback evidence instead of isolated marketing copy.