@webpresso/plugin-claude 0.0.9 → 0.0.11

package/skills/tooling-friction/SKILL.md

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents]
 related: [verify, ultragoal, tech-debt, devex-review, land-policy]
 created: "2026-08-03"
-last_reviewed: "2026-08-03"
+last_reviewed: "2026-08-11"
 name: tooling-friction
 description: "After land, capture MCP/CLI friction tips (optional; never blocks.)"
 argument-hint: "[--promote] [blueprint-slug|pr-number|session]"
@@ -50,26 +50,34 @@ Optional post-land **product signal** for MCP/CLI/hooks/CI pain so Webpresso too
    <state-root>/<repo-key>/tooling-friction/YYYY-MM-DD-<slug|pr|session>.json
    ```
 
-   Ask the read-only MCP resolver for the exact path, then use that returned
-   absolute path for the write:
+   **Path SSOT (required):** call the read-only MCP resolver and **copy the
+   absolute path from its summary text** (hosts often omit structured details):
 
    ```text
    wp_tooling_friction_path({"file":"YYYY-MM-DD-<slug|pr|session>.json"})
+   → summary: tooling-friction path: <absolute-path>
    ```
 
-   The resolver is backed directly by
-   `getSurfacePath("tooling-friction/<file>", "repo", <project-cwd>)`. For
-   human CLI use, the equivalent read-only projection is
-   `wp tooling-friction path --file <file>`. The capture is shared by that
-   repository's worktrees but never written to any checkout. Create parent
-   dirs as needed. If the returned path already exists, choose a unique
-   session/HHMM suffix rather than overwriting it. If the surface cannot be
-   resolved or written, report `tooling-friction: skipped: no state surface`
+   Write only to that absolute path. Do **not** construct a path by hand.
+
+   - `repo-key` is a **16-hex** `repoIdentityV1(git-common-dir)` segment from
+     `repoIdentityV1` under the pure preferred state root — **not** a fleet worktree folder slug such
+     as `github.com-org-repo-<hash>` under `~/.webpresso/worktrees/repos/`.
+   - Scope is always **repo** (shared by every worktree of that git common
+     dir). Never use a worktree-keyed desktop-state surface for captures.
+   - Human CLI equivalent: `wp tooling-friction path --file <file>` (prints
+     the same absolute path on stdout).
+
+   Create parent dirs as needed. If the returned path already exists, choose a
+   unique session/HHMM suffix rather than overwriting it. If the surface cannot
+   be resolved or written, report `tooling-friction: skipped: no state surface`
    and stop; never fall back to a worktree or `.agent/` path.
 
 5. Optional `--promote` or severity `high`/`critical`:  
    `wp tech-debt new "<short title>" --severity <s> --category tooling --status accepted`  
-   Set `promoted_to` to the resulting path.
+   Set `promoted_to` to the resulting path. `new` refuses on a primary-like
+   checkout; from one, pass `--cwd <managed-worktree-path>` (or `--allow-primary`
+   to override deliberately).
 6. Optional one-line `wp_session_capture` pointer to the JSON path — no paste-back walls.
 
 **Rate limit:** at most **one** capture per verify bookend.
@@ -77,9 +85,18 @@ Optional post-land **product signal** for MCP/CLI/hooks/CI pain so Webpresso too
 ## Store path (SSOT)
 
 `wp_tooling_friction_path({"file":"<file>"})` (or the human CLI projection
-`wp tooling-friction path --file <file>`) — a read-only projection of
-`getSurfacePath("tooling-friction/<file>", "repo", <project-cwd>)`, the
-repo-scoped desktop state surface, not a path inside `planning/` or a worktree.
+`wp tooling-friction path --file <file>`) — a read-only projection of the pure
+preferred state root (WP_STATE_ROOT or env-paths data; no writability fallback)
+plus `repoIdentityV1(git-common-dir)` under `tooling-friction/<file>`. This
+intentionally does **not** follow `getStateRoot()`'s temporary fallback when the
+preferred root is unwritable — always copy the resolver output.
+
+The MCP summary embeds the absolute path (`tooling-friction path: …`). Details
+also include `path`, `repoKey` (16-hex), `stateRoot`, `scope: "repo"`, and
+`projectRoot`. Copy the path; never invent one.
+
+**Not** a path inside `planning/`, a checkout, or
+`desktop-state/repos/github.com-…` (fleet worktree layout ≠ desktop-state key).
 
 ## Schema v1
 
@@ -161,6 +178,11 @@ repo-scoped desktop state surface, not a path inside `planning/` or a worktree.
 6. No blueprint errata misuse
 7. No committing desktop-state captures
 8. No auto-open GitHub issues per tip
+9. **Never invent the capture path** — no fleet folder slugs
+   (`github.com-org-repo-*`), no worktree-keyed desktop-state, no guessing
+   under `Application Support` or `~/.webpresso`. Always call
+   `wp_tooling_friction_path` / `wp tooling-friction path` and write to the
+   absolute path it returns
 
 ## Integration
 
@@ -171,7 +193,7 @@ repo-scoped desktop state surface, not a path inside `planning/` or a worktree.
 ## Output (agent reply)
 
 ```text
