@webpresso/agent-kit 3.1.26 → 3.1.30

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

@@ -5,78 +5,83 @@ title: PLL Skill — Blueprint-Aware Parallel Execution
 status: active
 scope: repo
 applies_to: [agents]
-related: []
+related: [ultragoal, autopilot, team]
 created: "2026-05-07"
-last_reviewed: "2026-05-07"
+last_reviewed: "2026-07-21"
 name: pll
+description: "Blueprint-aware parallel execution: ready-queue, max-parallel lanes, cascade-skip."
 ---
 
 # PLL Skill — Blueprint-Aware Parallel Execution
 
-Use this skill when the user invokes `/pll` or asks for Blueprint-aware parallel execution.
+Use when the user invokes `/pll` or asks for Blueprint-aware parallel execution.
 
-`/pll` is not a standalone runner. It is the operator-facing adapter over the same shared execution model used by `wp blueprint exec`: both surfaces consume the same Blueprint-backed launch spec, backend vocabulary, and runtime-state bridge, but `/pll` stays manual and operator-facing.
-
-`/pll`:
-
-1. understands Blueprint/task dependencies
-2. updates `wp blueprint` lifecycle state honestly
-3. delegates generic parallel fan-out to the engine layer such as `$ultrawork` or host-native subagents
+`/pll` is the operator-facing adapter over the same shared execution model as
+`wp blueprint exec`: Blueprint-backed launch specs, backend vocabulary, and
+runtime-state bridge. `/pll` stays manual and operator-facing; `ultragoal` is the
+durable multi-phase controller that should call the same ready-queue rules.
 
 ## Responsibilities
 
-1. **Input parsing**
-   - Accept inline task lists, comma-separated strings, or file paths.
-   - Treat blueprint paths under `blueprints/` as lifecycle-backed execution.
-2. **Blueprint lifecycle**
-   - Use `wp blueprint start`, `wp blueprint task ...`, and `wp blueprint finalize` for durable state.
-   - Never use `wp blueprint move` as the normal execution primitive.
-   - Keep the lifecycle semantics aligned with `wp blueprint exec`; do not invent a separate `/pll`-only plan model.
-3. **Dependency-aware batching**
-   - Compute ready work from explicit dependencies and obvious blocking relationships.
-   - Prioritize critical-path or high-fan-out work when choosing the next batch.
-4. **Engine delegation**
-   - Hand independent work to the current engine layer (`$ultrawork`, subagents, or equivalent runtime-native parallel lanes).
-   - Do not promise a fixed active-agent count across runtimes.
-5. **Verification discipline**
-   - Require repo verification before marking blueprint tasks complete.
-6. **Shared execution model**
-   - Treat `/pll` as the interactive/manual front door for the same control-plane contract that `wp blueprint exec` uses.
-   - Reuse the same backend names, progress bridge semantics, and truthfulness rules.
-
-## Roadmap-Aware Lane Picking
-
-When no explicit task list is supplied, ground lane selection in `wp blueprint list` before inventing work:
+1. **Input parsing** — inline task lists, files, or blueprint paths under `blueprints/`.
+2. **Blueprint lifecycle** — `wp blueprint start`, task tools, finalize; never `wp blueprint move`
+   as the normal primitive. Prefer MCP: `wp_blueprint_list` / `get` / `context` /
+   `put` / `transition` / `task_verify`.
+3. **Ready-queue (max parallel)** — compute tasks with satisfied deps; print the ready-set
+   before launching; fill up to `concurrency` (default 4, max 8; user can set `--max`).
+4. **Engine delegation** — independent work → host subagents / `$ultrawork` / worktrees via
+   `wp_worktree`. Before each delegate: `wp_session_context` (no full-history paste).
+5. **Verification** — complete tasks only with `wp_blueprint_task_verify` + repo proof
+   (`wp_qa` / `wp_test` / targeted tools). Large commands → `wp_session_execute` /
+   `wp_session_batch_execute`.
+6. **Shared model** — same control-plane contract as `wp blueprint exec` and ultragoal execute.
+
+## Ready-queue algorithm
+
+```text
+ready = tasks where status=todo and all Depends are done
+while ready or in_progress:
+  launch min(len(ready), concurrency - in_progress) implementers in worktrees
+  on success → verify with evidence → unlock dependents into ready
+  on hard fail → block task, cascade-skip dependents that require it, continue others
+```
 
