@webpresso/plugin-codex 0.0.4

package/skills/ultragoal/SKILL.md

@@ -0,0 +1,179 @@
+---
+type: skill
+slug: ultragoal
+title: Ultragoal
+status: active
+scope: repo
+applies_to: [agents]
+related: [autopilot, plan-refine, verify, fix, opencode-go]
+created: "2026-07-10"
+last_reviewed: "2026-07-21"
+name: ultragoal
+description: "Run durable multi-blueprint ultragoals through evidence-gated handoffs."
+argument-hint: "<new|status|handoff|run|cancel> [brief]"
+---
+
+# Ultragoal
+
+Use `wp ultragoal` / MCP `wp_ultragoal_*` as the durable controller for work spanning
+one or more blueprints. Prefer this spine over host-local mega-sessions or ad-hoc
+multi-agent swarms.
+
+## Default budgets (override only when the user sets them)
+
+| Budget          | Default                          | Meaning                                            |
+| --------------- | -------------------------------- | -------------------------------------------------- |
+| `concurrency`   | 4 (max 8)                        | Parallel ready tasks / implementer lanes           |
+| `fix_budget`    | 1                                | Pre-existing issues fixable via `/fix` this phase  |
+| `review_budget` | 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
+through `plan-refine` first (or require `force:` only when the user explicitly opts out).
+
+## Tooling map (use these; do not reimplement with Bash)
+
+| Phase                  | Prefer MCP / CLI                                                                       | Purpose                                             |
+| ---------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Create / resume        | `wp_ultragoal_new`, `wp_ultragoal_status`                                              | Durable controller state                            |
+| Isolation              | `wp_worktree`                                                                          | Owner / lane worktrees; never primary as controller |
+| Blueprint read         | `wp_blueprint_list`, `wp_blueprint_get`, `wp_blueprint_context`                        | Ready-set and deps                                  |
+| Blueprint write        | `wp_blueprint_put`, `wp_blueprint_transition`                                          | Spec edits (MCP-only for blueprints)                |
+| Task done              | `wp_blueprint_task_verify` only                                                        | Evidence-gated completion                           |
+| Parallel execute       | `/goal` (autopilot) or ready-queue + host subagents                                    | Max parallel when deps allow                        |
+| Context-light delegate | `wp_session_context`                                                                   | Manifest for subagents (no history paste)           |
+| Continuity             | `wp_session_capture`, `wp_session_search`, `wp_session_restore`, `wp_session_snapshot` | Decisions / resume                                  |
+| Large command / file   | `wp_session_execute`, `wp_session_batch_execute`, `wp_session_execute_file`            | Bounded output + index                              |
+| QA                     | `wp_qa` (or `wp_lint` + `wp_typecheck` + `wp_test`)                                    | Affected quality gates                              |
+| PR / land              | `wp_pr_upsert`, `wp_pr_status`, `wp_pr_wait`, `wp_pr_merge`                            | Open early; exact-head merge only                   |
+| Delivery programs      | `wp_delivery_status`                                                                   | Derive one dispatch/integration action              |
+| Fleet / workers        | `wp_fleet_status`, `wp_worker_tail`                                                    | Multi-session visibility                            |
+| Token gain             | `wp_gain`                                                                              | Optional efficiency check after heavy execute       |
+| Advance loop           | `wp_ultragoal_run`, `wp_ultragoal_handoff`, `wp_ultragoal_cancel`                      | Controller steps only                               |
+
+Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer `wp` >
+`vp` > raw package managers. Never raise timeouts to hide hangs.
+
+## Protocol
+
+1. Create or resume the ultragoal in a **managed blueprint owner worktree**
+   (`wp_worktree` / `wp_blueprint_put`). Never use `main` or the primary checkout
+   as controller.
+2. Print the **ready-set**: tasks whose dependencies are satisfied (from blueprint tools).
+3. Launch up to `concurrency` independent ready tasks in parallel (worktree-isolated).
+   Serialize only when file ownership overlaps or deps require it.
+4. Execute only the current phase handoff; call `wp_ultragoal_run` again after evidence.
+5. Mark tasks done **only** via `wp_blueprint_task_verify` with passing evidence.
+6. **Opportunistic `/fix`:** at most `fix_budget` pre-existing issues per phase, each with
+   named invariant + failing proof. Excess → handoff backlog (do not expand epic).
+7. **Validate / land:** local proof with `wp_qa` / targeted tools; outside review only when
+   merge-ready and within `review_budget` — **exactly one sequential** outside voice unless
+   the user sets N (the default value lives in `workflow-skills-routing.md`).
+   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
+   multi-sleep poll loops; no parallel multi-reviewer stampede.
+8. Stop on `complete`, `cancelled`, blocked guard exhaustion, or `WP_ULTRAGOAL_DISABLE=1`.
+
+The blueprint engine owns task status and approval gates. The ultragoal controller must
+never self-approve, directly mark a task done, bypass review provenance, or mutate the
+primary checkout.
+
+## Failure / cascade
+
+- Hard fail on a task → mark blocked with reason; **cascade-skip** dependents that cannot
+  proceed; continue independent ready work.
+- Lifecycle mutation failure → stop (do not continue on stale plan state).
+- On block: call `wp_ultragoal_handoff` and emit a **≤40-line handoff**: goal, done, blockers,
+  evidence refs (`wp_session_*` ids if any), next 3 commands. Do not paste full transcripts.
+
+## Outside-voice review (required for autopilot)
+
+Autopilot and agent-driven ultragoal loops **must** request an **OpenCode Go** outside-voice review after each **goal/phase milestone**, and must pick the model by purpose. 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.
+
+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.
+
+| Milestone          | When                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Plan gate          | Before `draft` → `planned`, using the exact version returned by `wp_blueprint_put`; approval may auto-promote the same 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) |
+
+Do **not** invent ledger approvals. If OpenCode Go is unavailable or hits a provider-wide usage limit, capture the failure evidence and use Grok on the next invocation (`--provider grok` / `/grok`); do not hop OpenCode families or substitute a forged approval.
+
+### Purpose → model routing (no hardcoding IDs)
+
+Resolve models from the live catalog every time:
+
+```bash
+opencode models opencode-go
+```
+
+**Selection order and the purpose→family mapping live in one place: the committed
+reviewer policy (`packages/workflow-skills/src/opencode-reviewer-policy.ts`),
+rendered into the `opencode-go` skill and drift-gated against it.** Follow that
+skill; do not restate the ordering here. A second copy of a preference list is a
+second thing to update, and the copy that goes stale is the one an agent reads.
+
+Treat a provider-wide usage limit as terminal for every OpenCode Go model in the current review window; do not hop OpenCode families to evade a usage block. Use Grok as the next outside-voice substitute instead.
+
+### Plan gate invocation shape
+
+```text
+wp_review_gate({
+  "project_id": "<project-id>",
+  "slug": "<blueprint-slug>",
+  "expected_version": "bpv1:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "repository_access": "read-only",
+  "auto_promote": true,
+  "provider": "opencode",
+  "model": "<selected-model>",
+  "effort": "medium"
+})
+```
+
+The plan gate has no `purpose` or `target` field. Pass the exact `bpv1:` token
+returned by `wp_blueprint_put`, never a commit hash or `HEAD`. An explicitly
+requested CLI delivery gate is an MCP-unavailable compatibility fallback only.
+If the MCP host returns before a terminal result, poll the same invocation with
+`wp_review_gate_wait`; treat in-progress, not-found, contention, waiter timeout,
+waiter abort, and cancellation as non-verdict observation states. `not_found`
+means no active or terminal gate exists for that subject; refresh state and
+start the gate again instead of spinning a wait loop.
+
+### Honesty rules (non-negotiable)
+
+- Never self-approve or hand-edit `reviews.md` / `review-events.jsonl` / frontmatter approvals to fake OpenCode Go authority.
+- Never mark blueprint tasks done except through `wp_blueprint_task_verify` with real evidence.
+- Never run ultragoal mutations on `main` or a primary checkout; use the managed blueprint owner worktree.
+- Keep every loop bounded and never increase timeouts.
+- When the controller returns `waiting` (`blueprint-promotion`, `approval-gate`, `blueprint-tasks`, …), fix the named gap; do not spin `wp ultragoal run` without progress.
+
+## Tooling-aligned evidence (QA / land)
+
+- **QA phase** prefers **GitHub required checks** for the worktree PR (`wp_pr_status` /
+  `wp_pr_wait` or `gh pr checks --required`) when PR is `OPEN`/`MERGED`, checks green, and
+  PR head matches clean worktree HEAD.
+- If no PR-bound green CI is available, fall back to local **`wp_qa`**.
+- Open a PR early so CI can satisfy QA. Do **not** raise timeouts.
+- **Land** still requires a **MERGED** PR with green required checks bound to the projected
+  source snapshot. Use `/verify --merge-ready` (merge-ready `review_budget`, per
+  `workflow-skills-routing.md`), not default local verify.
+
+## Snapshot / dirty worktree
+
+- Ultragoal ledger appends to blueprint `reviews.md` / `review-events.jsonl` /
+  `review-artifacts/**`.
+- These paths under both `blueprints/**` and monorepo `webpresso/blueprints/**` are
+  **evidence-only dirt** and must not fail `createCleanSourceSnapshot`.
+- Dirty **source** paths (including `_overview.md` task status edits) still fail closed
+  until committed. Use `wp_session_snapshot` before risky branch switches.