-tooling-friction: wrote desktop state <state-root>/<repo-key>/tooling-friction/<file>.json
+tooling-friction: wrote desktop state <absolute-path-from-wp_tooling_friction_path>
 findings: 2 (high=1, medium=1)
 promoted: none | tech-debt/...
 ```

package/skills/ultragoal/SKILL.md

@@ -195,11 +195,11 @@ Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer
    the user sets N (the default value lives in `workflow-skills-routing.md`).
    Controller validation evidence is **machine-qa (prior QA phase) + N outside voices**
    (default N=1), not two outside model reviewers at budget 1.
-   Use `wp_review_gate` only for exact-version draft plan approval/auto-promotion.
-   Use advisory `wp_review_run` for implementation/phase outside voice; it never
-   mutates blueprint approval state. A CLI delivery gate is explicit
-   MCP-unavailable compatibility only, not this MCP contract. Use `wp_pr_*` for
-   PR babysit — no
+   Use `wp_review_gate` in the default authoritative mode only for exact-version
+   draft plan approval/auto-promotion. Use the same tool with `mode: "advisory"`
+   for implementation/phase outside voice; it never mutates blueprint approval
+   state on its own. A CLI delivery gate is explicit MCP-unavailable
+   compatibility only, not this MCP contract. 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`.
 
@@ -217,15 +217,16 @@ primary checkout.
 
 ## 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. Use **`wp_review_gate`** only for exact-version draft plan approval/auto-promotion. Use single-shot **`wp_review_run`** for implementation/phase outside voice; it is advisory and never mutates blueprint approval state. CLI delivery gates are explicit MCP-unavailable compatibility only, not this MCP contract.
+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. Use **`wp_review_gate`** in the default authoritative mode only for exact-version draft plan approval/auto-promotion. Use a single-shot **`wp_review_gate`** call with **`mode: "advisory"`** for implementation/phase outside voice; it never mutates blueprint approval state on its own — a later authoritative call may promote a matching advisory approval without re-invoking a provider. 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`. Prefer purpose-matched OpenCode Go first; do not fan out multi-host review swarms.
 
 ### Milestones that require a review
 
-Run `wp_review_gate` only for the plan approval milestone below. Run one
-single-shot `wp_review_run` for implementation/phase milestones; it is advisory
-and does not promote or otherwise mutate blueprint approval state.
+Run `wp_review_gate` (default authoritative mode) only for the plan approval
+milestone below. Run one single-shot `wp_review_gate` call with `mode:
+"advisory"` for implementation/phase milestones; it is advisory and does not
+promote or otherwise mutate blueprint approval state on its own.
 
 | Milestone          | When                                                                                                                             |
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |

package/skills/verify/SKILL.md

@@ -41,18 +41,18 @@ 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`                                                        |
-| PR / CI wait              | `wp_pr_status`, `wp_pr_wait` (not multi-sleep loops)                                    |
-| Release                   | `wp_release_progress` for live Release phases; `wp_release_readiness` for package gates |
-| 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` for plans; `wp_review_run` for implementation                          |
+| 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`                                                                        |
+| PR / CI wait              | `wp_pr_status`, `wp_pr_wait` (not multi-sleep loops)                                                    |
+| Release                   | `wp_release_progress` for live Release phases; `wp_release_readiness` for package gates                 |
+| 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` (authoritative) for plans; `wp_review_gate` with `mode: "advisory"` for implementation |
 
 ## Iron law — evidence before claims
 
@@ -145,17 +145,21 @@ Run the narrowest checks that prove the touched behavior:
 **Before push or PR open/update**, run the pre-push owner end-to-end:
 
 ```text
