@webpresso/plugin-antigravity 0.0.0-stage → 0.0.17

package/skills/tooling-friction/SKILL.md

@@ -0,0 +1,234 @@
+---
+type: skill
+slug: tooling-friction
+title: Tooling Friction
+status: active
+scope: repo
+applies_to: [agents]
+related: [verify, ultragoal, tech-debt, devex-review, land-policy]
+created: "2026-08-03"
+last_reviewed: "2026-08-11"
+name: tooling-friction
+description: "After land, capture MCP/CLI friction tips (optional; never blocks.)"
+argument-hint: "[--promote] [blueprint-slug|pr-number|session]"
+---
+
+# Tooling Friction
+
+Optional post-land **product signal** for MCP/CLI/hooks/CI pain so Webpresso tooling can improve. Not a land gate. Not a full session debrief.
+
+## Boundary
+
+| Owns                                                                                                                        | Does not own                                       |
+| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Structured friction tips after land-ish success                                                                             | Code bugs (`/investigate` → `/fix`)                |
+| Optional promote to a blueprint task or draft blueprint (tech-debt only where `committed-state-paths` permits `tech-debt/`) | Blueprint claim corrections (`blueprints/errata/`) |
+| Repo-scoped desktop-state JSON (outside worktrees)                                                                          | Human DX audits (`/devex-review`)                  |
+| Soft bookend from `/verify` Phase 7                                                                                         | Required PR section, finalize/merge blockers       |
+
+## When
+
+- After `/verify` Phase 7 (esp. green or `--merge-ready`) **and** medium+ tooling waste is already recalled
+- Explicit `/tooling-friction` or user asks for tooling papercuts / agent tax feedback
+- Blueprint completed or PR merged **and** gates burned meaningful tokens
+
+## When not
+
+- Work still in-flight (stay in fix/verify)
+- Smooth session with no tooling pain → **silence** (do not invent tips)
+- Product-code root cause unknown → investigate first
+- One-off transient network blips without a product fix
+
+## Workflow
+
+1. **Recall only** — do not re-ingest full CI logs or transcripts.
+2. If zero medium+ findings → stop: `skipped: no tooling friction`.
+3. Emit **1–3** findings (hard cap 8 for schema headroom; prefer ≤3).
+4. Write the capture with the validating verb — it is the only writer, and it
+   puts the document at the central, repo-scoped desktop state surface:
+
+   First write the capture JSON to a scratch file with the host's file-write
+   tool, under the scratch directory `$TMPDIR/webpresso/scratch/` (outside every
+   worktree, per the agent scratch write policy; never the repo root, and never
+   committed). Resolve that directory to an **absolute path** yourself and use
+   the literal path below — hosts refuse a command that carries a shell
+   variable expansion. Then hand the file to the verb with `--from-file`; no
+   pipe, redirect or shell variable is involved:
+
+   ```bash
+   wp tooling-friction write --file YYYY-MM-DD-<slug|pr|session>.json --from-file <absolute-scratch-dir>/tooling-friction-capture.json
+   ```
+
+   If your `wp` predates `--from-file`, **redirect** the same file to stdin
+   instead:
+
+   ```bash
+   wp tooling-friction write --file YYYY-MM-DD-<slug|pr|session>.json < <absolute-scratch-dir>/tooling-friction-capture.json
+   ```
+
+   Do not pipe a shell variable into the verb (`printf '%s' "$CAPTURE_JSON" | …`):
+   hosts refuse the unresolvable expansion, and the fallback — writing the JSON
+   straight into the store — skips validation, which is how a capture with ten
+   schema issues reached disk. Never write the capture into the store yourself.
+
+   The verb parses the document through the shared schema helper **before** it
+   touches disk, so a capture that violates v1 is refused (non-zero exit,
+   naming every failing field path) and nothing is written. It prints the
+   absolute path it wrote, creates parent dirs, and refuses to overwrite an
+   existing capture — pick a unique session/HHMM suffix instead.
+
+   **Path SSOT (required):** that target is the same location the read-only MCP
+   resolver reports, so call the resolver and **copy the absolute path from its
+   summary text** (hosts often omit structured details), then confirm the
+   verb's printed path matches:
+
+   ```text
+   tooling_friction_path({"file":"YYYY-MM-DD-<slug|pr|session>.json"})
+   → summary: tooling-friction path: <absolute-path>
+   ```
+
+   Never write the capture to a hand-constructed path — not to a fleet folder
+   slug (`github.com-org-repo-*`), not to worktree-keyed desktop-state, not
+   under `Application Support` or `~/.webpresso`.
+
+   - `repo-key` is a **16-hex** `repoIdentityV1(git-common-dir)` segment from
+     `repoIdentityV1` under the pure preferred state root — **not** a fleet worktree folder slug such
+     as `github.com-org-repo-<hash>` under `~/.webpresso/worktrees/repos/`.
+   - Scope is always **repo** (shared by every worktree of that git common
+     dir). Never use a worktree-keyed desktop-state surface for captures.
+   - Human CLI surface: `wp tooling-friction path --file <file>` prints that
+     absolute path; `wp tooling-friction write --file <file>` writes it.
+
+   If the surface cannot be resolved or written, report
+   `tooling-friction: skipped: no state surface` and stop; never fall back to a
+   worktree or `.agent/` path.
+
+5. Optional `--promote` or severity `high`/`critical`: record the follow-up as
+   a blueprint task (MCP `blueprint_put`) or a draft blueprint
+   (`wp blueprint new`), and set `promoted_to` to that blueprint path. Do not
+   use `wp tech-debt new` here: it refuses this repository's `tech-debt/` root,
+   which `wp audit committed-state-paths` forbids adding to.
+6. Optional one-line `session_capture` pointer to the JSON path — no paste-back walls.
+
+**Rate limit:** at most **one** capture per verify bookend.
+
+## Store path (SSOT)
+
+`tooling_friction_path({"file":"<file>"})` (or the human CLI projection
+`wp tooling-friction path --file <file>`) — a read-only projection of the pure
+preferred state root (WP_STATE_ROOT or env-paths data; no writability fallback)
+plus `repoIdentityV1(git-common-dir)` under `tooling-friction/<file>`. This
+intentionally does **not** follow `getStateRoot()`'s temporary fallback when the
+preferred root is unwritable — always copy the resolver output.
+
+The MCP summary embeds the absolute path (`tooling-friction path: …`). Details
+also include `path`, `repoKey` (16-hex), `stateRoot`, `scope: "repo"`, and
+`projectRoot`. Copy the path; never invent one.
+
+**Not** a path inside `planning/`, a checkout, or
+`desktop-state/repos/github.com-…` (fleet worktree layout ≠ desktop-state key).
+
+## Schema v1
+
+```json
+{
+  "schema_version": 1,
+  "captured_at": "2026-08-03T15:00:00Z",
+  "session": {
+    "host": "claude",
+    "session_id": "optional-max-128",
+    "blueprint_slug": "optional",
+    "pr_number": 1239,
+    "branch": "optional-max-200"
+  },
+  "findings": [
+    {
+      "id": "tf-status-ci-skew",
+      "severity": "high",
+      "surface": "pr",
+      "tool": "pr_status",
+      "kind": "friction",
+      "signal": "status_ci_skew",
+      "symptom": "pr_merge blocked while GitHub CLEAN and PR Policy green.",
+      "token_waste": "high",
+      "time_waste_minutes": 25,
+      "recurrence": "session",
+      "suggested_fix": "Align land readiness evidence with PR Policy (body+trailers; git-diff subject).",
+      "evidence_refs": ["pr:1239"],
+      "promoted_to": null
+    }
+  ],
+  "notes": "optional ≤400 chars theme"
+}
+```
+
+### Closed enums
+
+| Field       | Values                                                                                                               |
+| ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| severity    | `low` `medium` `high` `critical`                                                                                     |
+| surface     | `mcp` `cli` `hook` `pr` `ci` `review-gate` `session-memory` `host` `docs`                                            |
+| kind        | `friction` `missing` `docs` `workaround` `incident`                                                                  |
+| signal      | `retry_loop` `schema_confuse` `timeout` `wrong_facade` `missing_capability` `docs_mismatch` `status_ci_skew` `other` |
+| token_waste | `none` `low` `medium` `high`                                                                                         |
+| host        | `claude` `codex` `opencode` `other`                                                                                  |
+| recurrence  | `once` `session` `chronic`                                                                                           |
+
+### Limits
+
+- findings: prefer ≤3 (schema max 8)
+- finding `id`: `tf-` followed by 4–40 lowercase letters, digits, or hyphens
+- finding `tool`: ≤80 characters
+- `symptom` / `suggested_fix`: ≤280 chars
+- `notes`: ≤400 chars
+- `evidence_refs`: ≤5 items × ≤200 chars (run ids, receipt names, `pr:N` — **not** log bodies)
+- `token_waste` bands: `none` <1k · `low` 1–5k · `medium` 5–20k · `high` >20k or multi-retry (estimate only)
+
+## Few-shot tips
+
+**Good**
+
+- `pr_merge: land readiness disagrees with GitHub CLEAN / PR Policy (status_ci_skew, high)`
+- `review_gate: re-approve after ledger-only commits; subject binding unclear (retry_loop, medium)`
+- `pr_upsert: bare Review model "Kimi" fails provider regex; needs "kimi reviewer" (schema_confuse, low)`
+
+**Bad**
+
+- Full CI log paste
+- "Tools are confusing sometimes"
+- `suggested_fix: raise the timeout` (forbidden; see no-timeout-as-fix)
+
+## Anti-patterns (iron)
+
+1. No secrets, tokens, `.env`, auth headers
+2. No full logs/transcripts
+3. **Never block land** — missing capture ≠ incomplete
+4. No inventing tips on smooth runs
+5. No timeout-as-fix suggestions
+6. No blueprint errata misuse
+7. No committing desktop-state captures
+8. No auto-open GitHub issues per tip
+9. **Never invent the capture path** — no fleet folder slugs
+   (`github.com-org-repo-*`), no worktree-keyed desktop-state, no guessing
+   under `Application Support` or `~/.webpresso`. Always call
+   `tooling_friction_path` / `wp tooling-friction path` and write to the
+   absolute path it returns
+
+## Integration
+
+- **Canonical soft bookend:** `/verify` Phase 7 — if medium+ tooling waste recalled, run once.
+- Other surfaces (ultragoal/delivery): optional cross-link only — do not multi-prompt.
+- Land policy, finalize, and merge tools must not require this skill.
+
+## Output (agent reply)
+
+```text
+tooling-friction: wrote desktop state <absolute-path-from-tooling_friction_path>
+findings: 2 (high=1, medium=1)
+promoted: none | blueprints/<lifecycle>/<slug> | tech-debt/...
+```
+
+`tech-debt/...` applies only where `wp audit committed-state-paths` permits
+that root.
+
+Or: `tooling-friction: skipped: no tooling friction`

