@pugi/plugin-triple-review

Pugi triple-review plugin - slash command that fans the current diff out to three independent reviewers in parallel and runs a deterministic consensus coordinator. PASS / WARN / BLOCK gate before merge.

Part of the Pugi 1.0 soft fork sprint (see ADR-0081).

Status

Wired. The hook captures the diff, fans out to three sub-sessions via the Pugi SDK, runs the deterministic rubric, persists the verdict, and renders a TUI block back into the slash-command output.

Pipeline

1. command.execute.before intercepts the registered slash command (default /triple-review).

2. Flags are parsed with parseArguments: --commit <sha> / --base <ref> / --skip <id> / --council / --break-glass. A bare positional token is treated as the commit.

3. The diff is captured via PluginInput.$ (BunShell wrapper). Output is capped at 200 KB (configurable) and a marker is appended on truncation. The raw diff is persisted to /tmp/pugi-triple-review-diff-*.txt for downstream inspection.

4. Three sub-sessions (four in --council mode) are spawned in parallel via the SDK client. Each receives the same standardised prompt (STANDARD_REVIEW_PROMPT) - the apples-to-apples requirement.

5. Each reviewer's output passes through filterHallucinations first - the only codified rule today drops Gemini's decorator-as-filesystem-path confabulations.

6. parseAllOutputs regex-extracts [P0]/[P1]/[P2]/[P3] markers from each cleaned blob and records whether CLEAR: was emitted.

7. applyRubric returns the deterministic gate:

   | Condition | Gate | | -------------------------------------- | ----- | | any reviewer reports [P0] | BLOCK | | two or more reviewers report [P1] | BLOCK | | exactly one reviewer reports [P1] | WARN | | otherwise | PASS |

8. Verdict is persisted as JSON to .pugi/triple-review-log/<ts>-<sha>.json so the /learn pipeline and future CLI wrappers can read it.

9. renderVerdict produces the TUI block (counts table, verbatim reviewer output, cross-model disagreement section, recommendation) and pushes it onto output.parts as a text part.

Break-glass override

Two paths:

• --break-glass flag on the slash command itself. Logged in the verdict.
• Sentinel file at .pugi/triple-review-override (configurable). When present at hook start it is consumed (deleted) and the gate is bypassed once. Mirrors the Cloudflare pattern.

Either path produces a PASS verdict with reason = "break-glass override active - gate bypassed".

Exit-code semantics

command.execute.before runs inside the Pugi server process and cannot set process.exitCode. The plugin instead:

• persists the verdict JSON,
• appends a recommendation line saying what a CLI wrapper would do,
• exports gateToExitCode(gate) so a downstream pugi triple-review CLI wrapper can read the verdict file and exit 0/1.

The wrapper itself ships separately as part of the Pugi CLI.

TUI surface caveat

Appending to output.parts is the documented contract for slash-command hooks. The runtime fills in server-owned fields (id, sessionID, messageID) when materialising a TextPartInput. If a future Pugi runtime changes that contract, the rendered string is still preserved verbatim in the persisted verdict JSON, so no information is lost.

Install

pnpm add @pugi/plugin-triple-review

Usage

// pugi.config.ts
export default {
  plugin: [
    [
      '@pugi/plugin-triple-review',
      {
        command: 'triple-review',
        reviewers: [
          { id: 'pugi-consensus', label: 'Pugi', modelId: 'pugi-auto' },
          { id: 'gemini', label: 'Gemini', modelId: 'gemini-2.5-pro' },
          { id: 'claude-fresh', label: 'Claude', modelId: 'claude-sonnet-4-7' },
        ],
        diffBaseRef: 'origin/main',
        maxDiffBytes: 200_000,
      },
    ],
  ],
};

In a session, type /triple-review (optionally with --council for the four-reviewer mode used on DB migrations, auth, payments). The plugin fans the current diff out, applies the rubric, and prints the verdict.

Options

| Option | Default | Notes | | ------------------- | -------------------------------- | ---------------------------------------------------- | | command | triple-review | Slash command name (no leading slash). | | reviewers | Pugi + Gemini + Claude | Three reviewers spawned in parallel. | | diffBaseRef | origin/main | git diff <baseRef>..<commit>. | | maxDiffBytes | 200_000 | Hard cap on the diff sent to reviewers. | | logDir | .pugi/triple-review-log | Verdict JSON destination, repo-relative. | | overrideSentinel | .pugi/triple-review-override | Break-glass file, repo-relative. | | spawnReviewer | SDK client spawner | Injection point for tests. | | captureDiff | BunShell capturer | Injection point for tests. | | persistVerdict | JSON writer | Injection point for tests. |

Hook surface

• command.execute.before - the only hook the plugin registers.

License

MIT. See LICENSE.