-1. Prefer active `ROADMAP` rows and pick the next `planned` `CHILD` row whose `depends_on:` chain is satisfied.
-2. Treat `ORPHANS` as fallback work only when no roadmap child is actionable.
-3. Keep the heuristic discoverable and auditable: `wp audit roadmap-links` checks bidirectional roadmap/child links, while `wp audit blueprint-lifecycle` checks lifecycle placement.
-4. If command output changes, update `/pll` guidance and the shared blueprint output contract together.
+Prioritize critical-path / high-fan-out tasks when choosing the next batch.
 
 ## Concurrency Limits
 
-| Scope              | Guidance                                                                  |
-| ------------------ | ------------------------------------------------------------------------- |
-| Default batches    | Use the smallest parallelism that still keeps safe independent lanes busy |
-| Test-heavy tasks   | Keep concurrency conservative                                             |
-| Build/deploy tasks | Keep concurrency conservative                                             |
+| Scope                       | Guidance                                     |
+| --------------------------- | -------------------------------------------- |
+| Default                     | Keep safe independent lanes busy (default 4) |
+| Hard max                    | 8 unless the user explicitly raises          |
+| Test-heavy / build / deploy | Conservative (often 1–2)                     |
+| Shared file ownership       | Serialize or merge tasks — never two writers |
 
 ## Deadlock and Failure Handling
 
-- If no tasks remain ready but some are blocked, report the blocking tasks and their dependencies.
-- Failed tasks stay blocked with reasons; downstream work remains blocked unless explicitly safe to continue.
-- If lifecycle mutation fails, stop instead of continuing with stale plan state.
+- No ready work but blocked tasks remain → report blockers + deps; stop or handoff.
+- Failed tasks stay blocked with reasons; dependents cascade-skipped unless safe alone.
+- Lifecycle mutation failure → stop (no stale plan execution).
+- Capture decisions with `wp_session_capture`; resume via `wp_session_search` / `restore`.
+
+## Roadmap-Aware Lane Picking
+
+When no explicit task list is supplied, ground selection in `wp blueprint list`:
+
+1. Prefer active `ROADMAP` rows; next `planned` `CHILD` with satisfied `depends_on:`.
+2. `ORPHANS` only when no roadmap child is actionable.
+3. Audits: `wp audit roadmap-links`, `wp audit blueprint-lifecycle`.
 
 ## When **NOT** to use
 
-- Small, strictly serial work where `/plan` or direct execution is simpler.
-- Situations where you only need generic parallel fan-out and do not need Blueprint lifecycle/state awareness; use `$ultrawork` directly there.
+- Small strictly serial work → direct execution or `/fix`.
+- Generic fan-out without blueprint lifecycle → host-native parallel only.
+- Overnight multi-phase goals → `ultragoal` / `autopilot` (which should still use these rules).
 
-## Quick Start Examples
+## Quick Start
 
 ```bash
 /pll "lint auth, lint utils, typecheck api [depends: lint auth], test api [depends: typecheck api]"
 /pll tasks.md --max=6
-/pll blueprints/in-progress/new-launch.md
 /pll blueprints/in-progress/new-launch/_overview.md
 ```

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

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents]
 related: [autopilot, goal, plan-refine, verify]
 created: "2026-07-13"
-last_reviewed: "2026-07-13"
+last_reviewed: "2026-07-21"
 name: team
 description: "Coordinate multiple dashboard-backed agent sessions on one task."
 argument-hint: "<brief|role plan>"