package/skills/tph/SKILL.md

@@ -0,0 +1,35 @@
+---
+type: skill
+slug: tph
+title: TPH (Testing Philosophy Helper)
+status: active
+scope: repo
+applies_to: [agents]
+related: [testing-philosophy]
+created: "2026-06-13"
+last_reviewed: "2026-07-08"
+name: tph
+description: "/tph — testing-philosophy review: integration-first tests, real-boundary mocks, behavior-proving assertions."
+---
+
+# TPH (Testing Philosophy Helper)
+
+This is the short-name alias for the canonical `testing-philosophy` skill.
+
+Use the full testing-philosophy workflow in `../testing-philosophy/SKILL.md` before any mechanical smell scan. The `tph` name means the review workflow: integration-first tests, real-boundary mocks only, and assertions that prove behavior.
+
+After the judgment review is complete, run the repo's static smell audit as the final mechanical backstop when available:
+
+```bash
+wp audit test-smells
+```
+
+That audit is deliberately narrower than the skill. It can catch over-mocking and smell violations, but it does not replace the testing-philosophy review.
+
+Focus on:
+
+- integration-first tests over brittle implementation mocks;
+- E2E tests that go through real user/browser or HTTP boundaries;
+- weak assertions, tautologies, and over-mocking;
+- correct test naming and suite placement;
+- mutation-test-worthy coverage for new logic.