-wp_ci_preflight({})
+start = wp_ci_preflight({})
+wp_ci_preflight_wait({ runId: start.details.operation.runId })
 ```
 
+The start result is not a gate verdict. Poll again when wait returns
+`in_progress`; only terminal `success` authorizes push or PR mutation.
+
 MCP-unavailable CLI fallback:
 
 ```bash
 wp ci-preflight
 ```
 
-That is fail-fast branch-scoped format → guardrails → typecheck → lint →
-test. Run it after the final commit and make no further worktree or base-ref
+That runs the repository-owned, branch-scoped required-check plan fail-fast.
+Run it after the final commit and make no further worktree or base-ref
 changes before pushing. Agent-kit's `.husky/pre-push` checks the resulting
 exact-state receipt without rerunning the suite after Git opens the remote
 transport; consumer repos may keep pre-push checks user-owned. Do **not** claim
@@ -168,7 +172,7 @@ Rules:
 - Never claim broader correctness than the commands actually proved.
 - 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_ci_preflight` (or the `wp ci-preflight` CLI fallback), fix, then push **one**
+  local `wp_ci_preflight` + `wp_ci_preflight_wait` flow (or the `wp ci-preflight` CLI fallback), fix, then push **one**
   corrective commit — do not burn another full matrix “to check.”
 
 ## Phase 3 — Cross-surface impact scan
@@ -259,17 +263,33 @@ Do not substitute mutable branch names for authority when the audit needs a SHA.
 SSOT: `evaluateSensitiveReviewPolicy` in `src/review/sensitive-review-policy.ts`;
 CI job in `.github/workflows/pr-policy.yml`.
 
-### 2. Sensitive → delivery until satisfied
+### 2. Sensitive → delivery to terminal verdict
 
 When classification is **sensitive**:
 
 - Require delivery review via `risk-review-coverage` / `wp_review_gate`
   (purpose delivery) / qualifying lane approvals for the current
-  `wp-git-diff-v1` subject until `policySatisfied`.
-- Launch **exactly one** `wp_review_gate` delivery attempt with
+  review subject until `policySatisfied` (**approval** or valid same-subject
+  **maintainer-override**). A formal **reject** is a terminal automated-review
+  outcome but does **not** satisfy land policy: Product status stays
+  `incomplete`, Process status stays `sensitive-blocked` until approval or
+  override. Tech-debt is **not** a substitute for delivery approval.
+- Launch **exactly one at a time** `wp_review_gate` delivery attempt with
   `--base-ref <base-sha>` and `--authority-ref <head-sha>`. Do not substitute
   `HEAD` for the authority SHA, and do not relaunch while the same subject has
   an in-progress gate.