@@ -18,32 +18,49 @@ argument-hint: "<brief|role plan>"
 Use `team` when the work needs coordinated parallel lanes with a leader-owned
 task list, explicit handoffs, and independent verification. Prefer native
 subagents for small bounded lookups; use `team` when the parallel work should be
-visible, durable, and operator-controllable from `wp dash`.
+visible, durable, and operator-controllable from `wp dash`. Prefer `ultragoal` +
+`/pll` when the work is blueprint-owned and does not need multi-provider dashboard
+lanes.
+
+## Tooling map
+
+| Need                  | Prefer                                                          |
+| --------------------- | --------------------------------------------------------------- |
+| Dashboard / sessions  | `wp dash`, `wp_fleet_status`, `wp_worker_tail`                  |
+| Worktrees             | `wp_worktree` per lane                                          |
+| Context-light handoff | `wp_session_context` (required before spawn — no history paste) |
+| Continuity            | `wp_session_capture` / `search` / `restore`                     |
+| Blueprint tasks       | `wp_blueprint_task_verify` only for completion                  |
+| QA                    | `wp_qa` / targeted `wp_test` / `wp_lint` / `wp_typecheck`       |
+| PR                    | `wp_pr_upsert` / `wp_pr_status` / `wp_pr_wait`                  |
 
 ## Protocol
 
 1. Start from a grounded brief or an approved blueprint. If scope is vague, run
-   `plan-refine` first and define task lanes, shared files, and verification.
+   `plan-refine` first and define task lanes, shared files, budgets, and verification.
 2. Open or reuse `wp dash` and launch the provider sessions needed for the
    lanes. Direct `wp claude`, `wp codex`, and `wp opencode` commands are
    expected to enter the dashboard in interactive terminals.
 3. Assign one owner per lane. Include the task, allowed files or surfaces,
    expected output, verification command, and blocker-report rule.
-4. Keep one lane or leader pass responsible for integration and evidence.
+4. Before each worker spawn, build a bounded manifest with `wp_session_context`
+   (objective, constraints, evidence refs, remaining steps). Never copy parent transcripts.
+5. Keep one lane or leader pass responsible for integration and evidence.
    Workers report findings, patches, tests, and unresolved risks; they do not
    self-approve or mark blueprint tasks complete.
-5. Integrate only after checking shared-file conflicts, updated assumptions,
+6. Integrate only after checking shared-file conflicts, updated assumptions,
    and verification evidence. Use `wp_blueprint_task_verify` for task completion
    when a blueprint owns the work.
-6. Stop when every lane is complete, cancelled, or explicitly blocked and the
-   leader has recorded verification evidence.
+7. Stop when every lane is complete, cancelled, or explicitly blocked and the
+   leader has recorded verification evidence (≤40-line handoff if blocked).
 
 ## Coordination Rules
 
 - Use a single source of truth for assignments: the blueprint, goal handoff, or
   leader-maintained task list.
-- Require ACK-style lane starts for shared files, dependency boundaries, or
-  handoffs.
+- Cap concurrency (default 4). Cascade-skip dependents of hard failures.
+- Opportunistic `/fix` uses `fix_budget` (default 1) total across the team, not per lane.
+- Require ACK-style lane starts for shared files, dependency boundaries, or handoffs.
 - Reassign or narrow blocked lanes instead of letting work drift.
 - Escalate changed assumptions before widening scope.
 - Never bypass review provenance, push to main, self-approve, or increase

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

@@ -5,9 +5,9 @@ title: Ultragoal
 status: active
 scope: repo
 applies_to: [agents]
-related: [autopilot, plan-refine, verify]
+related: [autopilot, plan-refine, verify, pll, fix, opencode-go]
 created: "2026-07-10"
-last_reviewed: "2026-07-20"
+last_reviewed: "2026-07-21"
 name: ultragoal
 description: "Run durable multi-blueprint ultragoals through evidence-gated handoffs."
 argument-hint: "<new|status|handoff|run|cancel> [brief]"
