Moai Ref Cross Model Audit

Cross-Model Audit Convergence

This skill is the single load-point both plan-auditor and sync-auditor use when the audit plan reports a cross-model backend. It documents the one MCP tool the auditor calls, the independence rule that tool enforces, how to check the result against the plan, and how to fold the returned convergence result into the auditor's verdict.

When to use convergence vs single-model

The auditor does not choose a backend by interpreting the audit_model value. It runs moai verify audit-plan --project-root <own toplevel> first (the full flow is in each agent's MCP Audit Tools section; pass the toplevel yourself, because CLAUDE_PROJECT_DIR names the primary checkout in a worktree session) and follows the plan:

Legacy path (a binary that predates the verb). Behave as before the plan verb existed: read the project's audit_model from workflow.yaml — multi converges Claude, codex and GLM via audit_multi, claude keeps the single-model path, glm and codex call that one backend directly. Wherever audit_multi is called, pass it without a gates argument, and call it whenever the tree's workflow.yaml sets an audit model other than claude or any audit.gates key, so a plan-aware server applies the configured plan.

Single-model paths do NOT load this skill. Convergence is only the cross-model concern.

The audit_multi MCP tool

The single tool surface is:

mcp__moai__audit_multi

It is exposed by the moai mcp-server stdio server (the self-hosted MCP server shipped with the binary). The tool is a thin wrapper over the convergence engine: it does NOT re-implement the codex or GLM backends — it fans out by calling the existing single-backend handlers in parallel and synthesizes their results.

Input parameters

<!-- moai:closure-second-review:start -->

Contract-mode second review (card-bound). When the reviewed card runs under a contract-based autonomy workflow, invoke the tool with the card argument so this fan-out is recorded as the card's second review:

• pass card_id set to the card identifier from the reviewed card's contract;
• keep target: "baseBranch" — the review must cover the reviewed scope, never uncommitted changes;
• run the review AFTER the last commit that changes the card's governed paths (the contract's ownership write globs, excluding the SPEC's own directory), so the recorded scope is current for the commit that will be judged; a review recorded before that commit is stale for the closure push.

The tool appends one second-review record into the card evidence directory. Without card_id no record is written and the tool behaves byte-identically to the pre-argument surface.

<!-- moai:closure-second-review:end -->

Output shape

The tool returns a ConvergenceResult:

{
  "per_backend_verdicts": [
    {"backend": "claude", "source": "mcp_claude_audit", "gate": "required", "verdict": "pass", "summary": "...", "findings": [], "next_steps": [], "provenance": {"transport": "claude-code-cli", "auth_mode": "subscription", "requested_model": "sonnet", "resolved_model": "claude-sonnet-...", "requested_effort": "high", "session_persisted": false}},
    {"backend": "codex",  "gate": "required", "verdict": "fail", "summary": "...", "findings": [...], "next_steps": []},
    {"backend": "glm",    "gate": "advisory", "verdict": "pass", "summary": "...", "findings": [], "next_steps": []}
  ],
  "overall_verdict": "fail",
  "disagreement_flag": true,
  "participant_count": 3,
  "residual_risk_note": "required-backend FAIL: codex; cross-model disagreement: pass=[claude(required), glm(advisory)] fail=[codex(required)]",
  "fail_open_backends": []
}

• overall_verdict ∈ {pass, fail} — the existing review-output values. No new enum (disagreement is a flag, not a verdict value).
• next_steps is populated ONLY where the backend itself produced it. A backend that returns a structured review carries its model's own list; a backend that answers in prose carries none, so its entry shows [] even on a fail with findings. An empty next_steps beside a non-empty findings is therefore the expected shape, not a truncated result — do not read the finding text as steps.
• participant_count is how many backends contributed a comparable verdict: every entry whose gate is not off and whose verdict is pass or fail. inconclusive entries (missing, unauthenticated, erroring) are evidence-of-absence, not participants, and do not count. The field is always present, 0 included — it reports the count; no minimum-participant policy acts on it.
• disagreement_flag is three-valued. true = a divergence was observed: a required split, an advisory-only conflict, or a single participant's intra-backend synthesis divergence (directly observed divergences are never discarded, even below 2 participants). false = 2+ participants were compared and none diverged. null = undetermined: fewer than 2 participants were compared and no divergence was observed, so neither "they agreed" nor "they disagreed" is a grounded claim. The null is explicit — the member is always present in the JSON, never an absent key.
• residual_risk_note describes the convergence outcome in prose (which backend(s) failed, or the shape of the split). Surface this in the audit report's residual-risk section.
• fail_open_backends lists the backends that returned inconclusive (missing, unauthenticated, or erroring) — surfaced so the report can name them.
• plan_source is config when any backend's gate came from the tree's configuration, and absent otherwise. A result without it from a tree whose plan has configured gates comes from a server that predates the plan: the check below reports an unmet gate.
• source distinguishes an in-session Claude anchor from a real mcp_claude_audit call. provenance identifies transport, subscription auth, requested/resolved model, effort, tool surface, persistence, usage source, and sanitized error code. Token counts are null when the CLI does not report them; they are never guessed.

How to invoke

In a Claude main session, call the tool with the in-session analysis folded into the claude_verdict object. Do NOT pass the full analysis text as prompt context for the other backends — see the Independence rule below.

result = mcp__moai__audit_multi({
  claude_verdict: { verdict: <your verdict>, summary: <one-line>, findings: [...], next_steps: [...] },
  target: "uncommittedChanges",
  focus: "concurrency",
  project_root: <git rev-parse --show-toplevel>,
  session_id: <current session id>
})

In a GPT or GLM main session, omit claude_verdict (or treat it as ignored):

result = mcp__moai__audit_multi({
  target: "uncommittedChanges",
  focus: "concurrency",
  project_root: <git rev-parse --show-toplevel>,
  session_id: <current session id>
})

The launch provider decides the path; prompt text cannot impersonate a Claude main session. Direct single-backend use is mcp__moai__claude_audit with the same target/focus/project-root scope and optional model/effort override.

The orchestrator-side question channel is preserved: the tool returns a structured result, never prompts the user. When a required backend is inconclusive, surface the structured overall_verdict: fail plus residual_risk_note in the audit report and let the orchestrator translate.

Independence rule (load-bearing)

Pass only the synthesized claude_verdict object to the MCP tool — NEVER the full Claude analysis text as prompt context for the secondary backends.

The external backends (Claude subscription, codex, GLM) are SUPER-REVIEWS: uncorrelated second opinions. Their value collapses to a re-sample of another model's reasoning the moment they see Claude's analysis. The convergence engine enforces this structurally — the claude_verdict is consumed ONLY as a Claude-main anchor. For GPT/GLM origins it is ignored, and the backends receive (target, focus, project_root) — a scope, an area name, and a directory, carrying no analysis between them. The auditor must not undermine the invariant by pasting another backend's reasoning into the focus field either.

Concretely:

• focus carries a short AREA name (concurrency, auth, secret handling), not a paragraph of analysis.
• claude_verdict.summary is a one-line verdict rationale, not the full review.
• The findings you surface in the audit report come from per_backend_verdicts[].findings (each backend's own findings), NOT from echoing Claude's findings back.