@webpresso/agent-kit 3.3.3 → 3.3.4

package/THIRD-PARTY-NOTICES.md

@@ -34,19 +34,21 @@ otherwise in their frontmatter.
 These skills document how to invoke external CLIs or packages. Their upstream
 binaries are **not** bundled in `@webpresso/agent-kit`.
 
-## Runtime integrations (not bundled)
+## Runtime integrations
 
-These integrations invoke or install external tools separately; their upstream
-binaries are **not** bundled in `@webpresso/agent-kit`. The table below records
-whether each integration is part of the current default `wp setup` preset set or
-requires explicit `wp setup --with <name>` opt-in. Consumers accept the upstream
+Policy for which upstream CLIs are managed-download vs host-install lives in
+`catalog/agent/rules/managed-tool-binaries.md`. Summary: **rtk** is managed
+(pinned cache download on setup); **vp** / **bun** remain host package-manager
+installs; **actionlint** is probe-only.
+
+The table below records default preset vs opt-in. Consumers accept the upstream
 license separately when an integration is installed.
 
-| Integration                 | Default behavior                                                                                                                        | Upstream                                                                | License    |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------- |
-| `playwright-mcp`            | Opt-in.                                                                                                                                 | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) | Apache-2.0 |
-| `workflow skill provenance` | Curated Markdown skill assets adapted from an MIT-licensed upstream workflow project; no upstream runtime checkout or binaries bundled. | [garrytan/gstack](https://github.com/garrytan/gstack)                   | MIT        |
-| `rtk`                       | In the default preset set; skipped in CI or when `WP_SKIP_RTK=1`.                                                                       | [rtk-ai/rtk](https://github.com/rtk-ai/rtk)                             | Apache-2.0 |
+| Integration                 | Default behavior                                                                                                                               | Upstream                                                                | License    |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------- |
+| `playwright-mcp`            | Opt-in.                                                                                                                                        | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) | Apache-2.0 |
+| `workflow skill provenance` | Curated Markdown skill assets adapted from an MIT-licensed upstream workflow project; no upstream runtime checkout or binaries bundled.        | [garrytan/gstack](https://github.com/garrytan/gstack)                   | MIT        |
+| `rtk`                       | Managed install (pinned release into Webpresso cache on setup); skipped when `WP_SKIP_RTK=1`. Binary not reimplemented; filters stay upstream. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk)                             | Apache-2.0 |
 
 ## Runtime npm dependencies
 

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

@@ -91,9 +91,15 @@ When a feature branch with a `.changeset/<slug>.md` file merges to `main`,
 2. The action runs `wp run version`, which preserves the canonical version
    path: `changeset version && wp run sync-marketplace-version`.
 3. When the Version PR is merged, CI runs `wp run release:publish`, which
-   calls `npm publish --provenance --access public` inside GitHub Actions using
-   npm trusted publishing/OIDC. This workflow is the only production npm publish
-   path for Webpresso packages.
+   calls `npm publish --access public` inside GitHub Actions using npm trusted
+   publishing/OIDC. This workflow is the only production npm publish path for
+   Webpresso packages. **Provenance attestations are not currently produced.**
+   npm only issues provenance for a **public source repository**
+   (`https://docs.npmjs.com/generating-provenance-statements/`), and
+   `webpresso/agent-kit` is private, so `--provenance` was removed from every
+   publish call site. **Do not add `--provenance` back while this repo is
+   private — npm will reject the publish.** Provenance returns automatically
+   through this same OIDC flow if/when the repo becomes public.
 4. After publish, CI verifies the `v<version>` tag on the mainline version-bump
    commit and creates `release/v<version>` as the separate dist-carrying
    compatibility branch for marketplace consumers.
@@ -203,7 +209,12 @@ dist-tag changes, or subsequent versions.
 Use `.github/workflows/release.yml` — not `ci.agent-kit.yml` and not the
 artifact-only matrix job names — because the `release` job in `release.yml` is
 the job that runs `wp run release:publish`, has `id-token: write`, and invokes
-`npm publish --provenance --access public`.
+`npm publish --access public` via npm trusted publishing/OIDC. It does **not**
+pass `--provenance`: npm only issues provenance for a public source
+repository (`https://docs.npmjs.com/generating-provenance-statements/`), and
+this repo is private. Do not add `--provenance` while the repo stays private —
+npm will reject the publish. Provenance returns automatically through this
+same OIDC flow once the repo becomes public.
 
 ## Required repo files
 

package/catalog/agent/rules/managed-tool-binaries.md

@@ -0,0 +1,67 @@
+---
+type: rule
+slug: managed-tool-binaries
+title: Managed third-party tool binaries
+status: active
+scope: repo
+applies_to: [agents]
+related: [rtk-routing]
+created: "2026-07-25"
+last_reviewed: "2026-07-25"
+paths:
+  - "src/tool-runtime/**"
+  - "src/cli/commands/init/scaffolders/**"
+  - "compatible-versions.json"
+  - "THIRD-PARTY-NOTICES.md"
+---
+
+# Managed third-party tool binaries
+
+Policy for when agent-kit **embeds** (managed download/cache) an upstream CLI
+versus leaving install to the host package manager / user.
+
+## Decision rule (YAGNI)
+
+Manage a binary only when **all** of the following hold:
+
+1. **Invisible filter or sidecar** — used on agent/hook hot paths without the
+   user intentionally invoking it (e.g. output filtering).
+2. **Freestanding install creates dual ownership** — PATH/`init` hooks or
+   second install stories fight path-stable `wp` surfaces.
+3. **Small, pinned, capability-probed** — single static binary (or tiny
+   archive), Apache/MIT-class license, bounded probe, fail-open degrade.
+4. **No existing first-class package channel** — if the tool is already the
+   workspace package manager or a full runtime (npm/vp/bun), do not invent a
+   parallel download channel.
+
+Otherwise: **probe + install hint**, or rely on existing global/package install.
+
+## Inventory (current)
+
+| Tool                         | Lane                                            | Why                                                                                                                                              |
+| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **rtk**                      | **Managed** (`src/tool-runtime/managed-rtk.ts`) | Optional hot-path filter; freestanding PreToolUse hooks were dual/broken; pinned GitHub release; capability probe `gain --help`                  |
+| **wp**                       | First-party                                     | Own product binary / runtime staging                                                                                                             |
+| **vp** (vite-plus)           | **Host / package-manager**                      | Workspace package manager + global `vp install`; CI uses `voidzero-dev/setup-vp`; `resolveGlobalCapableVpCommand` — not a cache-download sidecar |
+| **bun**                      | **Host runtime**                                | JS runtime; install via bun.sh / brew; often co-installed with vite-plus; do not dual-manage                                                     |
+| **actionlint**               | **Probe-only**                                  | Optional workflow lint; `runtime-check` prints hint only; not on agent PreToolUse hot path                                                       |
+| **playwright** / MCP plugins | **Opt-in package**                              | Explicit setup/MCP install; not silent binary cache                                                                                              |
+
+## Hard rules
+
+- Do **not** add managed downloaders for `vp` or `bun` without a product
+  decision that retires the package-manager install path (would fork ownership).
+- Do **not** reimplement upstream filter/CLI logic in TypeScript to avoid
+  shipping a binary.
+- New managed tools must: pin version in `compatible-versions.json`, document
+  license in `THIRD-PARTY-NOTICES.md`, use absolute path resolution (never bare
+  PATH as the only source of truth), and degrade fail-open when skip/missing.
+- Freestanding third-party PreToolUse hooks remain forbidden; setup strips
+  known RTK freestanding markers.
+
+## Implementation pattern (when adding a managed tool)
+
+1. Single module under `src/tool-runtime/managed-<tool>.ts` (resolve + ensure + probe).
+2. Setup scaffolder calls `ensure*` only; no brew/cargo as the default lane.
+3. All runtime call sites import the same resolve helper (DRY).
+4. Tests: inject downloader; isolate cache via env root; no network in unit tests.

package/catalog/agent/rules/parallel-orchestration-quota.md

@@ -11,8 +11,9 @@ related:
   - pre-implementation
   - engineering-principles
   - supported-agent-clis
+  - workflow-skills-routing
 created: "2026-07-24"
-last_reviewed: "2026-07-24"
+last_reviewed: "2026-07-25"
 paths:
   - "blueprints/**"
   - "catalog/agent/**"
@@ -29,6 +30,17 @@ policy, `cmd-execution.md` for the scoped-command surface,
 `pre-implementation.md` for the blueprint gate, `engineering-principles.md` for
 scope filters, `supported-agent-clis.md` for host tiers.
 
+## Product mission anchor
+
+Webpresso is a product for building websites and agents on webpresso framework
+tooling, and every agent session here exists to move that product loop forward.
+Token economy is a standing constraint on that loop, not an optimization applied
+when convenient: prefer the harnesses and building blocks — `wp_*` tools,
+skills, subagent dispatch — over long free-form context, and spend the fewest
+tokens that still preserve quality. The orchestrator/executor split, the
+one-deliverable brief, and the cheapest-capable-model rule below are all
+instruments of that constraint, not independent preferences.
+
 ## Orchestrator / executor split
 
 The session that owns the program is an **orchestrator**: it plans, sequences,
@@ -43,6 +55,56 @@ blueprint's owner worktree.
 - The orchestrator runs from its own controller worktree cut from
   `origin/main`, never from the primary checkout.
 
+## One deliverable per brief
+
+**Brief scope drives executor cost more than model tier does.** A brief listing
+four numbered deliverables buys four investigations. Measured on one program:
+multi-item briefs ran 374K–501K tokens each; the same class of defect briefed as
+a single deliverable ran 117K and landed its PR. Trimming scope mid-flight does
+**not** recover the spend — the exploration already happened.
+
+- State **one** deliverable. Secondary polish is `only if trivial`, or omitted.
+- Apply DRY/KISS/YAGNI to the **brief**, before dispatch — not to the diff after.
+  Ask "what is the single smallest change that fixes this?" and brief only that.
+- **Prefer deletion-shaped fixes.** Removing a behavior usually beats adding a
+  mechanism to describe it. Deletion-shaped fixes are cheaper to brief,
+  implement, and review, and they close a defect class rather than narrowing it —
+  which also removes the hedged "narrowed, not closed" wording a partial fix
+  forces into its docs.
+- Give the executor the diagnosis you already hold. Re-deriving a known root
+  cause is pure duplicated cost.
+
+## Never await — poll
+
+An executor that ends its turn to "wait for" a background job **deadlocks**: the
+completion signal has usually already fired, so it idles indefinitely. Measured
+on one program: four executors × 3–5 rounds ≈ 2M tokens for zero landed work.
+Nudges did not break the loop; only orchestrator takeover did.
+
+- Executors **poll in a loop**. Never end a turn waiting for a notification.
+- Read durable state directly instead of awaiting: a review gate's outcome is in
+  `.webpresso/reviews/gates/<gate-id>.json` (`status`, `attempts[]`); CI is
+  readable via the PR status surface. Both are cheaper than waiting.
+- If genuinely blocked, **report and stop** — an explicit blocker is recoverable,
+  an idle turn is not.
+
+## Verify executor output, not executor reports
+
+A report describes intent; the diff is what lands. Read the diff before trusting
+a summary.
+
+- **Measure diffs against the fork point** (`git merge-base origin/main HEAD`),
+  never `origin/main` directly — a stale branch renders main's newer content as
+  deletions, making a five-file change look like a thousand-file catastrophe.
+- Watch for **whole-file rewrites from serializer round-trips**: editing YAML or
+  JSON by parsing and re-emitting silently renormalizes quoting and formatting
+  across the file, burying the real change and risking semantic drift. Config
+  edits are plain-text edits.
+- Orchestrator claims about gate state must be **machine-checked before being
+  passed to an executor**. Asserting "gate X approved your work" without
+  confirming its `reviewedCommit`/target matches what is being shipped sends the
+  executor to land on a stale approval.
+
 ## Model tier by intrinsic difficulty
 
 Pick the **cheapest model that can do the job**, judged by the hardest task in
@@ -66,6 +128,42 @@ work does not. A technically-correct but badly-judged UI passes every check and
 still has to be redone, so the cheaper tier is not actually cheaper. Backend and
 mechanical work keeps the cheapest-capable rule above.
 
+## Operator model ladder (reviewed 2026-07-25)
+
+The tier table above is host-agnostic. This section records how an operator maps
+it onto the hosts actually installed today. It is a **dated operator default,
+revisable per operator and per host** — agent-kit does not own model selection
+or agent hosting, only the dispatch-cost discipline for the work agents hand
+off.
+
+- **Cheap and mid tiers are the default lanes, and they run wide.** Mechanical
+  S/XS work and ordinary M work fan out across several concurrent executors;
+  that parallelism is where the throughput comes from, so it is the normal case,
+  not an exceptional one.
+- **The premium reasoning tier is narrow and deliberate** (e.g. the Claude Opus
+  class): L/XL blueprints, design/UI/frontend work, security- and
+  trust-boundary changes, and anything digest-, wire-format-, or
+  protocol-bearing. If one hard task is the only reason a blueprint wants this
+  tier, re-home that task — do not upgrade the whole lane.
+- **The frontier gating tier is rare and human-invoked** (e.g. the Claude
+  Fable/Mythos class). Its job is milestone approval on one-way doors — a schema
+  or wire format that cannot be un-shipped, a security-posture change, an
+  irreversible migration — not execution. It never enters routine dispatch and is
+  never the default for a sized blueprint.
+- **On a Codex host the operator's configured default model handles routine
+  checks**, with a premium family member reserved for the rare deep check. The
+  configuration owns that identity, not this document: read
+  `~/.codex/config.toml` (`model`), `CODEX_REVIEW_MODEL`, and
+  `CLAUDE_REVIEW_MODEL`. Never hardcode a model id or a preference ordering into
+  a plan, brief, or skill — the ids move faster than the prose does.
+
+Two orderings deliberately live elsewhere and are **not** restated here: the
+OpenCode reviewer purpose→family ordering, which is rendered into the
+[`opencode-go` skill](../skills/opencode-go/SKILL.md) from the committed
+reviewer policy and drift-gated by CI, and the agent-CLI tiers in
+[`supported-agent-clis.md`](./supported-agent-clis.md). Read those; a second
+copy is a second thing to update, and the stale copy is the one an agent reads.
+
 ## Quota awareness across hosts
 
 Provider subscriptions are the budget. Treat weekly quota as a shared,

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

@@ -162,11 +162,17 @@ lifecycle-valid, but they have no sibling review authority; run
 `wp blueprint canonicalize <slug>` before recording review ledgers, artifacts,
 Ultragoal events, or approval frontmatter.
 
-- **Gate input = committed in-folder review authority.** The preferred path is a
-  content-addressed v2 `review-events.jsonl` event produced by `wp review gate`.
-  The legacy path is `_overview.md` frontmatter `approvals:` backed by a matching
-  committed `reviews.md` structured entry and separate tracked artifact. The
-  markdown `## Approvals` checklist is only a human-readable mirror.
+- **Gate input = committed in-folder review authority.** The only path for new
+  blueprints is a content-addressed v2 `review-events.jsonl` event produced by
+  `wp review gate` (or `wp review override`). The legacy path — `_overview.md`
+  frontmatter `approvals:` backed by a matching committed `reviews.md` structured
+  entry and separate tracked artifact — **carries no content binding** (it never
+  reads or hashes the blueprint body), so it is accepted only for blueprints
+  grandfathered at `LEGACY_APPROVAL_LEG_ANCHOR_COMMIT`. On any blueprint created
+  after that anchor, a frontmatter `approvals:` entry does not satisfy the gate no
+  matter which reviewer it names; the audit says so explicitly rather than
+  reporting a bare "0 approvals". The markdown `## Approvals` checklist is only a
+  human-readable mirror.
 - **Durable record = committed in-folder review history.** V2 events bind the
   verdict to the reviewed subject digest and artifact hash. Legacy frontmatter
   entries count only with matching `wp:review-entry` provenance and a tracked
@@ -182,8 +188,10 @@ Ultragoal events, or approval frontmatter.
   Enforced by `wp audit blueprint-lifecycle`, the promotion command, and
   changed-completed blueprint CI audits.
 - **Recording a review entry is MCP-first**: use the `wp_blueprint_review_log`
-  MCP tool to write the artifact, the matching `reviews.md` structured entry,
-  and the corresponding `approvals:` frontmatter entry in one call. It is
+  MCP tool to write the artifact and the matching `reviews.md` structured entry
+  in one call (plus the `approvals:` frontmatter entry for `reject`/`no-verdict`
+  attribution — it never writes an `approve`/`approve-with-nits` entry there,
+  because that field is the unbound legacy leg). It is
   **not** the same as this CLI's own `wp review log` subcommand — that writes
   only the machine ledger (`review-events.jsonl`) and requires `--provider`
   plus a `human` reviewer for any approval verdict; treat the two as distinct,
@@ -199,14 +207,14 @@ Ultragoal events, or approval frontmatter.
   restriction exactly. It cannot mint a `claude`/`codex`/`grok`/OpenCode-Go
   frontmatter approval: no caller-supplied pointer can prove a named non-human
   reviewer actually produced an artifact, so the tool does not accept one.
-  Use it for `reject`/`no-verdict` entries from any reviewer, or a
-  human-adjudicated `approve`/`approve-with-nits`. Satisfying the
+  Use it for `reject`/`no-verdict` entries from any reviewer, or to record a
+  human-adjudicated `approve`/`approve-with-nits` in `reviews.md`. Satisfying the
   strong-reviewer promotion gate for a `claude`/`codex`/`grok`/OpenCode-Go identity
-  still requires either a converged `wp review gate` run (ledger-backed,
-  requires no frontmatter at all) or a maintainer directly authoring the
-  `approvals:` frontmatter with first-hand knowledge that reviewer actually
-  produced that verdict — there is intentionally no MCP-reachable shortcut
-  around that.
+  requires a converged `wp review gate` run (ledger-backed, requires no
+  frontmatter at all). Hand-authoring `approvals:` frontmatter is no longer an
+  option on a post-anchor blueprint — the gate does not read that leg there — so
+  there is neither an MCP-reachable nor a hand-edited shortcut around the
+  content-bound ledger.
 - **`wp review override <slug> --reason "…" --confirm` is the gated CLI escape
   hatch for a genuinely un-convergeable gate** — a strong reviewer legitimately
   rejected the subject but its sole remaining blocker is physically
@@ -342,16 +350,24 @@ scaffold a draft only to exempt it. For multi-file exempt follow-ups, use a
 `wp worktree new` — never `bp/<slug>`, which pre-claims the owner branch and
 collides with `wp blueprint start`.
 
-When the primary checkout has user-owned edits or is still on a topic branch,
-prefer:
+`--switch-primary` (the current flag name; `--stash-primary` is accepted as a
+deprecated alias and no longer stashes anything) is **not** a way to preserve
+"user-owned edits" on the primary checkout — it never stashes primary state at
+all. A **dirty** primary always refuses merge-cleanup, unconditionally, naming
+the offending files, with or without this flag:
 
 ```bash
-cd <primary-checkout> && wp worktree merge-cleanup <merged-worktree-or-branch> --base origin/main --stash-primary
+cd <primary-checkout> && wp worktree merge-cleanup <merged-worktree-or-branch> --base origin/main --switch-primary
 ```
 
-That preserves the existing primary-checkout state in a named git stash,
-switches the primary to the expected branch, and then performs the normal
-remove + fast-forward cleanup.
+The flag bypasses only the OTHER refusal: a **clean** primary sitting on the
+wrong branch. In that case it switches the primary to the expected branch and
+then performs the normal remove + fast-forward cleanup — switching a clean
+checkout is harmless, there is nothing uncommitted to lose. If the primary
+checkout has uncommitted work — human-owned edits, a topic branch you're mid
+way through, or leftover blueprint draft scaffold — commit it, `git stash` it
+yourself, or run `wp blueprint abandon <slug> --confirm` first. Do not expect
+`--switch-primary`/`--stash-primary` to preserve it for you.
 
 ## PR-level blueprint coverage gate
 

package/catalog/agent/rules/rtk-routing.md

@@ -5,9 +5,9 @@ title: RTK Tool Routing
 status: active
 scope: repo
 applies_to: [agents]
-related: []
+related: [managed-tool-binaries]
 created: "2026-05-07"
-last_reviewed: "2026-05-07"
+last_reviewed: "2026-07-25"
 paths:
   - "**/*"
 ---
@@ -17,25 +17,26 @@ paths:
 `rtk *` and the `wp_*` MCP tools are independent lanes. Webpresso-owned dev
 workflows route to the matching `wp_*` MCP tool — each tool's `description`
 states when to use it, and `pretool-guard` denies the common raw equivalents.
-There is no injected routing block; the tool descriptions plus AGENTS.md are the
-source of routing guidance.
-
-Use `rtk *` for shell-tool output filtering on the long-tail command surface
-that webpresso does not own.
 
 ## Ownership boundary
 
-- webpresso owns `wp_*` dev-workflow routing and MCP-shaped deny wording
-- rtk owns shell-tool output filtering for the long-tail surface (`git`, `gh`,
-  `kubectl`, `cargo`, `pytest`, `ruff`, and similar non-quality-engine tools)
-- `wp_*` and `rtk *` are independent lanes; prefer the `wp_*` MCP tool for
-  webpresso-owned workflows
+See also `managed-tool-binaries` for why only rtk is managed-download (not vp/bun).
+
+- webpresso owns **managed packaging** of the upstream `rtk` binary (pinned
+  download into the Webpresso cache on setup), PreToolUse rewrite routing, and
+  wrapping of quality-engine runners when filtering is enabled
+- rtk owns shell-tool **output filtering** (implementation stays upstream;
+  Apache-2.0; never reimplemented in TypeScript)
+- freestanding consumer hooks (`rtk-rewrite.sh`, `rtk hook claude`) are
+  **retired** — never re-introduce them
+- consumers **do not** brew/cargo install rtk for Webpresso workflows
 
 ## Hard rules
 
 - Never reimplement upstream rtk filters in webpresso.
 - Never wrap the `rtk` prefix behind `wp rtk`.
-- Keep `wp_*` and `rtk *` as independent lanes.
+- Never install freestanding RTK PreToolUse groups in managed project settings.
+- Prefer managed absolute rtk path from setup; do not require a global PATH install.
 
 ## Lane 4: Webpresso workflow/browser skills
 
@@ -45,6 +46,11 @@ Keep these as an independent lane from the `wp_*` MCP tools.
 
 ## Subprocess coverage note
 
-wp*\* tools shelling out via child_process.spawn own their own filtering; rtk PreToolUse hook
-only fires for top-level Bash calls and does NOT reach into wp*\* internals. CLI verbs
-(wp <verb> from a shell) ARE rewritten by rtk.
+wp* tools shelling out via child_process.spawn own their own filtering via
+managed rtk when available. pretool-guard may rewrite exact `git status` to the
+managed rtk binary when present. When rtk is skipped (`WP_SKIP_RTK=1`) or
+unavailable, commands passthrough unfiltered.
+
+Long-tail RTK filtering beyond exact `git status` requires an explicit
+`rtk …` invocation (or the managed absolute binary path); pretool-guard
+does not auto-rewrite the rest of the rtk command surface.

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

@@ -20,7 +20,7 @@ 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).
+After each ultragoal **phase or plan-gate milestone**, run an **OpenCode Go** outside-voice review and pick the model by purpose. The purpose→family ordering lives in one place — the committed reviewer policy rendered into the `opencode-go` skill — so follow that skill and do not restate the ordering here. 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 owned by `workflow-skills-routing.md`): one sequential path, no multi-host stampede.
 
 ## Vague gate
 
