@webpresso/agent-kit 3.1.26 → 3.1.30

package/catalog/AGENTS.md.tpl

@@ -54,6 +54,8 @@ Catalog-owned surfaces:
 - Reuse nearby utilities and patterns before adding new abstractions.
 - Apply DRY, SOLID, YAGNI, and KISS.
 - No hardcoded relative paths in executable code or config; derive from an explicit absolute anchor.
+- Efficiency: MCP `wp_*` over shell; `ultragoal`/`/pll`; `/verify` local vs
+  `--merge-ready` (1 outside voice); `fix_budget`=1.
 
 Hook invariant: global hooks use the canonical contract; skill hooks never
 project into host settings. Bound hot paths; do not raise timeouts or hide work
@@ -61,17 +63,10 @@ asynchronously.
 
 ## Verify
 
-Before claiming completion, run the narrowest checks that prove the change:
-
-- agent-kit MCP tools first when available; otherwise the repo wrapper
-- typecheck
-- lint / format check
-- affected tests
-- repo policy checks such as `verify:paths` / `verify:secrets`
-- docs or blueprint validation when docs/plans changed
-- `wp sync --check` after template/catalog changes
-
-If a gate fails, fix root cause or record the blocker with evidence.
+Before claiming completion, run the narrowest MCP/`wp` checks that prove the
+change: typecheck, lint/format, affected tests, policy, docs/blueprint, and
+`wp sync --check` after template/catalog changes. Fix root cause or record the
+blocker. Before pushing, run `wp ci-preflight` (see `ci-cost-local-first`).
 
 ## Communicate
 
@@ -149,6 +144,7 @@ Full details: `.agent/rules/package-conventions.md`
 ## Tech stack
 
 {{TECH_STACK}}
+
 <!-- <<< managed by webpresso (planning-and-release) -->
 
 <!-- >>> user-owned (escalation-map) -->

package/catalog/agent/commands/verify.md

@@ -1,6 +1,6 @@
 ---
-description: "Post-implementation quality gate that verifies work is actually done, runs the folded TPH/test-quality audit, cleans up legacy/backward-compat/dead-code garbage left behind, refreshes affected docs, and requires outside-model approval evidence before merge-ready claims. Use after implementing a feature or fix, before claiming done, or when finalizing a blueprint."
-argument-hint: "<target> [--full] where target is: package|file|plan-slug|all"
+description: "Post-implementation quality gate: local checks by default; --merge-ready requires exactly one outside-voice approval. Runs TPH/test-quality audit, dead-code sweep, and docs refresh. Use after implementing a feature or fix, before claiming done, or when finalizing a blueprint."
+argument-hint: "<target> [--full|--merge-ready] where target is: package|file|plan-slug|all"
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite
 ---
 

package/catalog/agent/rules/changeset-release.md

@@ -180,8 +180,10 @@ for the current repository and package configuration contract.
    `npm view <package> version`. For consumer setup smoke, use
    `vp install -g @webpresso/agent-kit@latest`, `wp setup`, and
    `wp sync --check`.
-6. If the Version Packages PR has no WP check / CI is `action_required` with
-   zero jobs, follow
+6. Version Packages PRs are authored via the **webpresso-dev** App installation
+   token in `release.yml` (not bare `GITHUB_TOKEN`). If a PR still has no WP
+   check / CI is `action_required` with zero jobs (legacy bot author or App
+   mint failure), follow
    [`docs/runbooks/version-packages-bot-ci.md`](../../../docs/runbooks/version-packages-bot-ci.md)
    (`gh run rerun` or Approve workflows). Do not admin-merge without WP check.
 7. After the OIDC publish path succeeds, set npm package publishing access to

package/catalog/agent/rules/ci-cost-local-first.md