package/skills/ultragoal/SKILL.md

@@ -0,0 +1,304 @@
+---
+type: skill
+slug: ultragoal
+title: Ultragoal
+status: active
+scope: repo
+applies_to: [agents]
+related: [autopilot, plan-refine, verify, fix, opencode-go]
+created: "2026-07-10"
+last_reviewed: "2026-08-03"
+name: ultragoal
+description: "Multi-blueprint ultragoal with budgets. Use for overnight, parallel execute, sleep with stop."
+argument-hint: "<new|status|handoff|run|cancel> [brief]"
+---
+
+# Ultragoal
+
+## Use when (freeform)
+
+- "ultragoal", "overnight", "go to sleep", "full autopilot" **with** named budgets/stop
+- "spawn many in parallel", multi-blueprint ready-set execution
+- Reject unbound "complete everything while I sleep" without stop condition / budgets
+
+Use `wp ultragoal` / MCP `ultragoal_*` as the durable controller for work spanning
+one or more blueprints. Prefer this spine over host-local mega-sessions or ad-hoc
+multi-agent swarms.
+
+## Creating an ultragoal does NOT set a host stop-condition
+
+`ultragoal_new` records a durable brief, budgets, and phase. It does **not**
+install the session Stop hook that keeps a host working until a condition holds
+— that hook belongs to the host's own goal surface (Claude Code's `/goal`), which
+this skill cannot reach. The two are independent: an ultragoal can sit in `plan`
+indefinitely with no host pressure to advance it, and a host goal can be set with
+no ultragoal behind it.
+
+So do not assume invoking this skill armed a stop condition. Either:
+
+- state the stop condition explicitly in the reply and drive the loop yourself, or
+- tell the operator to pair the run with their host's goal command when they want
+  the session held open until the ultragoal completes.
+
+Recording the brief and recording the stop condition are two separate acts;
+conflating them silently drops the one the operator was counting on.
+
+## Default budgets (override only when the user sets them)
+
+| Budget          | Default                          | Meaning                                            |
+| --------------- | -------------------------------- | -------------------------------------------------- |
+| `concurrency`   | 4 (max 8)                        | Parallel ready tasks / implementer lanes           |
+| `fix_budget`    | 1                                | Pre-existing issues fixable via `/fix` this phase  |
+| `review_budget` | see `workflow-skills-routing.md` | Outside-voice reviewer paths, local vs merge-ready |
+| `loop`          | off                              | Do not run `/loop` or unbounded stop-hooks         |
+
+Reject unbudgeted sleep-mode briefs (“complete all”, “full autopilot”, “go to sleep”)
+unless they name a blueprint/slug, budgets, and a stop condition. Route vague briefs
+through `plan-refine` first (or require `force:` only when the user explicitly opts out).
+
+## Executor preflight
+
+`wp ultragoal start` validates every requested host before it persists a durable run or
+permits supervisor worktree allocation. Built-in hosts validate both the executable and the
+CLI grammar Ultragoal invokes; the generic `process` host validates executable availability
+only. An incompatible wrapper fails with `UG_HOST_UNAVAILABLE`, the configured invocation
+path, the missing surface, and its remediation variable. Diagnostics mention the canonical
+target as secondary context only when the invocation path is a symlink.
+
+| Host     | Override variable               |
+| -------- | ------------------------------- |
+| Claude   | `WP_ULTRAGOAL_CLAUDE_COMMAND`   |
+| Codex    | `WP_ULTRAGOAL_CODEX_COMMAND`    |
+| OpenCode | `WP_ULTRAGOAL_OPENCODE_COMMAND` |
+| Process  | `WP_ULTRAGOAL_PROCESS_COMMAND`  |
+
+Upgrade the installed CLI or point the named variable at a compatible executable. Then
+restart the process that owns the adapter: probe successes and failures are cached by
+canonical executable for that adapter's lifetime. Missing paths are rechecked and symlink
+retargeting is re-probed, but an in-place executable repair still requires an adapter-owner
+restart.
+
+Existing `WP_ULTRAGOAL_<HOST>_COMMAND` configurations remain supported; no environment
+variable migration is required. Their executables must satisfy the current semantic probe
+and invocation contract after an upgrade. The generic process host is additive: integrations
+that opt into it configure `WP_ULTRAGOAL_PROCESS_COMMAND` and, when needed, the JSON argument
+array described below.
+
+Start probes each unique requested host concurrently, then reports the first failure in
+requested-host order. A failed preflight occurs before durable run creation, ledger writes,
+supervisor launch, or attempt/worktree allocation. Built-in probes validate the grammar they
+invoke: Codex `exec --json --sandbox workspace-write`, Claude prompt/streaming output/bypass
+permission flags, and OpenCode `run --format json --auto`.
+
+Preflight does **not** validate authentication, provider quota or billing, network
+reachability, or secrets isolation. Those failures remain runtime/provider concerns.
+
+### Host normalization and recovery
+
+Ultragoal trims and normalizes the default host and per-task `taskHosts` values once when it
+resolves the plan, then persists that normalized mapping. Task IDs are never normalized: a
+per-task entry must use the exact executable task ID. Blank host values, missing task IDs,
+and overrides for controller-only tasks fail with `UG_HOST_CONFIG_INVALID`; an unrecognized
+normalized host fails with `UG_HOST_UNKNOWN`.
+
+An initial host failure still occurs before owner-head lookup, durable run or ledger creation,
+supervisor launch, and worktree allocation. Once a run already exists, the supervisor fills
+only the ready executable tasks that fit the currently free concurrency slots. If one host is
+unavailable, available siblings in that ready slice start and are durably attached to the run;
+the unavailable task gets no attempt or worktree. The supervisor then records its exit and
+reports the first host failure in task order. The `supervisor-exited` record leaves the run
+nonterminal and the attached handles/worktrees recoverable.
+
+After upgrading or overriding the unavailable host, adopt the run. Adoption creates a fresh
+host registry and probe cache, recovers the already attached work, and schedules the task that
+could not start. Do not convert a cached availability failure into a retry attempt or mark an
+otherwise recoverable run terminal.
+
+### Generic process contract
+
+Set `WP_ULTRAGOAL_PROCESS_COMMAND` to an executable. Optional
+`WP_ULTRAGOAL_PROCESS_ARGS_JSON` must be a JSON array of string arguments. Ultragoal appends
+these fixed arguments after the configured arguments; process integrations must accept them:
+
+```text
+--task <task.json> --events <events.jsonl> --responses <responses.jsonl>
+```
+
+The same absolute paths are available as `UG_TASK_PATH`, `UG_EVENTS_PATH`, and
+`UG_RESPONSES_PATH`; `UG_ATTEMPT_ID` and `UG_WORKTREE` identify the attempt and its working
+tree. The executable runs with that worktree as its current directory. It writes one JSON
+object per line to the events file using one of these shapes:
+
+```json
+{"type":"attention","attentionId":"question-1","prompt":"Proceed?"}
+{"type":"response-ack","attentionId":"question-1"}
+{"type":"completed"}
+{"type":"failed","reason":"optional explanation"}
+```
+
+Ultragoal appends responses as JSONL objects with `type: "response"`, the matching
+`attentionId`, `response`, and `createdAt`. The process must emit `response-ack` with that
+identifier after consuming a response. The protocol paths and `UG_*` variables are fixed;
+the configured JSON arguments may add process-specific flags but cannot replace them.
+
+### Execution authority and isolation
+
+Ultragoal worktrees protect git integration boundaries; they are **not** operating-system
+sandboxes. Codex uses its `workspace-write` sandbox; Claude `bypassPermissions`, OpenCode `--auto` mode, and custom
+`process` executables retain substantial user authority. OpenCode disables automatic updates
+and sharing and denies external-directory access, but those policy settings do not make it an
+OS sandbox. Run Ultragoal only with providers, configuration, and task content you trust.
+
+## Tooling map (use these; do not reimplement with Bash)
+
+| Phase                  | Prefer MCP / CLI                                                           | Purpose                                             |
+| ---------------------- | -------------------------------------------------------------------------- | --------------------------------------------------- |
+| Create / resume        | `ultragoal_new`, `ultragoal_status`                                        | Durable controller state                            |
+| Isolation              | `worktree`                                                                 | Owner / lane worktrees; never primary as controller |
+| Blueprint read         | `blueprint_list`, `blueprint_get`, `blueprint_context`                     | Ready-set and deps                                  |
+| Blueprint write        | `blueprint_put`, `blueprint_transition`                                    | Spec edits (MCP-only for blueprints)                |
+| Task done              | `blueprint_task_verify` only                                               | Evidence-gated completion                           |
+| Parallel execute       | `/goal` (autopilot) or ready-queue + host subagents                        | Max parallel when deps allow                        |
+| Context-light delegate | `session_context`                                                          | Manifest for subagents (no history paste)           |
+| Continuity             | `session_capture`, `session_search`, `session_restore`, `session_snapshot` | Decisions / resume                                  |
+| Large command / file   | `session_execute`, `session_batch_execute`, `session_execute_file`         | Bounded output + index                              |
+| QA                     | `qa` (or `lint` + `typecheck` + `test`)                                    | Affected quality gates                              |
+| PR / land              | `pr_upsert`, `pr_status`, `pr_wait`, `pr_merge`                            | Open early; exact-head merge only                   |
+| Delivery programs      | `delivery_status`                                                          | Derive one dispatch/integration action              |
+| Fleet / workers        | `fleet_status`, `worker_tail`                                              | Multi-session visibility                            |
+| Token gain             | `gain`                                                                     | Optional efficiency check after heavy execute       |
+| Advance loop           | `ultragoal_run`, `ultragoal_handoff`, `ultragoal_cancel`                   | Controller steps only                               |
+
+Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer `wp` >
+`vp` > raw package managers. Never raise timeouts to hide hangs.
+
+## Protocol
+
+1. Create or resume the ultragoal in a **managed blueprint owner worktree**
+   (`worktree` / `blueprint_put`). Never use `main` or the primary checkout
+   as controller.
+2. Print the **ready-set**: tasks whose dependencies are satisfied (from blueprint tools).
+3. Launch up to `concurrency` independent ready tasks in parallel (worktree-isolated).
+   Serialize only when file ownership overlaps or deps require it.
+4. Execute only the current phase handoff; call `ultragoal_run` again after evidence.
+5. Mark tasks done **only** via `blueprint_task_verify` with passing evidence.
+6. **Opportunistic `/fix`:** at most `fix_budget` pre-existing issues per phase, each with
+   named invariant + failing proof. Excess → handoff backlog (do not expand epic).
+7. **Validate / land:** local proof with `qa` / targeted tools; outside review only when
+   merge-ready and within `review_budget` — **exactly one sequential** outside voice unless
+   the user sets N (the default value lives in `workflow-skills-routing.md`).
+   Controller validation evidence is **machine-qa (prior QA phase) + N outside voices**
+   (default N=1), not two outside model reviewers at budget 1.
+   `review_gate` has one mode: purpose plan for exact-version draft plan
+   approval (then `blueprint_promote`), purpose delivery for implementation/phase outside
+   voice. Each new provider verdict is a formal round of the slug's budget and
+   an approval is authority immediately. A CLI delivery gate is explicit MCP-unavailable
+   compatibility only, not this MCP contract. Use `pr_*` for PR babysit — no
+   multi-sleep poll loops; no parallel multi-reviewer stampede.
+8. Stop on `complete`, `cancelled`, blocked guard exhaustion, or `WP_ULTRAGOAL_DISABLE=1`.
+
+The blueprint engine owns task status and approval gates. The ultragoal controller must
+never self-approve, directly mark a task done, bypass review provenance, or mutate the
+primary checkout.
+
+## Failure / cascade
+
+- Hard fail on a task → mark blocked with reason; **cascade-skip** dependents that cannot
+  proceed; continue independent ready work.
+- Lifecycle mutation failure → stop (do not continue on stale plan state).
+- On block: call `ultragoal_handoff` and emit a **≤40-line handoff**: goal, done, blockers,
+  evidence refs (`session_*` ids if any), next 3 commands. Do not paste full transcripts.
+
+## Outside-voice review (required for autopilot)
+
+Autopilot and agent-driven ultragoal loops **must** request an outside-voice review after each **goal/phase milestone**. Use **`review_gate`** purpose plan for exact-version draft plan approval (then promote with `blueprint_promote`) and one single-shot **`review_gate`** purpose delivery call for implementation/phase outside voice. The gate has one mode: each newly executed provider review that reaches a verdict is a formal round of the slug's budget, an approval is authority immediately, and an identical-subject call replays the recorded verdict without a new round. CLI delivery gates are explicit MCP-unavailable compatibility only, not this MCP contract.
+
+Count each milestone review against `review_budget` for merge-ready claims: **exactly one sequential** reviewer path unless the user sets N; the default value is owned by `workflow-skills-routing.md`. Do not fan out multi-host review swarms.
+
+### Milestones that require a review
+
+Run `review_gate` purpose plan for the plan approval milestone below and one
+single-shot `review_gate` purpose delivery call for implementation/phase
+milestones. Each new provider verdict is one formal round of the slug's budget.
+
+| Milestone          | When                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Plan gate          | Before `draft` → `planned`, using the exact version returned by `blueprint_put`; then `blueprint_promote` the approved version   |
+| Phase advance      | After ultragoal advances `plan` → `execute`, `execute` → `qa`, `qa` → `validate`, `validate` → `land`, or lands `complete`       |
+| Task batch handoff | After a meaningful execute batch when the phase remains `execute` (at least once per blueprint before claiming execute-complete) |
+
+Do **not** invent ledger approvals. If the review provider is unavailable or hits a provider-wide usage limit, capture the failure evidence and end outside review for the window; do not hop reviewer families, substitute another host, or substitute a forged approval.
+
+### Reviewer selection (the gate chooses, not the caller)
+
+Pass `caller_model` with your own model id and omit `provider`, `model`, and
+`effort`. The gate selects the reviewer route itself — a cross-family reviewer
+chosen for capability, current provider limits, and measured daily cost — and
+reports the choice in `policy_selection`. Never resolve models from a live
+catalog at invocation time, never probe a provider CLI for its model list, and
+never read a credential store to discover models; provider catalog discovery
+belongs to the snapshot drift workflow. A human operator may still name an
+explicit `provider`/`model` as an override; agents must not.
+
+Treat a provider-wide usage limit as terminal for the current review window; do not hop reviewer families to evade a usage block. There is no substitute host: the window ends with the captured failure evidence.
+
+### Plan gate invocation shape
+
+```text
+review_gate({
+  "project_id": "<project-id>",
+  "slug": "<blueprint-slug>",
+  "expected_version": "bpv1:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "repository_access": "read-only",
+  "auto_promote": true,
+  "caller_model": "<your own model id>"
+})
+```
+
+The plan gate has no `purpose` or `target` field. Pass the exact `bpv1:` token
+returned by `blueprint_put`, never a commit hash or `HEAD`. An explicitly
+requested CLI delivery gate is an MCP-unavailable compatibility fallback only.
+If the MCP host returns before a terminal result, poll the same invocation with
+`review_gate_wait`; treat in-progress, not-found, contention, waiter timeout,
+waiter abort, and cancellation as non-verdict observation states. `not_found`
+means no active or terminal gate exists for that subject; refresh state and
+start the gate again instead of spinning a wait loop.
+
+### Honesty rules (non-negotiable)
+
+- Never self-approve or hand-edit `reviews.md` / `review-events.jsonl` / frontmatter approvals to fake outside-review authority.
+- Never mark blueprint tasks done except through `blueprint_task_verify` with real evidence.
+- Never run ultragoal mutations on `main` or a primary checkout; use the managed blueprint owner worktree.
+- Keep every loop bounded and never increase timeouts.
+- When the controller returns `waiting` (`blueprint-promotion`, `approval-gate`, `blueprint-tasks`, …), fix the named gap; do not spin `wp ultragoal run` without progress.
+
+## Tooling-aligned evidence (QA / land)
+
+- **QA phase** prefers **GitHub required checks** for the worktree PR (`pr_status` /
+  `pr_wait` or `gh pr checks --required`) when PR is `OPEN`/`MERGED`, checks green, and
+  PR head matches clean worktree HEAD.
+- If no PR-bound green CI is available, fall back to local **`qa`**.
+- Open a PR early so CI can satisfy QA. Do **not** raise timeouts.
+- **Land** still requires a **MERGED** PR with green required checks bound to the projected
+  source snapshot. Use `/verify --merge-ready` (merge-ready `review_budget`, per
+  `workflow-skills-routing.md`), not default local verify.
+
+## Snapshot / dirty worktree
+
+- **Never edit primary.** Ultragoal and locked blueprint mutations refuse
+  primary-like checkouts; planning SSOT lives only in managed owner worktrees.
+- On a **linked managed worktree**, uncommitted `blueprints/**` dirt (review
+  ledgers, `_overview.md` lifecycle, promote/finalize renames) is
+  controller-owned and must not fail `createCleanSourceSnapshot` / block
+  `wp ultragoal run` after task_verify or promotion.
+- On a **primary-like checkout**, only review ledgers/artifacts are ignored;
+  dirty `_overview.md` still fails closed so primary never silently absorbs
+  planning pollution. Product source outside blueprints always fails closed.
+- Committed blueprint documents still participate in the HEAD source snapshot
+  hash (QA/land identity). Commit blueprint + product changes when claiming
+  merge-ready.
+
+## After land (optional)
+
+If MCP/CLI/hooks/CI gates burned medium+ tokens this program, consider
+`/tooling-friction` once. Never required for land complete.