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:

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:

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:

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:

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.