@@ -0,0 +1,139 @@
+---
+type: rule
+slug: ci-cost-local-first
+title: CI cost and local-first gates
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - cmd-execution
+  - ci-test-perf
+  - pre-implementation
+  - hook-hot-path
+  - no-timeout-as-fix
+created: "2026-07-21"
+last_reviewed: "2026-07-21"
+paths:
+  - ".github/workflows/**"
+  - "catalog/agent/**"
+  - "AGENTS.md"
+  - ".husky/**"
+---
+
+# CI cost and local-first gates
+
+Agents waste money when they treat remote CI as the primary debugger.
+**Catch failures locally first.** Remote CI is confirmation, not exploration.
+
+Monthly spend on private repos (Ubicloud + GitHub-hosted minutes + artifact
+storage) is a product constraint. Prefer cheap local loops over burning full
+PR matrices to discover format/lint/type/test/governance failures.
+
+## Iron law
+
+1. **Never open or update a PR you already know will fail** a locally-runnable
+   gate (format, guardrails, typecheck, lint, affected tests, PR body contract,
+   changeset/blueprint trailers when applicable).
+2. **Never use `git push --no-verify` / `HUSKY=0` / skip hooks** to “save
+   time.” That only moves the failure to paid CI and trains a red-loop habit.
+3. **Never re-run a failed CI job “to see if it flaked”** until you have a
+   local reproduction or a concrete flake hypothesis with evidence.
+4. **Never add GitHub-hosted runners** (`ubuntu-latest`, `macos-*`,
+   `windows-*`) on private-repo workflows except the **Release / npm OIDC
+   publish** path (and release-native targets that truly need that OS). Default
+   is **Ubicloud** (`ubicloud-standard-2` / `-4` only when justified).
+
+## Local gate stack (must pass before push)
+
+| When                       | Command / check                                                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Every commit               | Managed pre-commit (format + staged guardrails)                                                                                  |
+| Every push                 | `wp ci-preflight` before pushing; in agent-kit itself this is also enforced by `.husky/pre-push`                                 |
+| Before PR open / body edit | PR template fields filled; trailers exact (`Blueprint-exempt`, `Changeset-exempt`, `Review-skip` as **start-of-line** when used) |
+| Before claim merge-ready   | `/verify <target>` then `/verify <target> --merge-ready` when landing                                                            |
+
+`wp ci-preflight` is fail-fast and **branch-scoped**:
+
+1. `wp format --affected --branch --check`
+2. `wp audit guardrails --affected --branch`
+3. `wp typecheck --affected --branch`
+4. `wp lint --affected --branch`
+5. `wp test --affected --branch`
+
+If preflight fails: **fix locally**, do not push. Reproduce with the printed
+`wp …` line.
+
+### Bootstrap before preflight
+
+Missing `node_modules` in a worktree → run `wp install` (or the repo’s setup),
+then preflight. Use `vp install` only when `wp` has no equivalent. Do not push a
+bare worktree “to let CI install.”
+
+## Cost model (private repos)
+
+| Resource                       | Cost driver                                       | Agent duty                                     |
+| ------------------------------ | ------------------------------------------------- | ---------------------------------------------- |
+| Ubicloud minutes               | Every PR job matrix (lint, tests, smokes, shards) | Local preflight; avoid drive-by full re-runs   |
+| GitHub-hosted `ubuntu-latest`  | Billable Actions minutes                          | Only release/OIDC publish unless proven needed |
+| GitHub `macos-*` / `windows-*` | ~10× Linux minutes                                | Release natives only; never default PR CI      |
+| Actions artifacts / caches     | Storage quota; can block Release uploads          | Prefer short retention; do not spam artifacts  |
+| Failed CI loops                | Full matrix × attempts                            | Fix from logs locally before `gh run rerun`    |
+
+Related: `ci-test-perf.md` (keep coverage; speed via workers/cache/shards — not
+by skipping tests). Prefer **fewer/cheaper runners + sharding** over raising
+timeouts (`no-timeout-as-fix.md`).
+
+## Workflow authoring (when you touch CI)
+
+- Private non-release jobs: `runs-on: ubicloud-standard-2` by default.
+- Use `ubicloud-standard-4` only when wall-time evidence shows standard-2 is
+  insufficient **with** full coverage and workers (document why).
+- Release publish job may use `ubuntu-latest` for npm trusted publishing /
+  provenance. Session-memory / platform native matrices that require Darwin or
+  Windows may use GH-hosted OS runners **only on the Release (publish=true)
+  path**, never on ordinary PR CI.
+- Path filters, `concurrency` cancel-in-progress, and change-scope skips are
+  preferred over always-on heavy jobs.
+- Do not add nightly/macOS “perf” jobs that run on every PR; keep them opt-in
+  (`workflow_dispatch`, label, or schedule) and prefer Ubicloud for any check
+  that is not Apple-signing/display-bound.
+
+## PR governance without burning CI
+
+These fail **before** expensive tests if you get them wrong — fix **before**
+push/open:
+
+- PR description AI/model disclosure + `Session id` (or `Session-skip`)
+- `Review-skip: SKIP <reason>` must match `^Review-skip:` at **line start**
+  (not nested under a bullet)
+- `Blueprint-exempt:` / `Changeset-exempt:` in **commit message** and/or body
+  when required (blueprint-pr-coverage reads **git trailers**, not only the PR body)
+- Version Packages / bot CI: do not invent admin-merge; use the runbook
+  (`docs/runbooks/version-packages-bot-ci.md` when present)
+
+## Forbidden agent habits
+
+- Push → watch red CI → tweak → push again (the “CI as unit test” loop)
+- Broaden CI timeouts / disable flakes instead of root-cause fix
+- Schedule or matrix-expand macOS/Windows for convenience
+- Upload large artifacts every PR “for debugging”
+- Claim “CI is green” from a partial check while WP check / required jobs pending
+- Force-push past hooks to land red work for “later fix”
+
+## Good loop
+
+```text
+edit → scoped lint/type/test → commit (hooks) → wp ci-preflight → push
+→ open PR with complete body → watch CI once → fix root cause locally if red
+```
+
+When CI fails: download/read the failed job log, reproduce with the matching
+local `wp` command, fix, preflight, push **one** corrective commit.
+
+## Related
+
+- `cmd-execution.md` — bookend QA; scoped commands in the middle
+- `ci-test-perf.md` — parallelism and install cache
+- `pre-implementation.md` — blueprint gates that only fail in CI if left open
+- `hook-hot-path.md` — pre-push stays local and non-network
+- CLI: `wp ci-preflight` (pre-push owner)