+- On formal **reject**: surface the gate `next_action` (`report_delivery_reject`)
+  / reject projection to the user; free-triage against blueprint non-goals;
+  address the findings, then re-review only a changed exact subject. The shared
+  gate permits five distinct rejected delivery subjects by default. Once that
+  budget is exhausted, **do not** set `scope_continue=true` without explicit
+  user authorization; agents must not invent the grant. For plan or delivery,
+  only an operator may request an absolute finite same-slug ceiling through MCP
+  `scope_continue_limit` (10..32); the field still requires
+  `scope_continue=true`. MCP wins over `WP_REVIEW_SCOPE_CONTINUE_LIMIT`; when
+  neither is present, the plan/delivery defaults are 16/10. Machine enforcement
+  does not link successor slugs; creating one to launder or bypass the budget
+  remains procedurally forbidden, as do resets and retry schemes.
 - `Review-skip` is **FORBIDDEN** (`sensitive-review-skip-forbidden`).
 - Completed owner blueprint must be present in the PR
   (`sensitive-no-completed-owner` otherwise).
@@ -289,7 +309,7 @@ When classification is **standard**:
   Must be start-of-line. Process label: `standard-skip`.
 
 - Otherwise obtain **exactly one sequential** advisory outside voice
-  (`wp_review_run` or host skill). Process label: `outside-approved`.
+  (`wp_review_gate` with `mode: "advisory"`, or host skill). Process label: `outside-approved`.
 - At most **one OpenCode Go reviewer** counts unless the user asks for more.
 - Invoke the selected reviewer **once**. Do not probe, retry, or rotate
   providers automatically, and **never** fan out parallel multi-host review
@@ -326,9 +346,25 @@ Never invent a land-now skip. See `land-policy` for the full table.
   `not_found` means there is no active or terminal gate for that subject; refresh
   state and start the gate again instead of continuing to wait.
 - Implementation / delivery approval: for sensitive PRs use `wp_review_gate`
-  purpose delivery on the immutable subject; for standard advisory use
-  `wp_review_run` exactly once with the selected provider and an expected
-  verdict marker. Do not run a separate provider probe.
+  purpose delivery, default authoritative mode, on the immutable subject; for
+  standard advisory use the same `wp_review_gate` call with `mode: "advisory"`
+  exactly once with the selected provider. Do not run a separate provider
+  probe. A later authoritative call on the same subject may promote a
+  matching complete advisory approval to authority with zero provider
+  invocation, unless a completed reject already exists for that content at
+  either stage.
+- `advisory-exhausted` is a terminal outcome with no ledger event and no
+  verdict — treat it as terminal-without-authority. It means this exact
+  digest already used its advisory attempt budget; do not retry the same
+  content or report it as a failure. Change the reviewed content (which mints
+  a new digest) or spend real authoritative budget instead. It is always
+  returned synchronously; no `wp_review_gate_wait` poll is ever needed or
+  issued for it.
+- An advisory gate and an authoritative gate on the same subject cannot run
+  concurrently — unlike the removed `wp_review_run`, an advisory
+  `wp_review_gate` call claims the same active marker an authoritative call
+  does. If a call reports marker contention, serialize the two calls rather
+  than treating contention as an error.
 - Each gate reviewer must return exactly one schema-valid JSON review object;
   never infer a verdict from Markdown. The gate derives approval from typed
   findings: blockers reject, nits approve with nits, and no findings approve.
@@ -356,7 +392,9 @@ If any required check is missing, the correct result is **not done yet**, not a
 
 **Tooling friction (optional):** if this session burned medium+ tokens on MCP/CLI/hooks/CI
 gates (not product code), run `/tooling-friction` once and resolve its capture
-destination with `wp_tooling_friction_path({"file":"<file>"})` (human CLI:
-`wp tooling-friction path --file <file>`). Skip when the path was smooth. If
-the surface cannot be resolved or written, report the skip and never fall
-back to a worktree path. Never blocks land — see the `tooling-friction` skill.
+destination with `wp_tooling_friction_path({"file":"<file>"})` — copy the absolute
+path from the tool summary (human CLI: `wp tooling-friction path --file <file>`).
+Do not invent fleet folder slugs or worktree-keyed desktop-state paths. Skip when
+the path was smooth. If the surface cannot be resolved or written, report the skip
+and never fall back to a worktree path. Never blocks land — see the
+`tooling-friction` skill.