package/skills/verify/SKILL.md

@@ -0,0 +1,283 @@
+---
+type: skill
+slug: verify
+title: Verify
+status: active
+scope: repo
+applies_to: [agents]
+related: [testing-philosophy, tph]
+created: "2026-05-07"
+last_reviewed: "2026-07-21"
+name: verify
+description: "Post-implementation quality gate: run checks, TPH audit, cleanup, docs, proof."
+argument-hint: "<target> [--full|--merge-ready] where target is: package|file|plan-slug|all"
+---
+
+# Verify
+
+Post-implementation quality gate. Run after implementation exists, before claiming `done`.
+
+`/fix` owns investigation-if-missing, root-cause analysis, and the minimal
+repair. `/verify` owns the broader question: **is this work actually complete,
+integrated, and free of stale garbage?**
+
+## Modes
+
+| Invocation                       | Outside voice                      | When                           |
+| -------------------------------- | ---------------------------------- | ------------------------------ |
+| `/verify <target>` (default)     | **0**                              | Local completeness / iteration |
+| `/verify <target> --full`        | **0** (broader local gates)        | Full local QA bookend          |
+| `/verify <target> --merge-ready` | **exactly 1** (unless user sets N) | Claiming merge-ready / land    |
+
+Default `/verify` must **not** spawn outside reviewers. That stampede is a known
+token/time failure mode. Merge-ready runs **one** sequential outside voice via
+the preferred skill (`claude` / `codex` / `grok` / one OpenCode Go), then stops.
+
+## Tooling map
+
+| Gate                      | Prefer                                                                                  |
+| ------------------------- | --------------------------------------------------------------------------------------- |
+| Lint / types / tests / QA | `wp_lint`, `wp_typecheck`, `wp_test`, `wp_qa`                                           |
+| Format                    | `wp_format`                                                                             |
+| Audits                    | `wp_audit`, `wp_audits`                                                                 |
+| Blueprint                 | blueprint MCP tools + `wp_audit`                                                        |
+| 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                          |
+
+## Iron law — evidence before claims
+
+No completion claim without fresh verification evidence.
+
+Before saying `done`, `fixed`, `passes`, or `clean`:
+
+1. Identify the command or log that proves the claim.
+2. Run it now, or cite the fresh log from the just-completed run.
+3. Read the exit code and summary — do not infer from partial output.
+4. State the actual result, including the log path when the repo records one.
+5. If another agent made the change, inspect the diff yourself before repeating the claim.
+
+Not sufficient: "should pass", "looks correct", lint-only evidence for runtime claims, or another agent's success report without independent verification.
+
+## Usage
+
+```bash
+/verify <target>
+/verify <target> --full
+/verify <target> --merge-ready
+```
+
+`<target>` is a file path, package name, blueprint slug, or `all`.
+
+Follow the repo's current routing and command surface:
+
+- use MCP `wp_*` / repo-owned quality wrappers first
+- use bounded session-memory tooling for large output
+- reuse fresh logs instead of re-running broad commands just to inspect output
+
+## Folded health dashboard
+
+`/health` is folded into this quality gate. When the user asks for repo health,
+run the available repo facades only as far as needed, then return a concise
+scorecard: score, pass/fail table, top risks, skipped checks with reasons, and
+the next command that most improves confidence.
+
+## Folded testing-philosophy gate
+
+`/tph` is folded into this quality gate. Every `/verify` run must apply the
+Testing Philosophy Helper, not leave test-quality review as an optional separate
+workflow:
+
+1. Load the `tph`/`testing-philosophy` skill guidance before judging changed tests.
+2. Run the repo audit when available:
+
+   ```text
+   wp_audit({"kind":"test-smells"})
+   ```
+
+   Use the global `wp audit test-smells` command only when MCP is unavailable.
+
+3. Treat TPH findings as verification findings: over-mocking, weak assertions,
+   tautologies, implementation-only spy assertions, wrong test placement, or
+   missing integration/E2E coverage can block a `done` or `merge-ready` claim.
+4. If no tests changed, still run or explicitly cite the fresh TPH audit result
+   and state that no test-quality diff review was needed.
+
+## Phase 0 — Scope and evidence map
+
+1. Identify target type (file / package / blueprint slug / all).
+2. Map each claim you plan to make to the exact command or log that proves it.
+3. If the target is a blueprint slug, run the repo's blueprint show/audit surface and record the acceptance boxes that still need proof.
+4. **CI cost / local-first:** treat remote CI as confirmation, not the first
+   debugger. Load `ci-cost-local-first` expectations: no hook skips, no
+   blind `gh run rerun`, Ubicloud for private non-release jobs.
+
+## Phase 1 — Governance gates
+
+Run only the gates that apply to the diff:
+
+- repo SSOT / schema / config changes → the repo's dedicated check
+- docs or markdown changes → the repo's docs / markdown validation surface
+- blueprint target → the repo's blueprint audit surface
+- agent-surface / catalog changes → the repo's agent or catalog audit surface
+
+Hard stop on any failure.
+
+## Phase 2 — Surface verification
+
+Run the narrowest checks that prove the touched behavior:
+
+- `wp_lint` / targeted lint
+- `wp_typecheck` / targeted typecheck
+- `wp_test` / targeted tests
+- `wp_qa`, `wp_e2e`, build / package checks only when the change requires them
+
+**Before push or PR open/update**, run the pre-push owner end-to-end:
+
+```text
+wp_ci_preflight({})
+```
+
+MCP-unavailable CLI fallback:
+
+```bash
+wp ci-preflight
+```
+
+That is fail-fast branch-scoped format → guardrails → typecheck → lint →
+test. Agent-kit itself enforces it from `.husky/pre-push`; consumer repos may
+keep pre-push checks user-owned, so run the command explicitly before pushing.
+Do **not** claim push-ready if preflight failed. Do **not** bypass hooks to ship
+red work.
+
+Rules:
+
+- Prefer MCP `wp_*` over raw underlying tools.
+- Reuse fresh logs / session-memory indexed output if the runner auto-saves them.
+- Never claim broader correctness than the commands actually proved.
+- If the repo documents a "full QA" bookend, reserve `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**
+  corrective commit — do not burn another full matrix “to check.”
+
+## Phase 3 — Cross-surface impact scan
+
+Ask:
+
+- Did the change alter a public/shared export, type, config shape, command, install path, setup path, update path, operator guidance, or generated surface?
+- Do consumers, mocks, fixtures, docs, help text, generated instruction templates, or skill/catalog references still mention the old shape?
+- Does another package, blueprint, or agent surface need to be updated in the same change?
+
+For command-surface, install/setup/update, or operator-guidance changes, explicitly scan affected docs/help/instruction surfaces before proceeding. Include, at minimum:
+
+- CLI help text
+- docs/guides
+- generated instruction templates and checked-in generated instruction copies
+- skill text and catalog references
+
+Hard stop if a shared contract changed and consumers were not updated.
+
+Every session that changes behavior, commands, setup, or operator guidance must
+update every affected doc/help/instruction surface in the same change. Keep
+those doc edits concise and direct.
+
+## Phase 4 — Test quality and behavioral audit
+
+The passing test suite is necessary, not sufficient.
+
+Check that:
+
+- the new or changed tests would fail against the old behavior
+- mocks stay at real external boundaries
+- assertions prove the intended behavior rather than incidental implementation details
+- mixed/partial/error-path coverage exists where the feature demands it
+- UX or operator-facing flows include graceful-degradation coverage when applicable
+
+Run the folded TPH gate for every verification target. At minimum, execute
+`wp_audit` with the `test-smells` kind when available (use global `wp audit
+test-smells` only as the CLI fallback) and inspect changed tests against the
+`testing-philosophy` checklist. Add E2E or integration evidence when the change
+touches user/operator-facing workflows, batch/list behavior, graceful
+degradation, or other fidelity-sensitive paths.
+
+## Phase 5 — Complexity, compatibility, and dead-code sweep
+
+Before claiming done:
+
+- remove stale compat aliases and "temporary" branches introduced by the change
+- verify no suppressions were added
+- verify no production `any` slipped in except an explicitly allowed repo test idiom
+- justify every new exported/helper surface with a real consumer or test
+- run the repo's dead-code / dependency checks when the change broadened public surface or added new files
+
+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.
+
+This phase exists to catch the garbage that often slips in beside otherwise-correct work.
+
+## Phase 6 — Outside-model approval gate (**`--merge-ready` only**)
+
+**Skip this entire phase** for default `/verify` and `/verify --full`. Local
+`done` claims do not require outside voice.
+
+Before claiming **merge-ready**, obtain outside-voice approvals only under this policy:
+
+Default merge-ready policy:
+
+- 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.
+
+Reviewer preference (pick **one** path):
+
+- From Codex → Claude or Grok (else one OpenCode Go).
+- From Claude → Codex or Grok (else one OpenCode Go).
+- From Grok → Claude or Codex (else one OpenCode Go).
+- Prefer skills: `claude`, `codex`, `grok`, or one of `opencode-go` / `qwen` /
+  `deepseek` / `glm` / `kimi` / `minimax` / `mimo`.
+
+Approval evidence requirements:
+
+- Blueprint plan approval: use `wp_review_gate` with the current `bpv1` version.
+  It records the review and promotes an approved draft atomically by default.
+  If the gate is still running or the host wait expires, poll the same exact
+  invocation with `wp_review_gate_wait` until a terminal review outcome is
+  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.
+- 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.
+- `APPROVE-WITH-NITS` is terminal approval when every typed finding is
+  non-blocking. Preserve detailed nits in the artifact or follow-up backlog; do
+  not edit the reviewed subject and rerun the gate just to clear nits.
+- Record as PR comments when a PR exists (model/tool, verdict, reviewed commit).
+- Unavailable reviewer → report the gap and **not merge-ready**. A later explicit
+  invocation may select another reviewer after the terminal result is inspected;
+  never cycle providers automatically or invent approvals.
+
+## Phase 7 — Final completion statement
+
+Report:
+
+- mode used (`local` / `full` / `merge-ready`)
+- what was verified and which `wp_*` commands/logs prove it
+- which docs/help/instruction surfaces were refreshed when guidance changed
+- outside models only if merge-ready (with PR comment links when applicable)
+- what remains intentionally out of scope
+
+When catalog assets 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.