package/catalog/agent/rules/ci-test-perf.md

@@ -56,9 +56,13 @@ Mutation/Stryker jobs are auto-exempt when the step/job name or nearby lines men
 When a single job still exceeds budget **with full coverage**:
 
 1. Prefer **Vitest sharding** (`vitest run --shard=i/n` + blob reporter merge) over raising isolation-off globally.
-2. Prefer a **larger runner** (`ubicloud-standard-4`, etc.) + more `VITEST_MAX_WORKERS` over dropping suites.
+2. Prefer a **larger runner** (`ubicloud-standard-4`, etc.) + more `VITEST_MAX_WORKERS` over dropping suites — only after `ubicloud-standard-2` is proven insufficient. Do not jump to GitHub-hosted macOS/Windows for ordinary test jobs.
 3. Cache **native/build artifacts** when warm steps rebuild every PR (producer-specific).
 
+Private-repo default is **Ubicloud** for non-release jobs. GitHub-hosted
+runners are reserved for Release/OIDC publish (and release-native OS builds).
+See `ci-cost-local-first.md`.
+
 ## Related
 
 - Vitest performance: https://vitest.dev/guide/improving-performance

package/catalog/agent/rules/cmd-execution.md

@@ -14,6 +14,15 @@ paths:
 
 # Command Execution Rules
 
+## Local-first before remote CI
+
+Paid CI (Ubicloud + GitHub-hosted) is for confirmation. Use scoped commands
+while iterating, then **`wp ci-preflight` before every push**. In agent-kit
+itself, `.husky/pre-push` enforces that gate; consumer templates may leave
+pre-push checks user-owned. Never `git push --no-verify` to skip a configured
+local gate. See `ci-cost-local-first.md` for runner policy and anti-red-loop
+habits.
+
 ## BOOKEND Rule: Full QA Runs Exactly Twice
 
 The full QA pipeline (e.g. `wp qa`, `bun run qa`) is a

package/catalog/agent/rules/pre-implementation.md

@@ -264,7 +264,8 @@ Doing it post-merge is also impossible without a second PR: you cannot push the
 **Local pre-push check (catches the CI failure before it costs minutes):** the
 local lifecycle audit gives a false pass here because the owner worktree resolves
 on your machine. So do not rely on it alone — before opening or updating the PR,
