@webpresso/plugin-codex 0.0.16 → 0.0.17

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wp",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Webpresso app: blueprints, skills, hooks, and MCP server",
   "author": {
     "name": "Webpresso",

package/bin/wp

@@ -17,8 +17,11 @@
 #      when the admitted repository's own .git/worktrees/*/gitdir names it.
 #   3. else (no checkout ancestor at all) the nearest ancestor
 #      .webpressorc.json: its top-level exact-semver "runtime" pin
-#      -> ~/.webpresso/runtimes/<pin>/wp (missing = error)
-#   4. else the newest stable ~/.webpresso/runtimes/<x.y.z>/wp
+#      -> ~/.webpresso/versions/<pin>/bin/wp, else the legacy
+#      ~/.webpresso/runtimes/<pin>/wp (missing = error)
+#   4. else the installer's active release ~/.webpresso/current/bin/wp, else
+#      the newest stable ~/.webpresso/versions/<x.y.z>/bin/wp, else the legacy
+#      newest stable ~/.webpresso/runtimes/<x.y.z>/wp
 #   5. else a named error, exit 127 — never a different runtime. A pre-shim
 #      ~/.webpresso/bin/wp is never run implicitly (nothing in it proves it is
 #      a release rather than a development build); name it with
@@ -110,7 +113,12 @@ is_exact_semver() {
   return 0
 }
 
-runtimes_dir=${HOME:-}/.webpresso/runtimes
+# Release layout literals; src/runtime/runtime-selector-vocab.ts (WP_RELEASE_LAYOUTS)
+# is the authority and bin/wp-shim.subprocess.test.ts asserts both directions.
+webpresso_home=${HOME:-}/.webpresso
+current_release=$webpresso_home/current/bin/wp
+versions_dir=$webpresso_home/versions
+runtimes_dir=$webpresso_home/runtimes
 
 # Sets PIN to the top-level "runtime" of $1 (empty when absent). The document
 # is opened non-blocking, must be a regular file, and is read through a
@@ -146,33 +154,50 @@ read_pin() {
   return 1
 }
 
-choose_latest_release() {
-  best=
+# Sets BEST to the newest stable x.y.z under directory $1 whose release binary
+# is "$1/<version>/$2" (an executable file); empty when there is none.
+scan_releases() {
+  BEST=
   best_major=
   best_minor=
   best_patch=
-  for entry in "$runtimes_dir"/*/; do
+  for entry in "$1"/*/; do
     [ -d "$entry" ] || continue
     entry=${entry%/}
     version=${entry##*/}
     is_exact_semver "$version" stable || continue
-    [ -f "$entry/wp" ] && [ -x "$entry/wp" ] || continue
+    [ -f "$entry/$2" ] && [ -x "$entry/$2" ] || continue
     major=${version%%.*}
     rest=${version#*.}
     minor=${rest%%.*}
     patch=${rest#*.}
-    if [ -z "$best" ] ||
+    if [ -z "$BEST" ] ||
       [ "$major" -gt "$best_major" ] ||
       { [ "$major" -eq "$best_major" ] && [ "$minor" -gt "$best_minor" ]; } ||
       { [ "$major" -eq "$best_major" ] && [ "$minor" -eq "$best_minor" ] && [ "$patch" -gt "$best_patch" ]; }; then
-      best=$version
+      BEST=$version
       best_major=$major
       best_minor=$minor
       best_patch=$patch
     fi
   done
-  if [ -n "$best" ]; then
-    choose latest-release "$runtimes_dir/$best/wp"
+}
+
+# The installer's active release (the current link) wins, then the newest
+# versions/x.y.z/bin/wp, then the legacy runtimes/x.y.z/wp.
+choose_latest_release() {
+  if [ -f "$current_release" ] && [ -x "$current_release" ]; then
+    choose current-release "$current_release"
+    return 0
+  fi
+  scan_releases "$versions_dir" bin/wp
+  if [ -n "$BEST" ]; then
+    choose latest-release "$versions_dir/$BEST/bin/wp"
+    return 0
+  fi
+  scan_releases "$runtimes_dir" wp
+  if [ -n "$BEST" ]; then
+    choose latest-release "$runtimes_dir/$BEST/wp"
     return 0
   fi
   return 1
@@ -189,14 +214,15 @@ choose_release() {
     read_pin "$rc_file" || fail pin-invalid "$rc_file $PIN_PROBLEM."
     if [ -n "$PIN" ]; then
       is_exact_semver "$PIN" || fail pin-invalid "$rc_file pins runtime \"$PIN\"; use an exact version such as 1.2.3 (no ranges)."
-      pinned=$runtimes_dir/$PIN/wp
-      [ -f "$pinned" ] && [ -x "$pinned" ] || fail pin-not-installed "$rc_file pins runtime $PIN, but $pinned is not installed under $runtimes_dir."
+      pinned=$versions_dir/$PIN/bin/wp
+      [ -f "$pinned" ] && [ -x "$pinned" ] || pinned=$runtimes_dir/$PIN/wp
+      [ -f "$pinned" ] && [ -x "$pinned" ] || fail pin-not-installed "$rc_file pins runtime $PIN, but it is installed under neither $versions_dir/$PIN/bin/wp nor $runtimes_dir/$PIN/wp."
       choose pinned-release "$pinned"
       return 0
     fi
   fi
   choose_latest_release && return 0
-  fail no-release-installed "no webpresso source checkout above $PWD and no release under $runtimes_dir; install the Webpresso app, or name a runtime explicitly with WEBPRESSO_WP_BIN (for example a pre-shim \$HOME/.webpresso/bin/wp release) or WP_FORCE_JIT_PATH (a source checkout)."
+  fail no-release-installed "no webpresso source checkout above $PWD and no release at $current_release, under $versions_dir or under $runtimes_dir; install the Webpresso app, or name a runtime explicitly with WEBPRESSO_WP_BIN (for example a pre-shim \$HOME/.webpresso/bin/wp release) or WP_FORCE_JIT_PATH (a source checkout)."
 }
 
 : "${WEBPRESSO_WP_BIN:=}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/plugin-codex",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "private": false,
   "description": "Codex plugin adapter for the Webpresso app (wp CLI) skills, hooks, and MCP runtime.",
   "homepage": "https://github.com/webpresso/app#readme",

package/plugin-skill-ownership.json

@@ -2,12 +2,15 @@
   "schemaVersion": 1,
   "host": "codex",
   "packageName": "@webpresso/plugin-codex",
-  "packageVersion": "0.0.16",
+  "packageVersion": "0.0.17",
   "runtimeDirs": [".codex/skills", ".agents/skills"],
   "skills": {
     "ai-deslop": {
       "digest": "sha256:cf07df5835037f10401400e220c1c923f5325a6149d59c231ce316e10595fdfc"
     },
+    "antigravity": {
+      "digest": "sha256:729c4dd74e5c6394c31de23d04f664140088ee58ddfc57f3a2751394945a938b"
+    },
     "autopilot": {
       "digest": "sha256:8355f6ddc6e53e68ada49248bdd8d8beb0069ed09d3f2d346debc2401270445c"
     },
@@ -27,7 +30,7 @@
       "digest": "sha256:574669e040141e9986e362e9f46e3176aa47eccfda0f4589205d9d6d65e57b8d"
     },
     "deep-interview": {
-      "digest": "sha256:1d5bbb564dde9037722d2029f771afb52c2fe000a2b38822db430224cbe3407d"
+      "digest": "sha256:6feeaa35de63a0e1f39dbe2882ca91a72928a058f138d4d79e70d81d09209693"
     },
     "deep-research": {
       "digest": "sha256:ece766cb18869317d7c8992fc562920b03250ff8c44bdcb9eccdc3b21922a83f"
@@ -42,16 +45,16 @@
       "digest": "sha256:306355888da0827e3523022077f731845726bbaaf595ca12515cc91d8605b5e6"
     },
     "fix": {
-      "digest": "sha256:cf5d74995a690307ebbc3f6b017b03a0c2b395acecccb16dcfedbb9674d0f155"
+      "digest": "sha256:aa5caa229f0a56290bd6ad4487f41fd2933ac9e9cf4fdf2191f04a559bf66943"
     },
     "handoff": {
       "digest": "sha256:5d40899f54fabe3f6ec8f99b417345a433850585086570872a137a1d0d837002"
     },
     "hooks-doctor": {
-      "digest": "sha256:0a32515ba42755847552991fe5dafe5bd9572a9540e7b376f56d8549320a4cf2"
+      "digest": "sha256:6169e2b4b3638b9b5430811cd44e7952a54685b6f6556ebe81a9aee8ade1a3e0"
     },
     "investigate": {
-      "digest": "sha256:44578904d967161b9128830c7c66f9684bb8c8257e8da7884dd6dbda88743b39"
+      "digest": "sha256:b6d82b2dc76297167a8fb75422d1f7037c4b9f0c74186cc4a2d719246764ca7e"
     },
     "lore-protocol": {
       "digest": "sha256:a80fbacc765e8b886437b9fdf7dd71e1ceb1b98b939078ec90fc88d06a8b4c69"
@@ -72,10 +75,10 @@
       "digest": "sha256:b728dad90254d4c9f81b3818321d34ab53519b79ce20ff3bfe08bfacb2aa3e86"
     },
     "plan-refine": {
-      "digest": "sha256:3dccc4e85ff7f355b1d7297b636d7acf3c31658b749fc1778ffdd1a255b27300"
+      "digest": "sha256:8a0e38564627565d267b347a0361eb222b9ba230961998c2d6812874ea7cf608"
     },
     "ralplan": {
-      "digest": "sha256:aa8879addccc19c0cdb69fce945fe54cf356380203f774080f8655211a5841c3"
+      "digest": "sha256:95d02771d3e3a46d225b1bf9dd12a33e83c9e0dbe2c126aad24986c4cb1d98a3"
     },
     "team": {
       "digest": "sha256:e403a5a92d145e777d7a344fe8fc6fe5df44640691aa2319b6dfd50b909166f5"
@@ -87,13 +90,13 @@
       "digest": "sha256:23fdad944b089de3cfcd13957a5ac10c37bd3d136b192029af69368bca1470db"
     },
     "tooling-friction": {
-      "digest": "sha256:7f6e60a2c886e0c735135ab66926fbbd1b54d9291036fb0ddea020c7754f1534"
+      "digest": "sha256:6f94949b6910d88ff974a95f4cd67bbaca05579db88fbeacc50126a13faf800b"
     },
     "tph": {
       "digest": "sha256:bed3684a850651534f315d355cdeae50d951c429817df0f105cccdb7f4e1561b"
     },
     "ultragoal": {
-      "digest": "sha256:8826e955c3a68f962d73a4b476d952574fa32e802c0d2616d569e58e7cfc29c3"
+      "digest": "sha256:e60091f795311fd4ee8779b60b04f835522163fcca5d27122740b66f66afeceb"
     },
     "verify": {
       "digest": "sha256:e1aa3baed96ef005b144e17fac8a2153b90a075b142acee2fdfba7c89e613765"

package/skills/antigravity/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: antigravity
+description: "Antigravity outside-voice reviewer through Webpresso MCP."
+license: MIT
+---
+
+# Antigravity outside-voice review
+
+Use only for a requested content-bound plan or delivery review. Treat output as external advice
+until independently verified.
+
+## MCP-only contract
+
+- Call `review_gate` exactly once for the real plan version or delivery diff.
+- Observe the same durable operation with `review_gate_wait` when needed.
+- Never invoke a provider command, the legacy review CLI, or a removed review-run surface.
+- If the review MCP is unavailable, stop and report it unavailable. There is no CLI fallback.
+
+## Gate call
+
+```jsonc
+{
+  "project_id": "<project>",
+  "slug": "<blueprint-slug>",
+  "purpose": "delivery",
+  "base_ref": "<full-base-sha>",
+  "authority_ref": "<full-head-sha>",
+  "caller_model": "<your own model id, exactly as your host reports it>",
+  "repository_access": "none",
+}
+```
+
+Each newly executed provider review that reaches a verdict is one formal round of the
+slug's budget, and its approval is authority. An identical-subject call replays the recorded
+verdict with no new review and no new round. A partial approval, withheld because adjudication
+is incomplete (not every prior finding was briefed, or a briefed prior claim was marked
+still-open without a matching finding), grants no authority and spends no round.
+
+## Reviewer selection
+
+Pass `caller_model` with your OWN model id, exactly as your host reports it, and omit
+`provider`, `model`, and `effort`: the gate selects the reviewer route itself — a cross-family
+reviewer chosen for capability, current provider limits, and measured daily cost — and reports
+the choice in `policy_selection`. Never name a reviewer model, probe a provider CLI for its
+catalog, or read a credential store to discover models at invocation time; provider catalog
+discovery belongs to the snapshot drift workflow. An operator may still pass an explicit
+`provider`/`model` as a human override; agents must not.
+
+## Review quality
+
+Follow `catalog/agent/rules/review-methodology-sota.md`; report typed verdict, model,
+artifact, grounded findings, and independently verified conclusions.

package/skills/deep-interview/SKILL.md

@@ -219,7 +219,7 @@ Present execution options after artifact generation using explicit handoff contr
 - **`autopilot`** — when the spec is already strong enough for direct planning plus execution. Consumer uses the spec as the clarified execution brief with the non-goals and acceptance criteria as binding context.
 - **`ultragoal`** — when the clarified work should become durable, sequentially tracked goal-mode work.
 - **`team`** — when the task is large, multi-lane, or blocker-sensitive enough to justify coordinated parallel execution.
-- **Blueprint lifecycle** — refine with `blueprint_put`, review the exact version with `review_gate`, and inspect the auto-promoted result with `blueprint_get` when work should enter planned execution directly.
+- **Blueprint lifecycle** — refine with `blueprint_put`, review the exact version with `review_gate`, then promote the approved version explicitly with `blueprint_promote` when work should enter planned execution directly (MCP `review_gate` never auto-promotes).
 - **Refine further** — re-enter the loop to resolve the highest-leverage remaining uncertainty when residual ambiguity is still too high or an early-exit/above-threshold warning indicates too much risk to proceed cleanly.
 
 For research-shaped requests (a research question, evaluator-backed analysis, or reference gathering), hand off to `autoresearch` after the interview converges on a validator-ready mission; keep the explicit `refine further` vs `launch` boundary and do not launch until the user confirms.

package/skills/fix/SKILL.md

@@ -98,6 +98,19 @@ there, the investigation work is part of `fix`.
 - Read enough surrounding code to say the broken invariant in one sentence.
 - If the issue is nondeterministic, gather evidence until you can describe the slow/flaky/failing case without guessing.
 
+**Prove the mechanism before naming it.** A cause that merely explains the
+symptom is a hypothesis, not a finding. Run the failing thing with the candidate
+values and read what it actually did; trace the claim to the code that executes,
+not the code whose name matches the theory. If you cannot reproduce it, label it
+unverified and keep investigating — do not write it into a plan, commit, or
+report as the cause.
+
+**When a cause is disproved, go back to the command, not to the next story.**
+Substituting another plausible explanation without new observation is how one
+dead route gets three confident, wrong diagnoses. If your second and third
+explanations are still unobserved, you have not reproduced the failure yet.
+Related: `catalog/agent/rules/evidence-discipline.md` § 6.
+
 If the "issue" is actually several unrelated failures, stop and ask which one to fix first.
 
 ### Step 2 — Decide where the fix belongs

package/skills/hooks-doctor/SKILL.md

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents]
 related: []
 created: "2026-05-07"
-last_reviewed: "2026-05-07"
+last_reviewed: "2026-11-01"
 name: hooks-doctor
 description: "Hook/plugin doctor for install health. Use for hook blocked, pretooluse, plugin broken."
 argument-hint: "[--skip-mcp]"
@@ -55,13 +55,13 @@ Each check prints `[x]` (pass) or `[ ]` (fail) with a detail line:
 
 ## Failure Remediation
 
-| Check                                            | Likely Cause                                                   | Fix                                                               |
-| ------------------------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `pretool-guard` / `post-tool` / etc. — not found | `wp run build` not run after install                           | `wp run build`                                                    |
-| `pretool-guard` / etc. — not executable          | `chmod +x` not persisted                                       | Re-run `wp run prepare` or `wp run build` which runs `chmod-bins` |
-| `plugin.json integrity` — missing                | Claude adapter manifest absent from `@webpresso/plugin-claude` | Re-run `wp setup --host claude` or reinstall the Claude plugin    |
-| `MCP server liveness` — timeout                  | MCP server cold-start too slow                                 | Wait and retry, or run `wp hooks doctor --skip-mcp`               |
-| Any check — not found at `dist/esm/...`          | Build artifacts missing                                        | Run `wp run build` in the webpresso repo                          |
+| Check                                            | Likely Cause                                                      | Fix                                                               |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `pretool-guard` / `post-tool` / etc. — not found | `wp run build` not run after install                              | `wp run build`                                                    |
+| `pretool-guard` / etc. — not executable          | `chmod +x` not persisted                                          | Re-run `wp run prepare` or `wp run build` which runs `chmod-bins` |
+| `plugin.json integrity` — missing                | Claude or Antigravity adapter manifest absent from plugin package | Re-run `wp setup --host <host>` or reinstall the host plugin      |
+| `MCP server liveness` — timeout                  | MCP server cold-start too slow                                    | Wait and retry, or run `wp hooks doctor --skip-mcp`               |
+| Any check — not found at `dist/esm/...`          | Build artifacts missing                                           | Run `wp run build` in the webpresso repo                          |
 
 ### Updating the webpresso MCP server (monorepo authors)
 
@@ -95,6 +95,8 @@ started. Check the installed host version before using version-scoped controls.
   commands](https://dev.opencode.ai/v2/docs/cli/commands/); host documentation
   verified 2026-10-17). These `dev.opencode.ai` paths sit on a preview domain
   and can move; confirm the v2 path still resolves before following it.
+- **Antigravity:** Preferences / Settings → Plugins → reload or toggle `wp` plugin,
+  or restart the Antigravity session. Verify with `wp hooks doctor` or `wp hooks status`.
 
 After reconnecting, prove the loaded source rather than the connection:
 

package/skills/investigate/SKILL.md

@@ -42,9 +42,20 @@ flaky behavior, or confusing symptom before editing code.
    - Name the broken invariant in one sentence.
    - Name the owner that should enforce it.
    - Separate facts from guesses.
+   - **Every cause must carry the observation that proved it**: the command you
+     ran, its output, and the code path that produced it. A cause you have not
+     executed against the failing case is a guess and must be labelled as one.
 4. Disconfirm cheap alternatives.
    - Test the obvious competing explanations before settling on one cause.
    - Add temporary diagnostics only when needed, and remove them after one pass.
+   - **When a cause is disproved, return to the reproduction rather than
+     replacing it with the next plausible story.** Two or three confident
+     explanations in a row, none observed, means the failure has not been
+     reproduced yet — go back to step 1.
+   - A test fixture, capability object, or recorded tool output that asserts
+     behaviour is the weakest link: confirm at least one path against the real
+     binary, module, or service it stands in for.
+   - Related: `catalog/agent/rules/evidence-discipline.md` § 6.
 5. Produce failing proof.
    - Prefer a targeted failing test.
    - If test-first is impossible at this boundary, use the nearest deterministic

package/skills/plan-refine/SKILL.md

@@ -75,6 +75,7 @@ Run **1–3 (and relevant review lenses) in parallel** whenever tools allow. Do
    - Score alternatives on elegance, durability, and efficiency; keep only the winner and write the rejection rationale for heavier options.
 
 4. **Plan-review lenses (skip when the caller already ran them).** Folded `/autoplan`: run relevant CEO/founder, design, engineering, and DevEx lenses **in parallel when independent**; consolidate keep/change/drop, unresolved taste calls, tests, go/no-go.
+   - **Review cost — know it before you dispatch.** An `approve`, `approve-with-nits`, or `reject` verdict from a `review_gate` run spends ONE formal review round (per slug and purpose). A no-verdict attempt spends none; editing the plan spends and resets nothing already spent. `src/review/budgets.ts` owns the numeric allowance — never restate it in prose — and `wp review budget <slug>` reports remaining capacity live.
    - **Skip condition.** If the caller states `plan-* reviews complete for this pass`, do **not** re-run the lenses. `ralplan` runs them before handing off, so re-running them here is duplicated spend, not a second opinion.
    - **Re-entry.** If refinement itself **materially changes scope**, re-run only the affected lens — never the full set — then continue applying.
    - **Re-review rounds.** `catalog/agent/rules/review-methodology-sota.md` Principle 5 sets the delta-anchored adjudication contract subsequent `review_gate` rounds follow.

package/skills/ralplan/SKILL.md

@@ -42,6 +42,10 @@ Use when the user invokes `$ralplan`, asks for RALPLAN, or wants consensus plann
 1. **Blueprint is the plan.** Freeform notes are not durable consensus. Create or bind a blueprint before reviews.
 2. **Align with other lanes before planning.** This repo is worked by many concurrent agent sessions. Before the code dive, establish which surfaces another live lane already owns and record them as explicit non-goals. See [Lane alignment](#lane-alignment-not-optional). The user should not have to re-assert this.
 3. **Ground before drafting.** Code dive (+ bounded external research when needed) happens **before** the blueprint draft is treated as serious.
+   - **A stated cause is a claim that must be observed.** When a plan explains
+     why something fails, it carries the command that produced that answer.
+     An unobserved cause is a guess laundered into consensus, and review will
+     spend rounds disproving it instead of improving the plan.
 4. **Reviews before refine.** Run risk-matched `plan-*` skills on the blueprint, apply findings, **then** `/plan-refine`.
 5. **No implementation.** Do not edit product source, commit implementation, or start `ultragoal`/`team`/`autopilot` unless the user explicitly switches out of planning.
 6. **No review stampede.** Do not fan out multi-host outside-voice swarms. Prefer in-host skill loads; at most one outside voice only if the user asks or the change is auth / data-loss / public-API sensitive.

package/skills/tooling-friction/SKILL.md

@@ -47,10 +47,30 @@ Optional post-land **product signal** for MCP/CLI/hooks/CI pain so Webpresso too
 4. Write the capture with the validating verb — it is the only writer, and it
    puts the document at the central, repo-scoped desktop state surface:
 
+   First write the capture JSON to a scratch file with the host's file-write
+   tool, under the scratch directory `$TMPDIR/webpresso/scratch/` (outside every
+   worktree, per the agent scratch write policy; never the repo root, and never
+   committed). Resolve that directory to an **absolute path** yourself and use
+   the literal path below — hosts refuse a command that carries a shell
+   variable expansion. Then hand the file to the verb with `--from-file`; no
+   pipe, redirect or shell variable is involved:
+
+   ```bash
+   wp tooling-friction write --file YYYY-MM-DD-<slug|pr|session>.json --from-file <absolute-scratch-dir>/tooling-friction-capture.json
+   ```
+
+   If your `wp` predates `--from-file`, **redirect** the same file to stdin
+   instead:
+
    ```bash
-   printf '%s' "$CAPTURE_JSON" | wp tooling-friction write --file YYYY-MM-DD-<slug|pr|session>.json
+   wp tooling-friction write --file YYYY-MM-DD-<slug|pr|session>.json < <absolute-scratch-dir>/tooling-friction-capture.json
    ```
 
+   Do not pipe a shell variable into the verb (`printf '%s' "$CAPTURE_JSON" | …`):
+   hosts refuse the unresolvable expansion, and the fallback — writing the JSON
+   straight into the store — skips validation, which is how a capture with ten
+   schema issues reached disk. Never write the capture into the store yourself.
+
    The verb parses the document through the shared schema helper **before** it
    touches disk, so a capture that violates v1 is refused (non-zero exit,
    naming every failing field path) and nothing is written. It prints the

package/skills/ultragoal/SKILL.md

@@ -190,7 +190,7 @@ Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer
    Controller validation evidence is **machine-qa (prior QA phase) + N outside voices**
    (default N=1), not two outside model reviewers at budget 1.
    `review_gate` has one mode: purpose plan for exact-version draft plan
-   approval/auto-promotion, purpose delivery for implementation/phase outside
+   approval (then `blueprint_promote`), purpose delivery for implementation/phase outside
    voice. Each new provider verdict is a formal round of the slug's budget and
    an approval is authority immediately. A CLI delivery gate is explicit MCP-unavailable
    compatibility only, not this MCP contract. Use `pr_*` for PR babysit — no
@@ -211,7 +211,7 @@ primary checkout.
 
 ## Outside-voice review (required for autopilot)
 
-Autopilot and agent-driven ultragoal loops **must** request an outside-voice review after each **goal/phase milestone**. Use **`review_gate`** purpose plan for exact-version draft plan approval/auto-promotion and one single-shot **`review_gate`** purpose delivery call for implementation/phase outside voice. The gate has one mode: each newly executed provider review that reaches a verdict is a formal round of the slug's budget, an approval is authority immediately, and an identical-subject call replays the recorded verdict without a new round. CLI delivery gates are explicit MCP-unavailable compatibility only, not this MCP contract.
+Autopilot and agent-driven ultragoal loops **must** request an outside-voice review after each **goal/phase milestone**. Use **`review_gate`** purpose plan for exact-version draft plan approval (then promote with `blueprint_promote`) and one single-shot **`review_gate`** purpose delivery call for implementation/phase outside voice. The gate has one mode: each newly executed provider review that reaches a verdict is a formal round of the slug's budget, an approval is authority immediately, and an identical-subject call replays the recorded verdict without a new round. CLI delivery gates are explicit MCP-unavailable compatibility only, not this MCP contract.
 
 Count each milestone review against `review_budget` for merge-ready claims: **exactly one sequential** reviewer path unless the user sets N; the default value is owned by `workflow-skills-routing.md`. Do not fan out multi-host review swarms.
 
@@ -223,7 +223,7 @@ milestones. Each new provider verdict is one formal round of the slug's budget.
 
 | Milestone          | When                                                                                                                             |
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| Plan gate          | Before `draft` → `planned`, using the exact version returned by `blueprint_put`; approval may auto-promote the same version      |
+| Plan gate          | Before `draft` → `planned`, using the exact version returned by `blueprint_put`; then `blueprint_promote` the approved version   |
 | Phase advance      | After ultragoal advances `plan` → `execute`, `execute` → `qa`, `qa` → `validate`, `validate` → `land`, or lands `complete`       |
 | Task batch handoff | After a meaningful execute batch when the phase remains `execute` (at least once per blueprint before claiming execute-complete) |