---
slug: "pi-company"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/aa2246740/pi-company@main/README.md"
repo: "https://github.com/aa2246740/pi-company"
source_file: "README.md"
branch: "main"
---
# pi-company

[English](https://github.com/aa2246740/pi-company/blob/HEAD/README.md) | [中文](https://github.com/aa2246740/pi-company/blob/HEAD/README.zh-CN.md)

> Run Pi agents like a visible local project team.

`pi-company` connects the Pi sessions you already open into one local workflow: lead keeps the global brief, workers coordinate through mailboxes, coders edit in isolated git worktrees, and local PRs cannot merge until review, test, and product acceptance gates pass.

- Source: https://github.com/aa2246740/pi-company
- Website: https://aa2246740.github.io/pi-company/

## Why Install It?

If you are already opening several Pi windows for one project, `pi-company` adds the missing operating layer:

- **Visible agents, not hidden subagents.** Every worker is still a normal Pi session you can watch, interrupt, and steer.
- **One shared project truth.** Lead reads local issues, PRs, gates, inboxes, runtime state, and recovery snapshots before claiming work is done.
- **Parallel code without branch chaos.** Coder agents work in separate git worktrees and must submit local PRs.
- **Quality gates before merge.** Review, tester validation, automated checks, and PM/lead product acceptance are tracked as structured evidence.
- **Human steering stays global.** When you type into any company Pi session, the guidance is mirrored to lead so the team does not drift.
- **Provider pressure is managed.** Requests are queued and staggered per provider to reduce overload failures and noisy recovery storms.

The point is simple: keep the speed of multiple agents without giving up the control of a human-readable project process.

## 🏆 Benchmark: OKF v3 beats plain single-agent on official SWE-bench

Same model (`openai-codex/gpt-5.5`), same instance, same base commit, scored by the **official SWE-bench Verified harness**. Only difference: orchestration.

| Instance | plain | **pi-company v3** | result |
|---|:---:|:---:|---|
| `django__django-13212` | ❌ 3/5 | ✅ **5/5** | **v3 wins** |
| `django__django-13128` | ✅ | ✅ | tie |
| `sympy__sympy-18199` | ❌ 0/1 | ❌ 0/1 | tie |
| `sympy__sympy-14248` | ❌ | ❌ | tie |

**v3 vs plain: 1 win, 3 ties, 0 losses. Resolve rate: plain 25% → v3 50%.**
pi-company **never scored below plain**, and converted a hard near-miss into a full resolve.

### Why it wins (not luck — a mechanism)

The win on `django-13212` is mechanistically explained. Both plain and the older
OKF layer scored 3/5 — both missed `django/forms/fields.py`, where
`DecimalField` rejects `NaN` before ever reaching the validator. **pi-company v3's
contract negotiation** (coder + tester each propose testable Done assertions
*before coding*) explicitly surfaced:

> “DecimalField rejects `Decimal('NaN')` with `%(value)s` … value rendering as NaN”
> “FileField … FileExtensionValidator rejects a disallowed extension”

Working against assertions that *named* those hidden paths, the coder edited
`forms/fields.py` — the file plain never touched — and the adversarial evaluator
verified every field type. **This is the core thesis of the “agents that run for
hours” pattern made concrete: a negotiated contract bridges “user story” to
“testable behavior”, and an adversarial evaluator enforces it.**

> Full evidence, honest limits, and per-case breakdown:
> [`docs/okf/OKF_V3_BENCHMARK.md`](https://github.com/aa2246740/pi-company/blob/HEAD/docs/okf/OKF_V3_BENCHMARK.md)

### How v3 works

- **Contract negotiation** — before any code, coder and tester each produce
  concrete, testable “Done” assertions; the driver merges them into the
  SprintContract.
- **Adversarial loop** — evaluator verifies against the *negotiated* assertions;
  blocking findings route back to coder; re-verify; up to `maxRounds`, with
  anti-thrash escalation to a human.

```bash
pi-company adversarial negotiate --contract <id> --agents coder=coder --agents tester=tester ...
pi-company adversarial run --contract <id> --coder coder --evaluator tester --max-rounds 3 ...
```

It runs as a deterministic driver (not a daemon), reusing the OKF operating layer
(mailbox, findings, contracts, handoffs, preflight, export gate). No new runtime
truth sources.

## 60-Second Start

```bash
npm install -g pi-company
pi install npm:pi-company
cd ~/Documents/cmux/tarot-draw
pi
```

Inside Pi:

```text
/company-init
```

Then talk to lead:

```text
Build the tarot draw site. Decide which roles are needed, create issues, and keep the project gated until it is tested and accepted.
```

After a project has `.pi-company/`, ordinary `pi` starts from that directory attach to the existing company automatically. Ordinary directories stay ordinary Pi.

## What It Looks Like

```text
human -> lead -> local issues -> coder worktrees -> local PR
      -> reviewer + tester -> PM/lead acceptance -> gates -> lead merge
```

Every company agent gets a desk panel inside Pi. Agents coordinate through local tools and mailbox messages. cmux can open panes automatically, but it is optional. Without cmux, you can paste launch commands into ordinary terminal windows.

## What You Get

| Capability | What it means in practice |
| --- | --- |
| Lead brief | A single local delivery truth before anyone says "done". |
| Human steering mirror | Guidance typed into any company Pi session reaches lead. |
| Local issues | Lead breaks work into owned tasks instead of vague chat promises. |
| Coder worktrees | Parallel implementation without agents editing the same checkout. |
| Local PR gates | Coder ready, automated tests, reviewer approval, tester pass, PM/lead acceptance. |
| Recovery snapshots | If a worker pane disappears, lead sees bounded terminal text instead of waiting silently. |
| Provider queue | Same-provider requests are limited and staggered before overload errors pile up. |
| Role model policy | Different roles can launch with different configured Pi models. |
| Advisor mode | Fast executors can pause at high-leverage moments and consult one explicitly configured stronger model inline. |

## What It Is

`pi-company` has two pieces:

- **Pi extension/package**: loaded into Pi sessions to add the desk panel, mailbox polling, tools, slash commands, and human-steering mirror.
- **Helper CLI**: used to initialize a project, print launch commands, spawn agents, inspect status, and handle occasional operations.

Node is only the runtime for the CLI and extension code. You do not run a Node daemon in daily use. You enter a project directory and launch Pi with the pi-company extension.

## What It Is Not

- Not a cloud service.
- Not a headless orchestrator that hides work from you.
- Not a replacement for Pi.
- Not a cmux-only tool. cmux improves pane management, but the runtime works with normal terminals.
- Not a license to skip review. The whole point is to make multi-agent work auditable.

## Daily Use

```bash
pi
```

Inside Pi:

```text
/company-init
```

`/company-init` creates the project-local `.pi-company/` state and attaches the current Pi session as `lead`. After that, starting Pi from that directory is enough: Pi restores the chat session normally, and pi-company automatically attaches to the existing company, shows the desk panel, registers company tools, mirrors human steering, gates provider requests, and refreshes role/lead context before each agent turn.

If you prefer shell-first setup, `pi-company init` does the same initialization before you launch Pi.

If you want to manually push the current role instructions and lead brief into the visible chat, run `/company-start` inside Pi. It is a refresh command, not a required resume step.

If a one-off skill or maintenance task needs ordinary Pi behavior, run
`/company-pause` in that Pi session. It pauses inbox delivery and provider
gates, blocks `company_*` tools, disables role file guards, and injects a small
pause override telling Pi to ignore earlier company role/brief instructions for
that session only. Run `/company-resume` to restore company context. Use this as
an escape hatch, not as the normal way to bypass role ownership.

Installing the Pi package does not make every `pi` session a company session. In ordinary directories without `.pi-company/`, Pi stays ordinary: pi-company does not create files, register company tools, mirror human input, gate provider requests, or show the company desk panel.

Then talk to lead in natural language:

```text
Continue the tarot draw website. Check current state, decide which roles are needed, and distribute the work.
```

Lead uses pi-company tools to create issues, assign work, coordinate coder/reviewer/tester/PM, and track gates. If you need another visible agent pane, lead can spawn it through tools, or you can run:

```bash
npm install -g pi-company # optional helper CLI
pi-company spawn tester --manual
pi-company spawn coder --name coder-ui --yes --manual
```

If cmux is installed:

```bash
pi-company spawn tester --cmux
pi-company spawn coder --name coder-ui --yes --cmux
```

`spawn` and `launch-command` start company-managed agents with Pi `--approve`
so generated worktrees do not block on Pi's project trust prompt. Ordinary `pi`
sessions outside a company project are unchanged.

`--root <project>` is only for operating on a project while your shell is somewhere else:

```bash
pi-company --root ~/Documents/cmux/tarot-draw status
```

When you are already inside the project directory, omit `--root`.

If you prefer to launch lead directly from the shell:

```bash
eval "$(pi-company launch-command lead)"
```

Running `init` again in an existing company is idempotent. It loads the existing
event log instead of resetting roster, issues, PRs, or agent status.
`init` also keeps `.pi-company/` in `.gitignore` so local company state and
managed worktrees do not get committed by `git add .`.

## Lead Is the Human Proxy

Lead is not a passive dispatcher. Lead should make routine low-risk decisions, preserve the human's requirements, and keep the project moving. Lead should only ask the human for decisions that are irreversible, expensive, legal/security sensitive, external-contract dependent, brand-risky, or mission-changing.

Lead should not absorb role-owned execution work. If the human names a required skill, tool, or method, lead preserves that requirement in the assignment to the responsible agent instead of doing that work in the lead context.

Handoff is the important exception. If the human invokes `$handoff` or asks for
a handoff to another agent/session, lead should produce the redacted
non-runnable handoff directly, save it to the OS temporary directory, include
suggested skills, and avoid worker delegation, local issues, PR gates, or
project worktrees. Handoff is a human export artifact, not a project deliverable.

## Current Scope

- Pi required
- Local single-machine runtime
- One project per company
- Project-local `.pi-company/` state
- Event log + reducer + mailboxes
- Local issues and PR gates
- Separate coder worktrees for parallel code edits
- Human steering mirrored to lead from every interactive Pi session
- Organization-level rate-limit backoff and staggered recovery
- Optional cmux spawn adapter

## Development

```bash
npm install
npm run check
npm run build
```

## Role File Boundaries

Pi-company separates files by their impact, not by whether they are written
with a `write` tool. Non-coder roles can write non-runnable Markdown/docs in
their responsibility area: PRDs, product specs, design notes, test reports,
review notes, research reports, repo-governance docs such as `AGENTS.md` /
`CLAUDE.md`, and `docs/agents/**`.

Runnable or behavior-changing files still belong to coder worktrees and PR
gates: source files, HTML/CSS/JS, configs, package files, scripts, CI, tests,
assets, generated app files, and other implementation artifacts. Coder agents
can mutate only inside their assigned worktree.

Non-runnable Markdown/text handoff artifacts under the OS temporary directory
are allowed for all roles. They are treated as human export artifacts, not
project deliverables.

For source development:

```bash
npm install
npm run build
node dist/src/cli.js status
```

Use `spawn` to create a new named agent or to launch an existing roster member.
For an exact shell command without spawn ergonomics, use `launch-command <agent>`.

## Role Model Policy

Pi-company can launch different roles with different Pi models.
Model choices are not free-form inside the Pi UI: lead uses Pi's configured
available model list, the same source as `/model` and `pi --list-models`.

In the lead Pi pane, the human can simply say "configure role models" or run:

```text
/company-configure-models
```

Lead opens a choice-based wizard. The human does not need to know role names
ahead of time. The wizard lists each target with its current setting:

- default model for future and unconfigured roles
- up to two global fallback models for provider failures
- all built-in roles: lead, pm, designer, researcher, coder, reviewer, tester
- the inline advisor model target (it is not a persistent agent role)

Targets show whether they are explicitly configured, inheriting the default, or
falling back to Pi's current startup model before the human changes anything.

For each target, lead chooses one model from Pi's configured models, then an
optional thinking level. After one target is configured, the wizard asks whether
to configure another role, default, or fallback.

The selection is saved to `.pi-company/company.yaml` under `model_policy`.
For example:

```yaml
model_policy:
  roles:
    coder:
      provider: openai-codex
      model: gpt-5.6-luna
      thinking: low
    advisor:
      provider: openai-codex
      model: gpt-5.6-sol
      thinking: high
    reviewer:
      provider: openai-codex
      model: gpt-5.6-terra
      thinking: high
    tester:
      provider: openai-codex
      model: gpt-5.6-terra
      thinking: medium
  fallbacks:
    - provider: xiaomi-token-plan-cn
      model: mimo-v2.5-pro
    - provider: openai-codex
      model: gpt-5.5
      thinking: high
```

If no explicit default is configured, agents inherit Pi's normal startup model,
which is usually the same model the lead pane was launched with. If default is
changed, dynamically added agents inherit that default unless their role has a
role model policy.

Fallbacks are global, not per-role. When a provider-specific `429`, quota, or
similar service incident is active, newly launched or relaunched agents keep
their role's main model unless that model uses the unhealthy provider. If it
does, pi-company tries the first configured fallback whose provider is different,
then the second. This keeps recovery simple: configure role primaries once, then
keep one or two organization-wide backup providers.

Pi-company intentionally keeps this as an organization-level policy. If one
specific running agent needs a temporary model change, switch it in that agent's
own Pi pane with Pi's normal model controls instead of encoding it into the
company defaults.

The next `launch-command` or `company_spawn_agent` run for that role includes
Pi flags such as `--provider`, `--model`, and `--thinking`. Running Pi panes keep
their current model until they are restarted or changed inside Pi.

## Advisor Mode

Advisor mode adds vertical escalation to pi-company's existing horizontal team.
A fast lead or coder remains the executor. In the default `adaptive` strategy it
continues locally until there is evidence worth escalating: the same bash/write
attempt fails repeatedly, the assigned issue is blocked, a reviewer explicitly
requests changes, or the executor faces a consequential unresolved or risky choice.
Pi-company then requires the parameterless `company_consult_advisor` before more
state-changing work, while leaving read-only orientation available. It pauses only
that executor, sends a bounded copy of its active Pi
branch plus a read-only company snapshot to the configured advisor model, and
returns the advice as the tool result in the same agent loop.

Configure it from the lead pane with `/company-configure-models`:

1. Give `coder` a fast, inexpensive model with low or medium thinking.
2. Give `advisor` the strongest trusted model available, usually with high thinking.
3. Give `reviewer` and `tester` reliable models for independent validation. They
   may be cheaper than the advisor, but should not be the executor that wrote the change.

The `advisor` role model is an inline capability; no persistent advisor pane needs
to be launched. If `model_policy.roles.advisor` is absent, the tool sends nothing
and returns setup guidance. Only lead and coder executor sessions receive the tool;
reviewer and tester sessions stay independent.

Normal use does **not** require a prompt that names the tool. In `auto` mode both
the executor and the runtime can escalate: the model may ask on genuine uncertainty,
while deterministic runtime triggers cover observable failures and review state.
The default task budget suppresses repeated consultations after one sent automatic
attempt. Control availability at any point in the Pi session:

| Command | Effect in the current Pi session |
| --- | --- |
| `/company-advisor auto` | Expose the tool and enable the configured adaptive/eager strategy. `/company-advisor on` is an alias. |
| `/company-advisor once` | Arm one real consultation; it switches to `off` when the provider payload is ready to dispatch. Setup, queue, empty-context, and pre-payload adapter failures do not consume it. |
| `/company-advisor off` | Hide the tool, disable any adaptive write gate immediately, and reject a stale tool call without reading or sending the transcript. |
| `/company-advisor default` | Clear the session override and follow `advisor_policy.enabled`. |
| `/company-advisor status` | Show mode, strategy, source, active-tool state, model, turn/task usage, and pending trigger count. With no argument, the command also shows status. |

These commands do not inject a user message. The mode is stored as a Pi custom
session entry, restored across resume/tree navigation, and excluded from model
context. The footer shows `advisor:auto`, `advisor:once`, or `advisor:off`.
Pi `0.80.6+` is required; active-tool changes made mid-run are reflected in
the next provider request in that same agent run. Pi's startup `--tools` and
`--exclude-tools` selection is a hard filter and still wins over session mode;
restart Pi without that filter to make the advisor tool available.

The project default and budgets can be tuned in `.pi-company/company.yaml`:

```yaml
advisor_policy:
  enabled: true
  trigger_mode: adaptive
  max_uses_per_turn: 1
  max_uses_per_task: 1
  repeat_failure_threshold: 2
  timeout_ms: 120000
  max_output_tokens: 4096
  max_transcript_chars: 240000
  max_company_context_chars: 24000
```

`enabled: true` means the project default is `auto`; `false` means `off`.
`trigger_mode: eager` restores the original start/stuck/final checkpoint guidance,
but `adaptive` is the recommended default. `once` intentionally bypasses the
automatic per-task budget. A session command can override availability without
rewriting company configuration.

Advisor calls use the same provider concurrency queue as company agents. The event
log records model, status, duration, token usage when available, truncation
statistics, trigger reasons, and hashed failure fingerprints, but never the failed
command, tool output, transcript, or advice text. If that metadata write fails,
the tool result returns an explicit audit warning instead of hiding the loss. Advisor output is strategic
guidance only: reviewer/tester evidence, product acceptance, lead brief, git state,
and merge gates remain authoritative.

Inside Pi, only the configured lead agent can spawn persistent agents. Other
agents should message lead when they need more role context.

Only lead can create or assign formal local issues. Other agents should report
scope changes, blockers, or follow-up work to lead through the mailbox.
Issue assignees must already exist in the company roster; spawn/register new
agents before assigning work to them.

Only the assigned issue owner can start, block, report on, or complete that
issue.

When a mission or message contains shell-sensitive text such as `$impeccable`,
`$grill-me`, or `$PORT`, read it from stdin or a file instead of putting it in
double-quoted shell arguments:

```bash
printf '%s' 'Use $impeccable to polish site/.' \
  | node dist/src/cli.js spawn coder --name coder-ui --yes --manual --mission-stdin

printf '%s' 'Run: PORT=8765; curl http://127.0.0.1:$PORT/' \
  | node dist/src/cli.js message --from lead --to tester --type test --text-stdin
```

Launch a coder with an isolated worktree:

```bash
node dist/src/cli.js spawn coder --name coder-api --yes --manual
```

New coder worktrees branch from `main` when it exists, regardless of the
current checkout in the project root.

If cmux is installed and available:

```bash
node dist/src/cli.js spawn tester --cmux
node dist/src/cli.js spawn coder --name coder-api --yes --cmux
```

## Pi Extension

The package exposes the compiled extension through `package.json`:

```json
{
  "pi": {
    "extensions": ["./dist/extensions/company.js"]
  }
}
```

During development you can also load the source extension:

```bash
pi -e ./extensions/company.ts --company-root "$PWD" --company-agent lead --company-role lead
```

The extension registers:

- UI: status line and desk panel for the current agent
- input hook: mirrors interactive human steering to lead
- mailbox poller: reads local messages; wake metadata tells future launchers whether a message should wake immediately or wait for digest
- commands: `/company-init`, `/company-start` (manual brief refresh), `/company-resume`, `/company-pause`, `/company-maintain`, `/company-status`, `/company-advisor`, `/company-brief`, `/company-inbox`, `/company-ack`, `/company-send`, `/company-configure-models`
- tools: inline advisor consultation, status, lead/global brief, lifecycle maintenance, inbox, send message, issues, task updates, spawn agent, local PR gates, review, test, product acceptance, automated-test evidence, merge request, rate-limit report, model policy configuration

`company_lead_brief` is the lead's authoritative global delivery view. Lead
must use it before telling the human that work, a feature, a PR, or the project
is complete or merged. Worker prose such as "done", "merged", "tested", or
"basically complete" is not delivery truth until the brief shows the related
issues done, PRs merged, and no dirty tracked worktree blockers.

## Lifecycle Maintenance

Pi-company keeps volatile agent liveness under `.pi-company/runtime/` instead
of appending periodic heartbeat events forever. Lead runs a lightweight watchdog
that can:

- read live cmux terminal text with `cmux read-screen`
- write bounded recovery snapshots under `.pi-company/runtime/recovery/`
- notify lead when an assigned worker is offline or stale
- hibernate idle worker surfaces with `cmux close-surface` while preserving
  worktrees, branches, issues, and PR records

The default policy keeps at most six active company-owned surfaces, hibernates
idle coder panes after five minutes, hibernates idle non-coder workers after
fifteen minutes, and keeps one warm `pm`, `tester`, and `reviewer` when idle.
It does not auto-relaunch closed workers by default; lead decides whether to
relaunch the same owner or reassign after reading the terminal-text excerpt.

Lead can run the same pass manually with `/company-maintain` or the
`company_maintain` tool.

## Message Backpressure

Every message is still written to the target agent's mailbox. To avoid wake
storms and Pi provider `429` errors, each message also carries a wake decision:

- `immediate`: suitable for waking the target agent now
- `digest`: keep it in inbox; let the target agent read it in the next batch

By default, human steering always wakes lead. Assignments, review requests, test
requests, and system messages can wake immediately, but respect per-agent and
organization-level cooldowns. The default wake policy is light: the same agent
can be woken again after 10 seconds, with up to six immediate wakes per agent
per minute and twelve per company per minute. Normal reports, replies, and
questions default to digest unless marked high priority.

The Pi extension records provider HTTP `429` responses through Pi's
`after_provider_response` hook. It also catches `429` or quota-like failures
while injecting mailbox follow-ups: the message remains unacknowledged, the
company enters backoff, and delivery is retried only after the wake policy says
the target agent can resume.

pi-company also gates provider requests before they are sent. Every Pi pane
loads the extension, and `before_provider_request` acquires a local provider
lease under `.pi-company/provider-queue/`. By default, one company allows at
most three concurrent requests per provider and spaces starts for the same
provider by five seconds. If Pi does not expose a provider name for a request,
the request is conservatively grouped under `unknown-provider`.

If an agent, human, or external supervisor sees provider `429`, quota
exhaustion, or repeated retry failures outside those hooks, report the incident
instead of retrying in a loop:

```bash
pi-company rate-limit --actor tester --reason "Retry failed after 3 attempts: 429 Too many requests"
```

For cmux-based companies, an external supervisor can scan visible pi-company
surfaces and report terminal-text-visible provider failures:

```bash
pi-company cmux-rate-limit-scan --workspace workspace:16
```

The scan ignores pi-company's own `rate-limit: active/recent` status lines and
does not extend an already active backoff unless `--force` is passed.
If a scan or human observation is verified as a false positive, lead can clear
the backoff with `pi-company rate-limit-clear --actor lead --reason "..."` or
the `company_clear_rate_limit` Pi tool.

Inside Pi, agents can use the `company_report_rate_limit` tool for the same
purpose. The first provider `429` pauses automatic wakes for 60 seconds. A second
report while the pause is active backs off to 120 seconds, up to a 10 minute cap.
Quota exhaustion uses at least a 10 minute pause. Lead is resumed first; other
agents are resumed in 30 second staggered intervals so recovery does not wake the
whole company at once.

The wake policy is not the main provider-safety mechanism. It only prevents
message storms. Provider safety comes from the request gate: at most three
concurrent requests per provider, with starts spaced by five seconds by default.
Extra messages are queued as digest wakes only when they would repeatedly wake
the same agent or exceed the company wake budget.

This is harness-level buffering for mailbox delivery and follow-up wakes. It
does not replace Pi's provider retry logic for a model request that is already
running. When that request fails, the agent records the rate-limit incident and
lets pi-company delay the next wave of work.

Mailbox participants and inbox readers must be known agents. The special sender
`system` is allowed for system notices, but recipients are always validated
against the company roster so typo inboxes do not silently absorb work.

Agent registration must match the lead-created plan for role, branch, and
worktree. A spawned Pi session can mark itself online, but it cannot silently
turn into another role or claim another worker's branch.

## Local PR Gates

CLI `pr ready` and `pr auto-test` default to the PR author when `--actor` is
omitted. Pass `--actor tester` or `--actor system` explicitly when those actors
actually produced the automated test evidence.

`pr review`, `pr test`, `pr accept`, and `pr auto-test` accept an optional
`--head <commit>` that pins the evidence to the exact commit the actor verified.
When omitted, evidence is stamped against the current branch tip. Passing the
reviewed commit closes a race where a coder lands a new commit between
inspection and evidence submission: the gate only counts evidence whose head
matches the PR's current head, so head-pinned evidence on a superseded commit
correctly goes stale instead of green-lighting unreviewed code.

A PR is mergeable only when:

- the PR author is an existing coder agent
- issue-bound PRs are created by the assigned owner of that issue
- the PR branch and worktree match the author's registered branch/worktree when they are known
- coder self-test evidence exists
- test brief exists
- automated tests are recorded as passed
- required independent reviewer approvals exist
- independent tester validation is pass
- PM or lead product acceptance is accept
- PR ready, review, test, product acceptance, automated test, and merge-request events come from known agents with the right role or ownership
- self-test, review, tester validation, product acceptance, and automated test evidence all match the current PR branch HEAD
- the PR branch resolves to a git commit and is not the base branch
- the PR branch still merges cleanly against the current base branch
- green evidence is explicitly clean and has no structured caveats; legacy summaries are also scanned for caveats, known issues, or unresolved risks

Product acceptance is a product-level gate, separate from tester validation and
code review. PM or lead must verify that the user-facing behavior matches the
human request and acceptance criteria. If a required flow was not observed, an
API request/result was not visible, a named skill/tool/method was skipped, or
evidence is missing, product acceptance must request changes or record a structured caveat;
it cannot green-light the merge.

`company_merge_pr` executes the local git merge by default when lead calls it and
the gates are green. Non-lead agents can only request a merge, and lead can pass
`execute_git: false` to record a dry merge request. Tracked or staged root
changes block merge. Unrelated untracked files do not. Lead must not run raw
`git stash`, `git reset`, `git clean`, revert, or checkout-away commands in the
project root just to make a merge pass. Dirty tracked/staged root changes are a
merge blocker that must be resolved deliberately or escalated to the human. If
another PR lands first and creates a conflict, the remaining PR becomes blocked
before the project root is checked out or merged.

For UI work, tester should prefer deterministic local checks first: static file
serving, DOM/content assertions, console/error checks, and targeted browser
verification. Avoid repeated cmux browser viewport or screenshot loops in the
user's main workspace; use them sparingly because they exercise cmux's WebView
surface management, not just the website under test.

## License

Apache-2.0. Contributions are accepted under the same Apache-2.0 license unless
explicitly stated otherwise.