-confirm no changed blueprint is still under `blueprints/in-progress/`:
+run `wp ci-preflight` for ordinary quality gates and confirm no changed blueprint
+is still under `blueprints/in-progress/`:
 
 ```bash
 git diff --name-only origin/main...HEAD | grep -q '^blueprints/in-progress/' \

package/catalog/agent/rules/test-scan-perf.md

@@ -0,0 +1,80 @@
+---
+type: rule
+slug: test-scan-perf
+title: Test scan performance (no full-repo FS walks)
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - testing-philosophy
+  - ci-test-perf
+created: "2026-07-20"
+last_reviewed: "2026-07-20"
+paths:
+  - "**/*.{test,spec}.{ts,tsx,js,jsx}"
+  - "src/audit/test-scan-perf.ts"
+---
+
+# Test scan performance
+
+Unit and contract tests must not walk the whole repository with
+`readdirSync` / `statSync` / `readFileSync` and paper over the cost with a
+30s+ per-test timeout.
+
+## Forbidden pattern
+
+```ts
+const repoRoot = findRepoRoot();
+const walk = (dir: string) => {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      walk(full);
+      continue;
+    }
+    const text = readFileSync(full, "utf8");
+    // ...
+  }
+};
+walk(repoRoot);
+
+it("scan", () => {
+  /* ... */
+}, 30_000); // band-aid
+```
+
+## Preferred
+
+```ts
+// Tracked files only — seconds, not tens of seconds.
+const stdout = execFileSync(
+  "git",
+  ["-C", root, "grep", "-l", "-I", "-E", "RETIRED_SPECIFIER_A|RETIRED_SPECIFIER_B"],
+  { encoding: "utf8" },
+);
+```
+
+Or walk a **bounded** fixture / package tree (not `findRepoRoot()` / `process.cwd()`).
+
+## Guardrail
+
+| Surface    | Contract                           |
+| ---------- | ---------------------------------- |
+| Audit      | `wp audit test-scan-perf`          |
+| Guardrails | included in `wp audit guardrails`  |
+| Scope      | affected-safe (changed test files) |
+
+### Opt-out
+
+```ts
+// test-scan-perf-allow — one-off inventory with justification
+walk(repoRoot);
+
+// or once per file:
+// test-scan-perf-allow-file — full inventory intentionally walks the tree
+```
+
+## Related
+
+- Implementation: `src/audit/test-scan-perf.ts`
+- CI workers/cache: `ci-test-perf` (workflow-level, separate concern)

package/catalog/agent/rules/workflow-skills-routing.md

@@ -73,7 +73,12 @@ Map routing intent like this:
   `deep-research`
 - debugging and regressions → `investigate` then `fix`
 - bounded cleanup after behavior is green → `ai-deslop`
-
-Use `wp_*` tools for tests, lint, typecheck, audits, blueprint execution, and
-quality gates. Use the curated review skills for plan critique, outside voice,
-and pre-landing review when explicitly requested or clearly useful.
+- multi-task / parallel execute → `ultragoal` + `/pll` (ready-queue, worktrees)
+- local completeness → `/verify` then `wp ci-preflight` before push; merge-ready
+  outside voice → `/verify --merge-ready` (exactly one sequential outside
+  reviewer unless user sets N). Do not use remote CI as the first debugger
+  (`ci-cost-local-first`).
+
+Use the full `wp_*` MCP surface for tests, lint, typecheck, audits, session memory,
+ultragoal, worktrees, PRs, and quality gates — not shell reimplementations. Use
+curated outside-voice skills only within `review_budget` (default 0 local / 1 merge-ready).

package/catalog/agent/skills/autopilot/SKILL.md

@@ -5,9 +5,9 @@ title: Autopilot
 status: active
 scope: repo
 applies_to: [agents]
-related: [goal, plan-refine, verify, testing-philosophy]
+related: [goal, plan-refine, verify, testing-philosophy, ultragoal, pll, fix]
 created: "2026-07-10"
-last_reviewed: "2026-07-10"
+last_reviewed: "2026-07-21"
 name: autopilot
 description: "Drive a brief through the bounded native goal pipeline."
 argument-hint: "<brief|force: brief>"
@@ -15,25 +15,62 @@ argument-hint: "<brief|force: brief>"
 
 # Autopilot
 
-Drive an approved brief through `plan -> execute -> qa -> validate -> land -> complete` using `wp ultragoal run` and the current handoff.
+Drive an approved brief through `plan -> execute -> qa -> validate -> land -> complete`
+using `wp_ultragoal_run` / `wp ultragoal run` and the current handoff.
+
+## Outside-voice (required)
+
+After each ultragoal **phase or plan-gate milestone**, run an **OpenCode Go** outside-voice review and pick the model by purpose (plan critique → DeepSeek Pro; coding quality → Kimi Code first; cheap recheck → DeepSeek Flash). Resolve IDs from live `opencode models opencode-go`. Lifecycle authority only via converged `wp review gate` — never self-approve. Full protocol: the `ultragoal` skill. Respect `review_budget` (default one sequential path; no multi-host stampede).
 
 ## Vague gate
 
-A brief is anchored when it includes a file path, symbol, issue number, test name, or numbered steps. Route any unanchored brief through `plan-refine` before execution. A leading `force:` is the only explicit bypass; strip it before creating the goal and record the bypass in the blueprint.
+A brief is anchored when it includes a file path, symbol, issue number, test name, or numbered steps
+(blueprint slug and explicit budgets also count). Route any unanchored brief through
+`plan-refine` before execution.
+
+**Reject** (unless rewritten with scope + budgets): “complete all”, “full autopilot”,
+“go to sleep”, “elegantly merge everything” without a named blueprint/PR set.
+
+A leading `force:` is the only explicit bypass; strip it before creating the goal and
+record the bypass in the blueprint.
+
+Default budgets if the user omits them: `concurrency=4`, `fix_budget=1`,
+`review_budget=1`, no `/loop`. See `ultragoal` skill.
+
+## Tooling map
+
+| Pipeline step        | Tools                                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Plan                 | `plan-refine`, `wp_blueprint_*`, `wp_session_capture` for decisions                                                                                |
+| Create controller    | `wp_ultragoal_new`, `wp_worktree`                                                                                                                  |
+| Execute              | ready-set via blueprint tools; `/pll` or parallel subagents; `wp_session_context` for delegates; `wp_blueprint_task_verify` only to complete tasks |
+| Opportunistic repair | `/fix` up to `fix_budget`; else handoff backlog                                                                                                    |
+| QA                   | `wp_qa` / `wp_lint` / `wp_typecheck` / `wp_test`; PR checks via `wp_pr_status` / `wp_pr_wait`                                                      |
+| Validate             | one outside voice if merge-bound (OpenCode Go by purpose, or claude/codex/grok); `wp review gate` for authority                                    |
+| Land                 | `wp_pr_upsert`, green required checks, merge + owner cleanup                                                                                       |
+| Blocked / stop       | `wp_ultragoal_handoff` ≤40 lines; `wp_ultragoal_cancel` if abandoned                                                                               |
 
 ## Pipeline
 
-1. Plan: refine blueprints and satisfy provenance-backed promotion approvals.
-2. Execute: implement current ready tasks; use only `wp_blueprint_task_verify` to mark them done.
-3. QA: run affected checks and `wp qa`; preserve normalized failure evidence.
-4. Validate: obtain distinct verification and code-review evidence and resolve findings. Each lane appends a tracked `reviews.md` record in one of these exact forms:
+1. **Plan:** refine blueprints and satisfy provenance-backed promotion approvals.
+2. **Execute:** implement current **ready** tasks in parallel up to `concurrency`; use only
+   `wp_blueprint_task_verify` to mark them done.
+3. **QA:** run affected checks and `wp_qa`; preserve normalized failure evidence. Prefer
+   PR-bound CI when a PR exists.
+4. **Validate:** obtain verification + code-review evidence within `review_budget`. Each
+   lane appends a tracked `reviews.md` record in one of these exact forms:
 
    ```text
    <!-- wp:goal-validation {"kind":"verify","reviewer":"<identity>","artifact":"<tracked-path>"} -->
    <!-- wp:goal-validation {"kind":"code-review","reviewer":"<different-identity>","artifact":"<tracked-path>"} -->
    ```
 
-5. Land: require green PR checks, complete the blueprint in the same PR, merge, and run owner cleanup.
-6. Complete: stop only when `wp ultragoal run` records terminal evidence.
+5. **Land:** require green PR checks, complete the blueprint in the same PR, merge, and
+   run owner cleanup.
+6. **Complete:** stop only when `wp_ultragoal_run` records terminal evidence.
 
-Resume from durable state after interruption. Obey `WP_ULTRAGOAL_DISABLE=1`, iteration/error/validation caps, and repository ownership. The pipeline must never self-approve, directly mark tasks done, bypass evidence, or push to main. Keep every loop bounded and never increase timeouts.
+Resume from durable state after interruption. Obey `WP_ULTRAGOAL_DISABLE=1`,
+iteration/error/validation caps, and repository ownership. Never self-approve, directly
+mark tasks done, bypass evidence, push to main, or increase timeouts (keep every loop bounded and never increase timeouts). After every phase
+transition recorded by `wp ultragoal run`, obtain a fresh OpenCode Go outside review
+before treating the milestone as closed (see Outside-voice above and the `ultragoal` skill).

package/catalog/agent/skills/claude/SKILL.md

@@ -8,6 +8,13 @@ license: MIT
 
 Use when a non-Claude host needs Claude to review a diff, challenge a plan, or answer a focused repo question. Keep it bounded/read-only unless asked otherwise, and report Claude output as advice, not verified fact.
 
+## Single-shot budget (anti-stampede)
+
+- Default: **one** review invocation per request.
+- Do **not** spawn parallel Claude + Codex + Grok + OpenCode reviews unless the user set `review_budget`/`N` > 1.
+- Prefer `wp review run` / `wp review gate` over hand-rolled multi-agent loops.
+- Bounded payload only (see below). Split large diffs across sequential calls, never unbounded whole-PR dumps.
+
 ## Auth check
 
 Use local Claude CLI login directly; do not route through Anthropic API-key env vars.

package/catalog/agent/skills/codex/SKILL.md

@@ -8,6 +8,13 @@ license: MIT
 
 Use this skill from Claude or another non-Codex host when the user wants Codex to independently review a diff, challenge a plan, or answer a repo question. Keep Codex read-only by default and treat its answer as external advice until independently verified.
 
+## Single-shot budget (anti-stampede)
+
+- Default: **one** review invocation per request.
+- Do **not** fan out parallel multi-host review matrices unless the user set `review_budget`/`N` > 1.
+- Prefer `wp review run` / `wp review gate` over spawn/wait agent loops for review.
+- Keep prompts bounded; no whole-repo paste.
+
 ## Auth check
 
 ```bash

