/moai-ref-cross-model-audit

name: moai-ref-cross-model-audit
description: >
  Cross-model audit convergence reference for the plan-auditor and sync-auditor
  agents. Documents how to invoke the `audit_multi` MCP tool to fan a code
  review out across the Claude subscription, codex, and GLM (z.ai) backends,
  converge their independent verdicts, and fold the resulting
  per-backend verdicts + disagreement flag into the audit output. The single
  skill both audit entry points load — no duplication.

when_to_use: >
  Use when the audit plan (`moai verify audit-plan`) reports a cross-model
  backend AND the auditor needs a cross-backend second opinion before reaching
  a verdict. Also use when the
  auditor runs under a GPT or GLM main session and needs an independent Claude
  subscription verdict through `claude_audit`, or when it must explain why the
  convergence result is a pass, fail, or
  advisory-only disagreement.

user-invocable: false
metadata:
  version: "1.1.0"
  category: "domain"
  status: "active"

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:

| Outcome of the verb | Path | This skill | |---|---|---| | `config_status` `ok` or `absent`, `cross_model_active: false` (the distributed default, an explicit `claude` token) | Claude main: in-session review; GPT/GLM main: `claude_audit` | for external-main sessions | | `cross_model_active: true` | `audit_multi` without a `gates` argument: the plan's backends, converged | **this skill** | | The output is the `verify` group's help text (it contains `Shared diagnostic snapshot contract` and neither `config_status` nor an `audit-plan:` line) | The legacy path below, with "plan surface unreachable, legacy path used" named as a Gap | only as the legacy path says | | `config_status: unreadable`, an `audit-plan:` error, or any other failure to run the verb (refused, crashed, timed out, malformed output) | Not the legacy path: a PASS-blocking Gap; a configured required backend that does not answer stays fail-closed | no PASS on this audit |

**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

| Parameter | Type | Required | Notes | |---|---|---|---| | `claude_verdict` | object | conditional | Claude main sessions pass their in-session verdict. GPT/GLM/unknown-origin sessions may omit it; `audit_multi` ignores any supplied value and performs a fresh Claude subscription audit. | | `target` | string | no | What the secondary backends review (`uncommittedChanges`, `baseBranch`). The string reaches both backends unchanged; for codex, `baseBranch`'s branch name is then resolved server-side from the reviewed tree (remote default head, then `main`) — it cannot be supplied here. | | `focus` | string | no | Optional focus area forwarded to the secondary backends (e.g. `concurrency`, `auth`). | | `gates` | object | no | Per-auditor gate map (`claude`/`codex`/`glm` ∈ `off`/`advisory`/`required`). Auditors do not pass it: omitted, the tree's own plan applies (the configured audit model and gates); with no configuration the distributed defaults apply — claude required, codex required, glm advisory — and an unconfigured gate stays fail-open. | | `session_id` | string | no | When set, the result is persisted to `.moai/state/audit-multi/<session>.json` so the multi-review-gate Stop hook reads the most recent result rather than re-invoking convergence. | | `delta_base` | string | no | With `card_id` and target `baseBranch`, omitted ⇒ the `audited_sha` of the card's newest FAIL verdict file is proposed as the delta base; `"full"` ⇒ review the full resolved base. A proposal is a request, not a grant: see Delta review below. | | `blocking_closed` | object | no | Delta confirmation: maps each `blocking_defect:` id of the card's FAIL verdict files to the commit that closed it. Ignored without `card_id` and a delta base. | | `rerun_legs` | array | no | Backend names (`claude`, `codex`, `glm`) to run again; requires `session_id`. The other legs are carried from the result the server persisted for that session. | | `project_root` | string | no *(REQUIRED in a worktree)* | The tree the backends should read — this session's own `git rev-parse --show-toplevel`. Omitted from a worktree, the fan-out reads the PRIMARY checkout instead, so the backends review a diff that is not the one under audit and nothing in the result s