@webpresso/plugin-opencode 0.0.6 → 0.0.7

package/skills/tooling-friction/SKILL.md

@@ -0,0 +1,159 @@
+---
+type: skill
+slug: tooling-friction
+title: Tooling Friction
+status: active
+scope: repo
+applies_to: [agents]
+related: [verify, ultragoal, tech-debt, devex-review, land-policy]
+created: "2026-08-03"
+last_reviewed: "2026-08-03"
+name: tooling-friction
+description: "After land, capture MCP/CLI friction tips (optional; never blocks.)"
+argument-hint: "[--promote] [blueprint-slug|pr-number|session]"
+---
+
+# Tooling Friction
+
+Optional post-land **product signal** for MCP/CLI/hooks/CI pain so Webpresso tooling can improve. Not a land gate. Not a full session debrief.
+
+## Boundary
+
+| Owns                                                 | Does not own                                       |
+| ---------------------------------------------------- | -------------------------------------------------- |
+| Structured friction tips after land-ish success      | Code bugs (`/investigate` → `/fix`)                |
+| Optional promote to tech-debt (`--category tooling`) | Blueprint claim corrections (`blueprints/errata/`) |
+| Local planning-state JSON (gitignored)               | Human DX audits (`/devex-review`)                  |
+| Soft bookend from `/verify` Phase 7                  | Required PR section, finalize/merge blockers       |
+
+## When
+
+- After `/verify` Phase 7 (esp. green or `--merge-ready`) **and** medium+ tooling waste is already recalled
+- Explicit `/tooling-friction` or user asks for tooling papercuts / agent tax feedback
+- Blueprint completed or PR merged **and** gates burned meaningful tokens
+
+## When not
+
+- Work still in-flight (stay in fix/verify)
+- Smooth session with no tooling pain → **silence** (do not invent tips)
+- Product-code root cause unknown → investigate first
+- One-off transient network blips without a product fix
+
+## Workflow
+
+1. **Recall only** — do not re-ingest full CI logs or transcripts.
+2. If zero medium+ findings → stop: `skipped: no tooling friction`.
+3. Emit **1–3** findings (hard cap 8 for schema headroom; prefer ≤3).
+4. Write JSON to:
+
+   ```text
+   .agent/planning/state/tooling-friction/YYYY-MM-DD-<slug|pr|session>.json
+   ```
+
+   Create parent dirs as needed. Path is under the durable planning **state** surface (see `Agents.md`). `.agent/` is gitignored — **never** `git add` captures.
+
+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.
+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.
+
+## Store path (SSOT)
+
+`.agent/planning/state/tooling-friction/*.json` — planning `state/`, not a new top-level under `planning/`.
+
+## Schema v1
+
+```json
+{
+  "schema_version": 1,
+  "captured_at": "2026-08-03T15:00:00Z",
+  "session": {
+    "host": "claude",
+    "session_id": "optional-max-128",
+    "blueprint_slug": "optional",
+    "pr_number": 1239,
+    "branch": "optional-max-200"
+  },
+  "findings": [
+    {
+      "id": "tf-status-ci-skew",
+      "severity": "high",
+      "surface": "pr",
+      "tool": "wp_pr_status",
+      "kind": "friction",
+      "signal": "status_ci_skew",
+      "symptom": "wp_pr_merge blocked while GitHub CLEAN and PR Policy green.",
+      "token_waste": "high",
+      "time_waste_minutes": 25,
+      "recurrence": "session",
+      "suggested_fix": "Align land readiness evidence with PR Policy (body+trailers; git-diff subject).",
+      "evidence_refs": ["pr:1239"],
+      "promoted_to": null
+    }
+  ],
+  "notes": "optional ≤400 chars theme"
+}
+```
+
+### Closed enums
+
+| Field       | Values                                                                                                               |
+| ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| severity    | `low` `medium` `high` `critical`                                                                                     |
+| surface     | `mcp` `cli` `hook` `pr` `ci` `review-gate` `session-memory` `host` `docs`                                            |
+| kind        | `friction` `missing` `docs` `workaround` `incident`                                                                  |
+| signal      | `retry_loop` `schema_confuse` `timeout` `wrong_facade` `missing_capability` `docs_mismatch` `status_ci_skew` `other` |
+| token_waste | `none` `low` `medium` `high`                                                                                         |
+| host        | `claude` `codex` `opencode` `grok` `other`                                                                           |
+| recurrence  | `once` `session` `chronic`                                                                                           |
+
+### Limits
+
+- findings: prefer ≤3 (schema max 8)
+- `symptom` / `suggested_fix`: ≤280 chars
+- `notes`: ≤400 chars
+- `evidence_refs`: ≤5 items × ≤200 chars (run ids, receipt names, `pr:N` — **not** log bodies)
+- `token_waste` bands: none &lt;1k · low 1–5k · medium 5–20k · high &gt;20k or multi-retry (estimate only)
+
+## Few-shot tips
+
+**Good**
+
+- `wp_pr_merge: land readiness disagrees with GitHub CLEAN / PR Policy (status_ci_skew, high)`
+- `wp_review_gate: re-approve after ledger-only commits; subject binding unclear (retry_loop, medium)`
+- `wp_pr_upsert: bare Review model "Grok" fails provider regex; needs "grok reviewer" (schema_confuse, low)`
+
+**Bad**
+
+- Full CI log paste
+- "Tools are confusing sometimes"
+- `suggested_fix: raise the timeout` (forbidden; see no-timeout-as-fix)
+
+## Anti-patterns (iron)
+
+1. No secrets, tokens, `.env`, auth headers
+2. No full logs/transcripts
+3. **Never block land** — missing capture ≠ incomplete
+4. No inventing tips on smooth runs
+5. No timeout-as-fix suggestions
+6. No blueprint errata misuse
+7. No committing `.agent/` captures
+8. No auto-open GitHub issues per tip
+
+## Integration
+
+- **Canonical soft bookend:** `/verify` Phase 7 — if medium+ tooling waste recalled, run once.
+- Other surfaces (ultragoal/delivery): optional cross-link only — do not multi-prompt.
+- Land policy, finalize, and merge tools must not require this skill.
+
+## Output (agent reply)
+
+```text
+tooling-friction: wrote .agent/planning/state/tooling-friction/<file>.json
+findings: 2 (high=1, medium=1)
+promoted: none | tech-debt/...
+```
+
+Or: `tooling-friction: skipped: no tooling friction`