package/catalog/agent/skills/fix/SKILL.md

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents]
 related: [verify, testing-philosophy]
 created: "2026-05-13"
-last_reviewed: "2026-05-22"
+last_reviewed: "2026-07-21"
 name: fix
 description: "Root-cause fix workflow that runs investigate first when diagnosis or failing proof is still missing."
 argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
@@ -23,18 +23,43 @@ This command turns "please fix it well" into an enforceable workflow: diagnose
 first, repair at the owner, prove the repair, and escalate to `/verify` when
 the blast radius is broader than a local fix.
 
+## Tooling map
+
+| Need                   | Prefer                                                                      |
+| ---------------------- | --------------------------------------------------------------------------- |
+| Reproduce / large logs | `wp_session_execute`, `wp_session_batch_execute`, `wp_session_execute_file` |
+| Recall prior evidence  | `wp_session_search`, `wp_session_restore`, `wp_session_retrieve`            |
+| Capture decisions      | `wp_session_capture` (do not paste full reports back as user text)          |
+| Scoped proof           | `wp_test`, `wp_lint`, `wp_typecheck`, or `wp_qa`                            |
+| Audits                 | `wp_audit` / `wp_audits`                                                    |
+| Worktree isolation     | `wp_worktree` / `wp blueprint start` — never thrash primary checkout        |
+| PR follow-up           | `wp_pr_status`, `wp_pr_upsert` when landing the fix                         |
+
 ## Non-negotiable invariants
 
 1. **Root cause, not symptom.** Trace the failure to the invariant that actually broke. Do not patch callers when the owner is fixable.
 2. **Loud failures, no silent fallbacks.** No default shims, sentinel returns, or catch-and-continue behavior that hides missing config, bad state, or broken boundaries.
