macprovider: Instructions file for Codex

MacProvider Agent Guide

This file is the canonical instruction surface for every coding agent in this repository. Keep it short, concrete, and current. Put long incident writeups in docs or runbooks and link them from here.

HARDEST RULE — no options, always implement the goal

Never present the operator with two or more options, an either/or menu, or a "proceed vs hold" question. Do not stop to ask which path to take. Pick the single best path toward the stated goal and implement it directly. If a prerequisite is genuinely blocking (missing access, a hard permission denial), do everything possible around it, then surface the one specific unblock needed — never as a menu. Analysis and status are fine; decision-shaped menus are not.

HARD RULES — activation, evidence, and campaign discipline

These exist because native MTP and CB sat qualified-but-inactive for a week while sessions regenerated evidence instead of deploying. Each is binding.

1. Done means live; merged work closes its issue. A goal of "X active" is reached only when a live probe shows X serving a real buyer request through the Malibu gateway. When the work is implemented and merged, close its issue and record the remaining live step (CLI cut, signed policy, coordinator rollout) in docs/releases/cli-release-train.md or the coordinator release doc; that doc, not an open issue, tracks it to live. A PR that changes catalog, CB, or native-MTP state must name its deploy command in the body, and the merging session deploys it the same day.
2. Reuse evidence; never regenerate it. Before proposing any benchmark, qualification, journey, or evidence capture, list the existing evidence and name the decode-path code line that changed since it was produced. No named line, no benchmark. A new CLI cut changes only identity binding (source, SHA-256, CDHash), never the qualification.
3. Unclearable gates get flagged once. If a runbook gate depends on a workflow or journey that has never run, report it to the operator in one line on first encounter. Do not build evidence around it and do not treat it as blocking after the operator has decided.
4. One campaign, one PR. Before gh pr create, run gh pr list --state open --search "<issue or epic number>". If an open PR exists for that issue or epic, push to it.
5. Deploy-tooling refusals are fixed, not routed around. If release or deploy tooling refuses a coherent change, fix the tooling in the campaign PR or follow its documented order. Never answer a refusal with more evidence.
6. Two sessions without a live change means stop. Write a one-paragraph blocker diagnosis to the operator instead of starting a third session.
7. Handoffs are committed to the private macprovider-internal repo and point at paths that exist. One session at a time mutates Pearl or a Studio provider. Handback is written, naming what changed live.
8. Releases and live changes go through scripts/ops/ only. CLI release, catalog/CB/native-MTP activation and the Pearl runtime train each have one entry point (cli-release.sh, catalog-activate.sh, pearl-runtime.sh). Run status, then next; next --run executes exactly one documented step and takes the live-ops lock (live-lock.sh). Never call the release workflows, deploy-pearl-vps.sh, catalog-content-release.sh --deploy, the Pearl updater --apply, or a coordinator restart directly. Claude Code enforces this with scripts/ops/hooks/claude-pretooluse-ops-guard.sh; other agents follow it from this rule. See scripts/ops/README.md.
9. No closing keyword next to an issue number (the close/fix/resolve family, any tense, even negated) in a PR body, title or commit message unless that PR completes the issue. Write Related: #N. GitHub ignores negation; that is how the #1690 and #1749 epics were auto-closed early.
10. No expiry dates on live features. Never add an expiry, sunset date, automatic withdrawal or automatic kill switch to a live product feature, its config validation, ops tooling, SPEC or decision log unless the operator explicitly asks for one. A feature that works live stays on. If a process document demands an expiry, flag it to the operator as a rule to remove instead of complying.
11. Proven changes ship on. When lab evidence shows a change works (correctness checks pass and the gain is measured) and its audit is clean, it ships enabled by default in the same PR. Do not add a default-off flag or a separate operator enable gate for it. Handle risk in the code itself (caps, bounds, fallbacks) and keep an emergency kill switch where one already exists. Signed catalog/CB/native-MTP policy is deployment state, not a default-off gate; changing it still goes through scripts/ops/.
12. Measure the goal first; build only what the number justifies. A campaign whose goal is a performance or capability gain starts with the one end-to-end measurement of the metric the goal names. For native MTP that is output tokens/s, acceptance, TTFT and token parity against ordinary CB at the same row count (SPEC-048 R015 cells). Use existing tools and report the number in the first Studio window. Only then write code, tooling or audits.
    • Never decide a campaign on a side metric. A kernel variant, one forward pass or a profiler sample is not the goal metric.
    • A kill or continue decision cites the goal metric, measured end-to-end.
    • A new tooling PR must name the blocked live step it unblocks. "Nicer harness" is not a reason.
    • Audits run once at freeze, not per slice.
    • Why: #2086 spent 1.5 days on harness rework, five tooling PRs and a shared-load kernel experiment, then closed on a 1.58% kernel-variant slowdown. The decisive multi-row native-versus-ordinary throughput measurement was never run.
13. No standalone tooling PRs. Tooling lives in the campaign PR. Harness, profiler, ops-script and acceptance-tool changes go in the one campaign PR they serve (rule 4), never in a PR of their own. A fix to earlier tooling goes in the same campaign PR, never in a follow-up PR.
    • The only exception: a merged ops entry point is genuinely required to run a live step (rule 8), and the campaign cannot proceed without it. Then use one small PR, linked from the campaign PR. At most one such PR per campaign.
    • Lab measurement runs from the campaign branch with existing guarded windows. It needs no merged tooling.
    • A campaign's PR count is the campaign PR plus at most one ops PR. A third PR means stop and write the operator a one-paragraph blocker (rule 6).
    • An issue closes when its implementation is merged and its live step is recorded in the release doc (rule 1). Merged tooling, merged harness or a measurement note alone does not close it. Do not close an issue as a "handoff" or as "deferred".
    • Why: between 2026-10-20 and 2026-10-22, about 12 tooling PRs, several of them fixes to earlier tooling PRs (#2090–#2094, #2097, #2101–#2105), produced no new live capability. #2081 was closed as a "handoff" with nothing released, and #2082 sat merged but not live.