@@ -15,30 +15,158 @@ argument-hint: "<new|status|handoff|run|cancel> [brief]"
 
 # Ultragoal
 
-Use `wp ultragoal` as the durable controller for work spanning one or more blueprints.
+Use `wp ultragoal` / MCP `wp_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.
+
+## 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` | 1         | Outside-voice reviewers for merge-ready (0 for local work) |
+| `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).
+
+## Tooling map (use these; do not reimplement with Bash)
+
+| Phase                  | Prefer MCP / CLI                                                                       | Purpose                                             |
+| ---------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Create / resume        | `wp_ultragoal_new`, `wp_ultragoal_status`                                              | Durable controller state                            |
+| Isolation              | `wp_worktree`                                                                          | Owner / lane worktrees; never primary as controller |
+| Blueprint read         | `wp_blueprint_list`, `wp_blueprint_get`, `wp_blueprint_context`                        | Ready-set and deps                                  |
+| Blueprint write        | `wp_blueprint_put`, `wp_blueprint_transition`                                          | Spec edits (MCP-only for blueprints)                |
+| Task done              | `wp_blueprint_task_verify` only                                                        | Evidence-gated completion                           |
+| Parallel execute       | `/pll` or ready-queue + host subagents                                                 | Max parallel when deps allow                        |
+| Context-light delegate | `wp_session_context`                                                                   | Manifest for subagents (no history paste)           |
+| Continuity             | `wp_session_capture`, `wp_session_search`, `wp_session_restore`, `wp_session_snapshot` | Decisions / resume                                  |
+| Large command / file   | `wp_session_execute`, `wp_session_batch_execute`, `wp_session_execute_file`            | Bounded output + index                              |
+| QA                     | `wp_qa` (or `wp_lint` + `wp_typecheck` + `wp_test`)                                    | Affected quality gates                              |
+| PR / land              | `wp_pr_upsert`, `wp_pr_status`, `wp_pr_wait`                                           | Open early; wait on required checks                 |
+| Fleet / workers        | `wp_fleet_status`, `wp_worker_tail`                                                    | Multi-session visibility                            |
+| Token gain             | `wp_gain`                                                                              | Optional efficiency check after heavy execute       |
+| Advance loop           | `wp_ultragoal_run`, `wp_ultragoal_handoff`, `wp_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 (never main as controller).
-2. Read `wp ultragoal status`, execute only the current phase handoff, then call `wp ultragoal run` again.
-3. Complete blueprint tasks only through `wp_blueprint_task_verify` with passing evidence.
-4. Stop when the controller reports `complete`, `cancelled`, blocked guard exhaustion, or `WP_ULTRAGOAL_DISABLE=1`.
+1. Create or resume the ultragoal in a **managed blueprint owner worktree** (`wp_worktree` /
+   `wp blueprint start`). 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 `wp_ultragoal_run` again after evidence.
+5. Mark tasks done **only** via `wp_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 `wp_qa` / targeted tools; outside review only when
+   merge-ready and within `review_budget` (default **exactly 1** sequential outside voice).
+   Prefer `wp review gate` for lifecycle authority. Use `wp_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 `wp_ultragoal_handoff` and emit a **≤40-line handoff**: goal, done, blockers,
+  evidence refs (`wp_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 **OpenCode Go** outside-voice review after each **goal/phase milestone**, and must pick the model by purpose. Direct `wp review run` output is advisory only. Lifecycle authority that can satisfy promotion/completion gates comes only from a converged **`wp review gate`** (content-addressed ledger + bound artifact).
+
+Count each milestone review against `review_budget` for merge-ready claims: **exactly one sequential** reviewer path unless the user sets N. Prefer purpose-matched OpenCode Go first; do not fan out multi-host review swarms.
+
+### Milestones that require a review
+
+Run a distinct OpenCode Go review (via `wp review gate` when the milestone is a promotion/approval gate; otherwise `wp review gate` or a purpose-matched gate resume) after each of:
+
+| Milestone          | When                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Plan gate          | Before `draft` → `planned` / when ultragoal phase is `plan` and promotion is required                                            |
+| 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 OpenCode Go is unavailable or hits a provider-wide usage limit, capture the failure evidence and stop; do not substitute a forged approval.
+
+### Purpose → model routing (no hardcoding IDs)
+
+Resolve models from the live catalog every time:
+
+```bash
+opencode models opencode-go
+```
+
+Pick by purpose (same intent as the committed OpenCode reviewer policy / `opencode-go` skill):
+
+| Purpose                                     | Preferred family (live catalog)                                                                  | Why                        |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------- |
+| Plan / architecture critique                | DeepSeek **Pro** (`opencode-go/deepseek…-pro`)                                                   | Deeper plan review depth   |
+| Coding / implementation quality             | Kimi **Code** first (`…kimi…-code`)                                                              | Coding quality lane        |
+| Cheap recheck / high-availability follow-up | DeepSeek **Flash** (`…deepseek…-flash`)                                                          | Fast secondary pass        |
+| Aggregate / unspecified                     | Follow `opencode-go` skill order: Kimi Code → DeepSeek Pro → DeepSeek Flash → remaining families | Default outside-voice lane |
+
+Resolve the actual model ID with catalog greps (never paste a fixed model string into agent instructions as the only option):
+
+```bash
+CATALOG=$(opencode models opencode-go)
+# plan critique example:
+MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-pro$' | sort -V | tail -1)
+# coding example:
+# MODEL=$(echo "$CATALOG" | grep '^opencode-go/kimi' | grep -- '-code$' | sort -V | tail -1)
+```
+
+Treat a provider-wide usage limit as terminal for every OpenCode Go model in the current review window; do not hop families to evade a usage block on the same provider.
+
+### Gate invocation shape
+
+```bash
+wp review gate <blueprint-slug> \
+  --purpose plan|delivery \
+  --provider opencode \
+  --model "$MODEL" \
+  --effort medium|high \
+  --target HEAD \
+  --json
+```
+
+Use `--purpose plan` for plan-phase promotion and `--purpose delivery` for implementation/delivery validation. Resume interrupted gates with `--resume <gate-id>` against the same immutable target.
+
+### Honesty rules (non-negotiable)
 
-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. Keep every loop bounded and never increase timeouts.
+- Never self-approve or hand-edit `reviews.md` / `review-events.jsonl` / frontmatter approvals to fake OpenCode Go authority.
+- Never mark blueprint tasks done except through `wp_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 (`gh pr view` + `gh pr checks --required`) when:
-  - PR is `OPEN` or `MERGED`
-  - required checks are green (same evaluator as land)
-  - PR head source snapshot matches the clean worktree HEAD snapshot
-- If no PR-bound green CI is available, ultragoal falls back to local **`wp qa`** (`vp run qa`).
-- Do **not** raise timeouts to paper over incomplete worktrees; open a PR early so CI can satisfy QA.
-- Prefer `wp pr wait` / `gh run watch` while babysitting; do not invent multi-sleep poll loops.
-- **Land** still requires a **MERGED** PR with green required checks bound to the projected source snapshot.
+- **QA phase** prefers **GitHub required checks** for the worktree PR (`wp_pr_status` /
+  `wp_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 **`wp_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` (review_budget=1), not default local verify.
 
 ## Snapshot / dirty worktree
 
-- Ultragoal ledger appends to blueprint `reviews.md` / `review-events.jsonl` / `review-artifacts/**`.
-- These paths under both `blueprints/**` and monorepo `webpresso/blueprints/**` are **evidence-only dirt** and must not fail `createCleanSourceSnapshot`.
-- Dirty **source** paths (including `_overview.md` task status edits) still fail closed until committed.
+- Ultragoal ledger appends to blueprint `reviews.md` / `review-events.jsonl` /
+  `review-artifacts/**`.
+- These paths under both `blueprints/**` and monorepo `webpresso/blueprints/**` are
+  **evidence-only dirt** and must not fail `createCleanSourceSnapshot`.
+- Dirty **source** paths (including `_overview.md` task status edits) still fail closed
+  until committed. Use `wp_session_snapshot` before risky branch switches.

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

@@ -7,10 +7,10 @@ scope: repo
 applies_to: [agents]
 related: [testing-philosophy, tph]
 created: "2026-05-07"
-last_reviewed: "2026-07-13"
+last_reviewed: "2026-07-21"
 name: verify
 description: "Post-implementation quality gate: run checks, TPH audit, cleanup, docs, proof."
-argument-hint: "<target> [--full] where target is: package|file|plan-slug|all"
+argument-hint: "<target> [--full|--merge-ready] where target is: package|file|plan-slug|all"
 ---
 
 # Verify
@@ -21,6 +21,33 @@ Post-implementation quality gate. Run after implementation exists, before claimi
 repair. `/verify` owns the broader question: **is this work actually complete,
 integrated, and free of stale garbage?**
 
+## Modes
+
+| Invocation                       | Outside voice                      | When                           |
+| -------------------------------- | ---------------------------------- | ------------------------------ |
+| `/verify <target>` (default)     | **0**                              | Local completeness / iteration |
+| `/verify <target> --full`        | **0** (broader local gates)        | Full local QA bookend          |
+| `/verify <target> --merge-ready` | **exactly 1** (unless user sets N) | Claiming merge-ready / land    |
+
+Default `/verify` must **not** spawn outside reviewers. That stampede is a known
+token/time failure mode. Merge-ready runs **one** sequential outside voice via
+the preferred skill (`claude` / `codex` / `grok` / one OpenCode Go), then stops.
+
+## Tooling map
+
+| Gate                      | Prefer                                                          |
+| ------------------------- | --------------------------------------------------------------- |
+| Lint / types / tests / QA | `wp_lint`, `wp_typecheck`, `wp_test`, `wp_qa`                   |
+| Format                    | `wp_format`                                                     |
+| Audits                    | `wp_audit`, `wp_audits`                                         |
+| Blueprint                 | blueprint MCP tools + `wp audit blueprint-lifecycle`            |
+| PR / CI wait              | `wp_pr_status`, `wp_pr_wait` (not multi-sleep loops)            |
+| Release                   | `wp_release_readiness` when shipping                            |
+| Large output              | `wp_session_execute` / `batch_execute` / `execute_file`         |
+| Continuity                | `wp_session_capture` for verify summary; avoid paste-back walls |
+| E2E / act                 | `wp_e2e`, `wp_ci_act` when the change requires them             |
+| Outside authority         | `wp review gate` (not raw multi-agent review swarms)            |
+
 ## Iron law — evidence before claims
 
 No completion claim without fresh verification evidence.
@@ -40,15 +67,15 @@ Not sufficient: "should pass", "looks correct", lint-only evidence for runtime c
 ```bash
 /verify <target>
 /verify <target> --full
+/verify <target> --merge-ready
 ```
 
 `<target>` is a file path, package name, blueprint slug, or `all`.
 
 Follow the repo's current routing and command surface:
 
-- use repo-owned quality wrappers first
-- use injected quality-tool routing when present
-- use bounded large-output tooling when the repo instructs it
+- use MCP `wp_*` / repo-owned quality wrappers first
+- use bounded session-memory tooling for large output
 - reuse fresh logs instead of re-running broad commands just to inspect output
 
 ## Folded health dashboard
@@ -82,6 +109,9 @@ workflow:
 1. Identify target type (file / package / blueprint slug / all).
 2. Map each claim you plan to make to the exact command or log that proves it.
 3. If the target is a blueprint slug, run the repo's blueprint show/audit surface and record the acceptance boxes that still need proof.
+4. **CI cost / local-first:** treat remote CI as confirmation, not the first
+   debugger. Load `ci-cost-local-first` expectations: no hook skips, no
+   blind `gh run rerun`, Ubicloud for private non-release jobs.
 
 ## Phase 1 — Governance gates
 
@@ -98,17 +128,32 @@ Hard stop on any failure.
 
 Run the narrowest checks that prove the touched behavior:
 
-- targeted lint
-- targeted typecheck
-- targeted tests
-- build / e2e / package checks only when the change requires them
+- `wp_lint` / targeted lint
+- `wp_typecheck` / targeted typecheck
+- `wp_test` / targeted tests
+- `wp_qa`, `wp_e2e`, build / package checks only when the change requires them
+
+**Before push or PR open/update**, run the pre-push owner end-to-end:
+
+```bash
+wp ci-preflight
+```
+
+That is fail-fast branch-scoped format → guardrails → typecheck → lint →
+test. Agent-kit itself enforces it from `.husky/pre-push`; consumer repos may
+keep pre-push checks user-owned, so run the command explicitly before pushing.
+Do **not** claim push-ready if preflight failed. Do **not** bypass hooks to ship
+red work.
 
 Rules:
 
-- Prefer repo wrappers over raw underlying tools.
-- Reuse fresh logs if the runner auto-saves them.
+- Prefer MCP `wp_*` over raw underlying tools.
+- Reuse fresh logs / session-memory indexed output if the runner auto-saves them.
 - Never claim broader correctness than the commands actually proved.
-- If the repo documents a "full QA" bookend, reserve it for the final broad pass rather than every iteration.
+- If the repo documents a "full QA" bookend, reserve `wp_qa` / `--full` for the final broad pass rather than every iteration.
+- If CI is already red: read the failed job log, reproduce with the matching
+  local `wp` command, fix, re-run `wp ci-preflight`, then push **one**
+  corrective commit — do not burn another full matrix “to check.”
 
 ## Phase 3 — Cross-surface impact scan
 
@@ -161,59 +206,52 @@ cleanup, route that pass through `ai-deslop` first rather than broadening
 
 This phase exists to catch the garbage that often slips in beside otherwise-correct work.
 
-## Phase 6 — Outside-model approval gate
+## Phase 6 — Outside-model approval gate (**`--merge-ready` only**)
+
+**Skip this entire phase** for default `/verify` and `/verify --full`. Local
+`done` claims do not require outside voice.
 
-Before claiming merge-ready, obtain outside-voice model approvals unless the
-user explicitly asked for a different approval count or reviewer mix.
+Before claiming **merge-ready**, obtain outside-voice approvals only under this policy:
 
-Default policy:
+Default merge-ready policy:
 
-- Require **one extra model approval** by default. At most **one OpenCode Go reviewer** counts toward the requirement unless the user explicitly asks for multiple OpenCode models.
-- If the user asks for more, fewer, zero, or specific reviewers, follow that
-  explicit instruction and report the chosen requirement.
-- These approvals are model outside-voice approvals, not a substitute for
-  required human GitHub reviews or branch-protection approvals.
+- Require **exactly one** extra model approval unless the user sets a different N.
+- At most **one OpenCode Go reviewer** counts toward the requirement unless the user
+  explicitly asks for multiple OpenCode models.
+- Run reviewers **sequentially** (try next only if current unavailable). Never fan out
+  parallel multi-host review swarms.
+- If the user asks for more, fewer, zero, or specific reviewers, follow that instruction
+  and report the chosen requirement.
+- These approvals are model outside-voice approvals, not a substitute for human GitHub
+  reviews or branch-protection approvals.
 
-Reviewer preference:
+Reviewer preference (pick **one** path):
 
-- When running from Codex, prefer **Claude or Grok** (fall back to one OpenCode Go reviewer if both are unavailable).
-- When running from Claude, prefer **Codex or Grok** (fall back to one OpenCode Go reviewer if both are unavailable).
-- When Codex/Claude/Grok outside voice is unavailable, use **one OpenCode Go
-  reviewer** if OpenCode is logged in.
-- Prefer the repo's outside-voice skills instead of hand-rolled commands:
-  `$agent-kit:claude`, `$agent-kit:codex`, `$agent-kit:grok`, and one OpenCode Go reviewer
-  skills such as `$agent-kit:opencode-go`, `$agent-kit:qwen`,
-  `$agent-kit:deepseek`, `$agent-kit:glm`, `$agent-kit:kimi`,
-  `$agent-kit:minimax`, or `$agent-kit:mimo`.
+- From Codex → Claude or Grok (else one OpenCode Go).
+- From Claude → Codex or Grok (else one OpenCode Go).
+- From Grok → Claude or Codex (else one OpenCode Go).
+- Prefer skills: `claude`, `codex`, `grok`, or one of `opencode-go` / `qwen` /
+  `deepseek` / `glm` / `kimi` / `minimax` / `mimo`.
 
 Approval evidence requirements:
 
-- For blueprint lifecycle approval workflows, run `wp review gate <blueprint-slug> --target HEAD --json`
-  first so exact-SHA reusable evidence and approval frontmatter are handled
-  transactionally. Use `wp review log` / `wp review read` for focused ledger
-  inspection or manual evidence recording.
-- Each outside reviewer must return a clear `APPROVED`/`BLOCKED` (or equivalent)
-  verdict with enough evidence to identify what it reviewed.
-- Record outside approval evidence as PR comments when a PR exists.
-- Each PR comment must include the approving model/tool name, provider/family
-  when known, verdict, reviewed commit or branch, and any blockers or caveats.
-- If there is no PR yet, record the same evidence in the final Verify report and
-  add the PR comments once the PR exists before calling the PR merge-ready.
-- If an outside reviewer is unavailable (not installed, not logged in, missing
-  model, timeout after the reviewer skill's allowed retry path), do not silently
-  count it. Try the next preferred reviewer. If the required count still cannot
-  be met, report the exact approval gap and say the work is **not merge-ready**.
+- Blueprint lifecycle: `wp review gate <blueprint-slug> --target HEAD --json` first.
+  Use `wp review log` / `wp review read` for inspection.
+- Each reviewer must return clear `APPROVED`/`BLOCKED` with enough evidence.
+- Record as PR comments when a PR exists (model/tool, verdict, reviewed commit).
+- Unavailable reviewer → try next preferred; if still short, report gap and
+  **not merge-ready** (never invent approvals).
 
 ## Phase 7 — Final completion statement
 
 Report:
 
-- what was verified
-- which commands/logs prove it
-- which docs/help/instruction surfaces were refreshed when command or operator guidance changed
-- which outside models approved it, with PR comment links when a PR exists
+- mode used (`local` / `full` / `merge-ready`)
+- what was verified and which `wp_*` commands/logs prove it
+- which docs/help/instruction surfaces were refreshed when guidance changed
+- outside models only if merge-ready (with PR comment links when applicable)
 - what remains intentionally out of scope
 
-When catalog assets, generated instruction templates, or checked-in generated instruction copies changed, include the repo's public-package-safety or package-surface leak checks in the verification evidence.
+When catalog assets or generated instruction surfaces changed, include public-package-safety or package-surface leak checks.
 
 If any required check is missing, the correct result is **not done yet**, not a softer claim.

package/dist/esm/audit/blueprint-lifecycle-sql.d.ts

@@ -26,5 +26,13 @@ export interface BlueprintLifecycleAuditOptions {
     readonly baseRef?: string;
     /** Restrict expensive/error-producing checks to blueprints touched in git. */
     readonly changedOnly?: boolean;
+    /**
+     * When set (from `wp audit --affected` / pre-commit staged files), restrict
+     * changed-only scope to blueprints that appear in this path set.
+     *
+     * Without this filter, porcelain includes untracked drafts and can fail an
+     * unrelated skill/docs commit that never staged any blueprint.
+     */
+    readonly affectedFiles?: readonly string[];
 }
 export declare function auditBlueprintLifecycleSql(cwd?: string, options?: BlueprintLifecycleAuditOptions): Promise<RepoAuditResult>;