-3. **Use the repo's real execution surface.** Prefer repo-owned wrappers and injected routing guidance over host-specific tool assumptions. If the repo exposes quality wrappers, use them. Use bounded inspection paths for large-output investigation.
+3. **Use the repo's real execution surface.** Prefer MCP `wp_*` tools and repo wrappers over host Bash for search/test/lint. Use bounded session-memory paths for large output.
 4. **Regression proof is mandatory.** Add or strengthen a test or other reliable proof that would fail against the old behavior.
 5. **Raising timeouts is not a fix.** If a timeout fires, investigate the bottleneck. Only raise a bound when the repo already documents that workload and you can cite measurement.
 6. **Zero suppressions, zero papering over.** No lint disables, ts-ignore, compat aliases, or "temporary" branches to sneak the fix through.
 7. **Minimal correct diff.** Update every consumer of a changed contract in the same change, but do not bundle unrelated cleanup.
+8. **Primary checkout is sacred.** If HEAD is detached, primary is dirty with unrelated work, or you are not on a managed worktree for non-trivial edits → **stop** and move to `wp_worktree` / blueprint owner. Never leave the primary checkout broken.
+
+## Opportunistic fix budget (when called from ultragoal / autopilot / pll)
+
+- At most **`fix_budget` (default 1)** pre-existing issues per controller phase.
+- Each must have: named invariant, failing proof, owning path.
+- If the repair needs its own blueprint or expands epic scope → **handoff backlog**, do not inline.
+- Additional discoveries: list in the final report; do not thrash.
 
 ## Protocol
 
