# Clavue V2 Mao Supervisor Architecture

Date: 2026-05-02

## Product Position

Clavue V2 is a development system, not a chat wrapper. Its core promise is stronger real software delivery than single-agent Claude Code or Codex-style use: inspect, edit, test, verify, coordinate, review, and recover inside one controlled development platform.

Mao is the silent second engine in that system. `/mao` remains the user-visible management and diagnostic surface, but most Mao value should happen automatically as session-level supervision.

## Operating Model

- Clavue main lane owns user intent, repository context, edits, commands, provider state, memory, and final delivery.
- Mao supervisor lane owns independent review, scope splitting, conflict detection, adversarial checks, rescue guidance, and final evidence gates.
- Agent, subagent, team, and parallel workers receive Mao-owned scope contracts before they start.
- Coordination state is persisted under `.clavue/coordination/<session-id>/mao-ledger.json`.

## Required Supervisor Cases

Mao supervision is mandatory when:

- `/parallel` launches more than one worker.
- worker execution falls back to a shared workspace.
- multiple agents or teammates may write in the same repository.
- release, publish, tag, push, generated artifact, or dist claims are involved.
- final delivery claims implementation completion or test success.

## Coordination Ledger

The ledger records:

- session id and project root;
- user goal;
- supervisor decision and modes;
- worker scope contracts;
- worker launch/result summaries;
- coordination findings;
- final gate status.

The first V2 implementation adds `mao_supervisor_coordination_v1` and writes a ledger from `/parallel` launches. `/mao status` now discovers the latest supervisor ledger, ingests completed worker output artifacts, recomputes findings and final gates, persists the refreshed ledger, and reports its modes, findings, worker evidence, and final gate alongside manual Mao jobs. Worker-completion task notifications also refresh the ledger silently when background agents finish.

## Worker Scope Contract

Each worker receives:

- supervisor id;
- owned paths;
- forbidden paths;
- allowed actions;
- isolation mode;
- handoff requirement.
- a required `Mao worker handoff` report block with changed files, tests run, and blockers.

This turns multi-agent coordination from prompt-only guidance into a durable product contract.

## Delivery Gate

Final delivery is explicitly checked with `/mao gate`. The command refreshes the latest supervisor ledger from worker artifacts, persists the recomputed state, and renders a delivery-focused gate report with:

- status and `Can deliver` decision;
- session, goal, and ledger path;
- blocking findings;
- worker evidence, changed files, tests, and blockers;
- a hard warning not to deliver, release, publish, tag, or push while blocked.

The gate blocks when the supervisor detects:

- overlapping worker edits;
- edits outside assigned scope;
- changed files without verification;
- release or generated artifact claims without matching evidence.

This is the first user-visible delivery-control surface for Mao's silent second engine. Later work should wire high-risk final answers, push, publish, and release flows through the same gate automatically.