package/skills/ultragoal/SKILL.md

@@ -7,14 +7,20 @@ scope: repo
 applies_to: [agents]
 related: [autopilot, plan-refine, verify, fix, opencode-go]
 created: "2026-07-10"
-last_reviewed: "2026-07-21"
+last_reviewed: "2026-08-03"
 name: ultragoal
-description: "Run durable multi-blueprint ultragoals through evidence-gated handoffs."
+description: "Multi-blueprint ultragoal with budgets. Use for overnight, parallel execute, sleep with stop."
 argument-hint: "<new|status|handoff|run|cancel> [brief]"
 ---
 
 # Ultragoal
 
+## Use when (freeform)
+
+- "ultragoal", "overnight", "go to sleep", "full autopilot" **with** named budgets/stop
+- "spawn many in parallel", multi-blueprint ready-set execution
+- Reject unbound "complete everything while I sleep" without stop condition / budgets
+
 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.
@@ -32,6 +38,105 @@ Reject unbudgeted sleep-mode briefs (“complete all”, “full autopilot”,
 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).
 
+## Executor preflight
+
+`wp ultragoal start` validates every requested host before it persists a durable run or
+permits supervisor worktree allocation. Built-in hosts validate both the executable and the
+CLI grammar Ultragoal invokes; the generic `process` host validates executable availability
+only. An incompatible wrapper fails with `UG_HOST_UNAVAILABLE`, the configured invocation
+path, the missing surface, and its remediation variable. Diagnostics mention the canonical
+target as secondary context only when the invocation path is a symlink.
+
+| Host     | Override variable               |
+| -------- | ------------------------------- |
+| Claude   | `WP_ULTRAGOAL_CLAUDE_COMMAND`   |
+| Codex    | `WP_ULTRAGOAL_CODEX_COMMAND`    |
+| Grok     | `WP_ULTRAGOAL_GROK_COMMAND`     |
+| OpenCode | `WP_ULTRAGOAL_OPENCODE_COMMAND` |
+| Process  | `WP_ULTRAGOAL_PROCESS_COMMAND`  |
+
+Upgrade the installed CLI or point the named variable at a compatible executable. Then
+restart the process that owns the adapter: probe successes and failures are cached by
+canonical executable for that adapter's lifetime. Missing paths are rechecked and symlink
+retargeting is re-probed, but an in-place executable repair still requires an adapter-owner
+restart. Grok execution requires a separately installed and authenticated Grok Build CLI.
+`wp install` does not install or authenticate Grok Build.
+
+Existing `WP_ULTRAGOAL_<HOST>_COMMAND` configurations remain supported; no environment
+variable migration is required. Their executables must satisfy the current semantic probe
+and invocation contract after an upgrade. The generic process host is additive: integrations
+that opt into it configure `WP_ULTRAGOAL_PROCESS_COMMAND` and, when needed, the JSON argument
+array described below.
+
+Start probes each unique requested host concurrently, then reports the first failure in
+requested-host order. A failed preflight occurs before durable run creation, ledger writes,
+supervisor launch, or attempt/worktree allocation. Built-in probes validate the grammar they
+invoke: Codex `exec --json --sandbox workspace-write`, Claude prompt/streaming output/bypass
+permission flags, OpenCode `run --format json --auto`, and Grok headless prompt/streaming
+output/approval/workspace-sandbox flags. Grok also runs an auth-free `inspect --json` check
+against a temporary working directory so invalid sandbox profiles fail before execution.
+
+Preflight does **not** validate authentication, provider quota or billing, network
+reachability, or secrets isolation. Those failures remain runtime/provider concerns.
+
+### Host normalization and recovery
+
+Ultragoal trims and normalizes the default host and per-task `taskHosts` values once when it
+resolves the plan, then persists that normalized mapping. Task IDs are never normalized: a
+per-task entry must use the exact executable task ID. Blank host values, missing task IDs,
+and overrides for controller-only tasks fail with `UG_HOST_CONFIG_INVALID`; an unrecognized
+normalized host fails with `UG_HOST_UNKNOWN`.
+
+An initial host failure still occurs before owner-head lookup, durable run or ledger creation,
+supervisor launch, and worktree allocation. Once a run already exists, the supervisor fills
+only the ready executable tasks that fit the currently free concurrency slots. If one host is
+unavailable, available siblings in that ready slice start and are durably attached to the run;
+the unavailable task gets no attempt or worktree. The supervisor then records its exit and
+reports the first host failure in task order. The `supervisor-exited` record leaves the run
+nonterminal and the attached handles/worktrees recoverable.
+
+After upgrading or overriding the unavailable host, adopt the run. Adoption creates a fresh
+host registry and probe cache, recovers the already attached work, and schedules the task that
+could not start. Do not convert a cached availability failure into a retry attempt or mark an
+otherwise recoverable run terminal.
+
+### Generic process contract
+
+Set `WP_ULTRAGOAL_PROCESS_COMMAND` to an executable. Optional
+`WP_ULTRAGOAL_PROCESS_ARGS_JSON` must be a JSON array of string arguments. Ultragoal appends
+these fixed arguments after the configured arguments; process integrations must accept them:
+
+```text
+--task <task.json> --events <events.jsonl> --responses <responses.jsonl>
+```
+
+The same absolute paths are available as `UG_TASK_PATH`, `UG_EVENTS_PATH`, and
+`UG_RESPONSES_PATH`; `UG_ATTEMPT_ID` and `UG_WORKTREE` identify the attempt and its working
+tree. The executable runs with that worktree as its current directory. It writes one JSON
+object per line to the events file using one of these shapes:
+
+```json
+{"type":"attention","attentionId":"question-1","prompt":"Proceed?"}
+{"type":"response-ack","attentionId":"question-1"}
+{"type":"completed"}
+{"type":"failed","reason":"optional explanation"}
+```
+
+Ultragoal appends responses as JSONL objects with `type: "response"`, the matching
+`attentionId`, `response`, and `createdAt`. The process must emit `response-ack` with that
+identifier after consuming a response. The protocol paths and `UG_*` variables are fixed;
+the configured JSON arguments may add process-specific flags but cannot replace them.
+
+### Execution authority and isolation
+
+Ultragoal worktrees protect git integration boundaries; they are **not** operating-system
+sandboxes. Codex uses its `workspace-write` sandbox. Grok's `workspace` sandbox may read
+anywhere, write in its current directory, `~/.grok`, and temporary directories, and permits
+child-process network access. Claude `bypassPermissions`, OpenCode `--auto` mode, and custom
+`process` executables retain substantial user authority. OpenCode disables automatic updates
+and sharing and denies external-directory access, but those policy settings do not make it an
+OS sandbox. Run Ultragoal only with providers, configuration, and task content you trust.
+
 ## Tooling map (use these; do not reimplement with Bash)
 
 | Phase                  | Prefer MCP / CLI                                                                       | Purpose                                             |