+### Step 0a — Worktree preflight
+
+Before editing: confirm you are on a managed worktree or an explicitly allowed branch.
+If the primary checkout is dirty/detached with unrelated state, stop and isolate first.
+
 ### Step 0 — Run the investigate phase when evidence is missing
 
 Before editing, check whether the current context already contains all of the
@@ -94,17 +119,20 @@ Do not keep production code written before the test as "reference". If you wrote
 
 Run the narrowest checks that prove the repaired behavior on the real repo surface:
 
-- targeted test(s) for the repaired path
-- targeted lint/typecheck/build checks for changed files or packages
-- any boundary-specific verification the repo requires for the touched surface
+- `wp_test` / targeted tests for the repaired path
+- `wp_lint` / `wp_typecheck` for changed surfaces
+- `wp_qa` only when the blast radius needs the bookend
+- Before push: `wp ci-preflight` (local pre-push owner). Do not use remote CI
+  re-runs as the primary fix loop (`ci-cost-local-first`).
 
 Rules:
 
-- Prefer repo-owned wrappers or routed quality tools over raw host-specific commands.
-- Reuse fresh logs if the repo auto-saves them; do not re-run long commands just to re-read output.
+- Prefer MCP `wp_*` over raw host Bash.
+- Reuse fresh logs / session-memory indexed output; do not re-run long commands just to re-read.
 - Read the exit code and summary before making a claim.
+- Never `git push --no-verify` to land an unproven fix.
 
-Escalate to `/verify <target>` when any of these are true:
+Escalate to `/verify <target>` (local) or `/verify <target> --merge-ready` when any of these are true:
 
 - the fix crosses packages
 - the fix changes a public or shared contract

package/catalog/agent/skills/grok/SKILL.md

@@ -8,6 +8,13 @@ license: MIT
 
 Use when a non-Grok host needs Grok Build to review a diff, challenge a plan, or answer a focused repo question. Keep it read-only by default. A provenance-backed Grok approval is first-class and satisfies the blueprint strong-reviewer gate alone, with the same rejection authority as Claude or Codex.
 
+## Single-shot budget (anti-stampede)
+
+- Default: **one** review invocation per request.
+- Do **not** run parallel multi-host review swarms unless the user set `review_budget`/`N` > 1.
+- Prefer `wp review run` / `wp review gate --provider grok` for lifecycle authority.
+- Bounded prompts only.
+
 ## Auth / binary
 
 ```bash

package/catalog/agent/skills/investigate/SKILL.md

@@ -17,10 +17,21 @@ flaky behavior, or confusing symptom before editing code.
 - Stop once you can name the broken invariant, show the failing proof, and
   point at the owner that should be repaired.
 
+## Tooling map
+
+| Need                   | Prefer                                                           |
+| ---------------------- | ---------------------------------------------------------------- |
+| Reproduce / large logs | `wp_session_execute`, `wp_session_batch_execute`                 |
+| Large files            | `wp_session_execute_file`                                        |
+| Prior continuity       | `wp_session_search`, `wp_session_restore`, `wp_session_retrieve` |
+| Capture findings       | `wp_session_capture` (short pointer, not full paste-back)        |
+| Proof runs             | `wp_test`, `wp_qa`, `wp_lint`, `wp_typecheck`                    |
+| Code search/read       | host Grep/Read first; avoid shell-as-IDE                         |
+
 ## Workflow
 
 1. Reproduce or capture the failure.
-   - Run the exact failing command or trace the exact user path.
+   - Run the exact failing command or trace the exact user path (prefer `wp_session_execute`).
    - Keep the evidence that matters: error text, failing assertion, exit code,
      log path, or boundary mismatch.
 2. Read the whole boundary.