@@ -34,8 +34,9 @@ A brief is anchored when it includes a file path, symbol, issue number, test nam
 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.
+Default budgets if the user omits them: `concurrency=4`, `fix_budget=1`, no
+`/loop`; `review_budget` per `workflow-skills-routing.md`. See `ultragoal`
+skill.
 
 ## Tooling map
 

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

@@ -21,12 +21,12 @@ 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                 |
+| 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
@@ -66,7 +66,8 @@ Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer
 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).
+   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`).
    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`.
@@ -87,7 +88,7 @@ primary checkout.
 
 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.
+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`. Prefer purpose-matched OpenCode Go first; do not fan out multi-host review swarms.
 
 ### Milestones that require a review
 
@@ -147,7 +148,8 @@ Use `--purpose plan` for plan-phase promotion and `--purpose delivery` for imple
 - 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.
+  source snapshot. Use `/verify --merge-ready` (merge-ready `review_budget`, per
+  `workflow-skills-routing.md`), not default local verify.
 
 ## Snapshot / dirty worktree
 

package/dist/esm/audit/hook-surface.js

@@ -33,7 +33,11 @@ export function detectDrift(entries) {
         .map(([key, entries]) => ({ key, count: entries.length, entries }));
 }
 function isRewriter(command) {
-    return (command.includes("rtk hook claude") ||
+    // Managed pretool-guard emits updatedInput rewrites (exact git status → rtk).
+    // Classify it as a rewriter so freestanding RTK + pretool-guard collide in audit.
+    return (command.includes("wp-pretool-guard") ||
+        command.includes("wp hook pretool-guard") ||
+        command.includes("rtk hook claude") ||
         command.endsWith("pretooluse.mjs") ||
         command.includes("/pretooluse.mjs"));
 }

package/dist/esm/audit/repo-guardrails.d.ts

@@ -49,6 +49,14 @@ export declare function auditCatalogDrift(rootDirectory?: string, options?: Cata
 export declare function validateCommitMessage(message: string, options?: CommitMessageOptions): RepoAuditResult;
 export declare function auditCommitMessageFile(messageFile: string, options?: CommitMessageOptions): RepoAuditResult;
 export declare function auditDocsFrontmatter(rootDirectory?: string, options?: DocsFrontmatterOptions): RepoAuditResult;
+/**
+ * Flags a blueprint whose raw frontmatter clearly lists one or more
+ * `approvals:` entries but whose YAML-parsed `approvals` field yields zero —
+ * the corruption signature `wp blueprint move --force-recovery` produces
+ * when it silently destroys approval authority without making the document
+ * fail to parse outright.
+ */
+export declare function detectSuspiciousZeroApprovals(raw: string, frontmatter: Record<string, unknown>): string | undefined;
 export declare function auditBlueprintLifecycle(rootDirectory?: string, options?: BlueprintLifecycleOptions): RepoAuditResult;
 export declare function formatRepoAuditReport(auditResult: RepoAuditResult): string;
 export declare function parseFrontmatter(markdown: string): Record<string, string>;

package/dist/esm/audit/repo-guardrails.js

@@ -210,6 +210,53 @@ export function auditDocsFrontmatter(rootDirectory = process.cwd(), options = {}
     }
     return result("Docs frontmatter", markdownFiles.length, violations);
 }
+const APPROVALS_KEY_LINE = /^approvals:\s*$/m;
+/**
+ * Count `- ` list-item lines that follow a top-level `approvals:` key inside
+ * the RAW frontmatter text, stopping at the next top-level key. Returns -1
+ * when there is no `approvals:` key at all (nothing to check).
+ *
+ * This is deliberately independent of the YAML parser: it is the ground
+ * truth for "did the author intend approval entries here", used to catch a
+ * corrupted write where the YAML still happens to parse but the approvals
+ * mapping was silently truncated or displaced (e.g. a scalar-restore bug
+ * that inserts or drops lines near the approvals block).
+ */
+function countRawApprovalEntries(raw) {
+    const frontmatterBlock = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)?.[1] ?? "";
+    const keyIndex = frontmatterBlock.search(APPROVALS_KEY_LINE);
+    if (keyIndex === -1)
+        return -1;
+    const afterKey = frontmatterBlock.slice(keyIndex).split("\n").slice(1);
+    let count = 0;
+    for (const line of afterKey) {
+        if (/^[A-Za-z0-9_]+:/.test(line))
+            break;
+        if (/^\s*-\s/.test(line))
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Flags a blueprint whose raw frontmatter clearly lists one or more
+ * `approvals:` entries but whose YAML-parsed `approvals` field yields zero —
+ * the corruption signature `wp blueprint move --force-recovery` produces
+ * when it silently destroys approval authority without making the document
+ * fail to parse outright.
+ */
+export function detectSuspiciousZeroApprovals(raw, frontmatter) {
+    const rawEntryCount = countRawApprovalEntries(raw);
+    if (rawEntryCount <= 0)
+        return undefined;
+    const parsedApprovals = frontmatter["approvals"];
+    const parsedCount = Array.isArray(parsedApprovals) ? parsedApprovals.length : 0;
+    if (parsedCount > 0)
+        return undefined;
+    return (`Frontmatter parses to 0 approvals but the raw YAML lists ${rawEntryCount} ` +
+        "approval entr" +
+        (rawEntryCount === 1 ? "y" : "ies") +
+        " — likely corrupted frontmatter near the approvals block.");
+}
 export function auditBlueprintLifecycle(rootDirectory = process.cwd(), options = {}) {
     const root = resolve(rootDirectory);
     const blueprintsRoot = resolve(root, options.blueprintsRoot ?? "blueprints");
@@ -259,7 +306,30 @@ export function auditBlueprintLifecycle(rootDirectory = process.cwd(), options =
                 continue;
             }
             const raw = readFileSync(canonicalPath, "utf8");
-            const frontmatter = matter(raw).data;
+            let frontmatter;
+            try {
+                frontmatter = matter(raw).data;
+            }
+            catch (error) {
+                // A blueprint write (e.g. `wp blueprint move --force-recovery`) can
+                // emit invalid YAML — most commonly a folded-scalar continuation
+                // line stranded after an already-quoted scalar. Every downstream
+                // reader (including the approval gate) then fails the same way this
+                // parse does, so surface it as a first-class violation instead of
+                // letting the whole audit crash on the first corrupted file.
+                violations.push({
+                    file: relativePath(root, canonicalPath),
+                    message: `Frontmatter failed to parse as YAML: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                continue;
+            }
+            const suspiciousApprovals = detectSuspiciousZeroApprovals(raw, frontmatter);
+            if (suspiciousApprovals) {
+                violations.push({
+                    file: relativePath(root, canonicalPath),
+                    message: suspiciousApprovals,
+                });
+            }
             if (frontmatter.type !== "blueprint" && frontmatter.type !== "parent-roadmap") {
                 violations.push({
                     file: relativePath(root, canonicalPath),