@@ -70,6 +175,8 @@ Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer
 7. **Validate / land:** local proof with `wp_qa` / targeted tools; outside review only when
    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`).
+   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
@@ -171,9 +278,20 @@ start the gate again instead of spinning a wait loop.
 
 ## 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. Use `wp_session_snapshot` before risky branch switches.
+- **Never edit primary.** Ultragoal and locked blueprint mutations refuse
+  primary-like checkouts; planning SSOT lives only in managed owner worktrees.
+- On a **linked managed worktree**, uncommitted `blueprints/**` dirt (review
+  ledgers, `_overview.md` lifecycle, promote/finalize renames) is
+  controller-owned and must not fail `createCleanSourceSnapshot` / block
+  `wp ultragoal run` after task_verify or promotion.
+- On a **primary-like checkout**, only review ledgers/artifacts are ignored;
+  dirty `_overview.md` still fails closed so primary never silently absorbs
+  planning pollution. Product source outside blueprints always fails closed.
+- Committed blueprint documents still participate in the HEAD source snapshot
+  hash (QA/land identity). Commit blueprint + product changes when claiming
+  merge-ready.
+
+## After land (optional)
+
+If MCP/CLI/hooks/CI gates burned medium+ tokens this program, consider
+`/tooling-friction` once. Never required for land complete.

package/skills/verify/SKILL.md

@@ -5,16 +5,22 @@ title: Verify
 status: active
 scope: repo
 applies_to: [agents]
-related: [testing-philosophy, tph]
+related: [testing-philosophy, tph, land-policy]
 created: "2026-05-07"
-last_reviewed: "2026-07-21"
+last_reviewed: "2026-08-03"
 name: verify
-description: "Post-implementation quality gate: run checks, TPH audit, cleanup, docs, proof."
+description: "Post-impl quality gate. Use for verify, merge-ready, land, done. Local=0 outside voice."
 argument-hint: "<target> [--full|--merge-ready] where target is: package|file|plan-slug|all"
 ---
 
 # Verify
 
+## Use when (freeform)
+
+- "verify", "are we done?", "merge-ready", "land", "merge it" (with land-policy)
+- final completeness before push or PR claim
+- **Not** for multi-host review swarms — default local has **0** outside voice
+
 Post-implementation quality gate. Run after implementation exists, before claiming `done`.
 
 `/fix` owns investigation-if-missing, root-cause analysis, and the minimal
@@ -149,10 +155,11 @@ 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.
+test. 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
+push-ready if preflight failed. Do **not** bypass hooks to ship red work.
 
 Rules:
 
@@ -218,26 +225,79 @@ If behavior is already locked and the remaining work is purely anti-slop
 cleanup, route that pass through `ai-deslop` first rather than broadening
 `verify` into a writer lane.
 
+**Default branch when green:** if behavioral proof is green and the diff still
+shows machine-shaped noise, dead wrappers, or elegance debt, run or recommend
+`ai-deslop` on the changed scope before the final done claim.
+
 This phase exists to catch the garbage that often slips in beside otherwise-correct work.
 
 ## Phase 6 — Outside-model approval gate (**`--merge-ready` only**)
 
+**Anti-stampede:** never fan out parallel multi-host reviews. Default local
+verify uses **zero** outside voice. Merge-ready uses **exactly one sequential**
+outside voice unless the user sets N. If you needed "600 reviews", the bug is
+in outside-voice usage — stop and fix the gate, do not multiply reviewers.
+
 **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 approvals only under this policy:
+This phase implements **land-policy M7** (delivery vs advisory). Full land
+language and dual-label contract:
+[`catalog/agent/rules/land-policy.md`](../../rules/land-policy.md).
+
+Before claiming **merge-ready** / land:
+
+### 1. Classify with immutable refs
+
+Run `wp_audit` with `kind: "risk-review-coverage"` using:
+
+- immutable PR **base** SHA
+- immutable **authority** (head) SHA
+- PR-description body (`--pr-body-file`)
+
+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
+
+When classification is **sensitive**:
 
-Default merge-ready policy:
+- 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
+  `--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.
+- `Review-skip` is **FORBIDDEN** (`sensitive-review-skip-forbidden`).
+- Completed owner blueprint must be present in the PR
+  (`sensitive-no-completed-owner` otherwise).
+- Process label when blocked: `sensitive-blocked`. When delivery lane
+  approves: `delivery-approved`.
 
-- 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.
-- Invoke the selected reviewer **once**. Do not probe, retry, or rotate providers
-  automatically, and 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.
+### 3. Standard → skip or one advisory outside voice
+
+When classification is **standard**:
+
+- Prefer a specific trailer when justified:
+
+  ```text
+  Review-skip: SKIP standard-risk; <why ≥8 chars>
+  ```
+
+  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`.
+- 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
+  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 (pick **one** path):
 
@@ -247,7 +307,16 @@ Reviewer preference (pick **one** path):
 - Prefer skills: `claude`, `codex`, `grok`, or one of `opencode-go` / `qwen` /
   `deepseek` / `glm` / `kimi` / `minimax` / `mimo`.
 
-Approval evidence requirements:
+### 4. Dual product/process labels on every land claim
+
+Always emit:
+
+- **Product status:** `complete` | `incomplete`
+- **Process status:** `outside-approved` | `standard-skip` | `sensitive-blocked` | `delivery-approved`
+
+Never invent a land-now skip. See `land-policy` for the full table.
+
+### Approval evidence requirements
 
 - Blueprint plan approval: use `wp_review_gate` with the current `bpv1` version.
   It records the review and promotes an approved draft atomically by default.
@@ -256,8 +325,10 @@ Approval evidence requirements:
   observed; wait timeout/abort/in-progress/not-found are not reviewer verdicts.
   `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 approval: invoke `wp_review_run` exactly once with the selected
-  provider and an expected verdict marker. Do not run a separate provider probe.
+- 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.
 - 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.
@@ -282,3 +353,8 @@ Report:
 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.
+
+**Tooling friction (optional):** if this session burned medium+ tokens on MCP/CLI/hooks/CI
+gates (not product code), run `/tooling-friction` once and write tips under
+`.agent/planning/state/tooling-friction/`. Skip when the path was smooth. Never
+blocks land — see the `tooling-friction` skill.