@webpresso/plugin-antigravity 0.0.0-stage → 0.0.17

package/skills/verify/SKILL.md

@@ -0,0 +1,399 @@
+---
+type: skill
+slug: verify
+title: Verify
+status: active
+scope: repo
+applies_to: [agents]
+related: [testing-philosophy, tph, land-policy]
+created: "2026-05-07"
+last_reviewed: "2026-08-03"
+name: verify
+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
+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
+one `review_gate` delivery gate (or a host review skill), then stops. Pass
+`caller_model` with your own model id and omit `provider`/`model`/`effort`: the
+gate selects the cross-family reviewer and reports it in `policy_selection`.
+
+## Tooling map
+
+| Gate                      | Prefer                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| Lint / types / tests / QA | `lint`, `typecheck`, `test`, `qa`                                                     |
+| Format                    | `format`                                                                              |
+| Audits                    | `audit`, `audits`                                                                     |
+| Blueprint                 | blueprint MCP tools + `audit`                                                         |
+| PR / CI wait              | `pr_status`, `pr_wait` (not multi-sleep loops)                                        |
+| Release                   | `release_progress` for live Release phases; `release_readiness` for package gates     |
+| Large output              | `session_execute` / `batch_execute` / `execute_file`                                  |
+| Continuity                | `session_capture` for verify summary; avoid paste-back walls                          |
+| E2E / act                 | `e2e`, `ci_act` when the change requires them                                         |
+| Outside authority         | `review_gate` (purpose plan or delivery); each new provider verdict is a formal round |
+
+## 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 **at the entry point the consumer or CI actually invokes** — not a narrower one that happens to be handy. If you substituted a narrower entry point, say which, and check the side effect (did the artifact appear?) rather than pass/fail alone.
+3. Read the exit code and summary — do not infer from partial output.
+4. If the claim covers a SET, enumerate it first: state the command, the count it returned, and that every member was addressed. "The one I found" is not the class.
+5. State the actual result, including the log path when the repo records one.
+6. 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, another agent's success report without independent verification, or a guard that asserts a token is _present_ when the claim is that every site was fixed.
+
+## 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 wp MCP tools / 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
+   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:
+
+- `lint` / targeted lint
+- `typecheck` / targeted typecheck
+- `test` / targeted tests
+- `qa`, `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
+start = ci_preflight({})
+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 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. The app repo'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:
+
+- Prefer wp MCP tools 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 `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 `ci_preflight` + `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
+
+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
+`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.
+
+**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.
+
+This phase implements **land-policy M7** (delivery vs outside voice). 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 `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 to terminal verdict
+
+When classification is **sensitive**:
+
+- Require delivery review via `risk-review-coverage` / `review_gate`
+  (purpose delivery) / qualifying lane approvals for the current
+  review subject until `policySatisfied` (**approval**). 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.
+  Tech-debt is **not** a substitute for delivery approval.
+- Launch **exactly one at a time** `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**: record the gate `next_action` (`report_delivery_reject`)
+  / reject projection, triage against blueprint non-goals, address the findings,
+  then re-review only a changed exact subject. The gate counts formal verdicts
+  per slug and purpose, starting with eight rounds.
+  After all allowance is spent, a corrected subject may open one
+  extra lane on an explicitly selected provider and model, including one that
+  already reviewed the lineage. The gate records that grant, adds five formal
+  rounds, and permits at most five distinct provider attempts in the new lane
+  that reach a verdict or an unproven outcome; provider infrastructure failures
+  spend no attempt but are bounded separately at five per lane. The provider and model remain pinned.
+  Once that lane is spent, this blueprint's review lineage is terminal: no
+  gate call on its slug can reopen it, whatever the subject. Re-plan the
+  narrowed scope as a new blueprint with its own plan review.
+  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).
+- Process label when blocked: `sensitive-blocked`. When delivery lane
+  approves: `delivery-approved`.
+
+### 3. Standard → skip or one 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** outside voice: one
+  `review_gate` delivery gate (or host skill). Process label: `outside-approved`.
+- At most **one outside 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: the gate owns it. State `caller_model` (your own model
+id) and omit `provider`/`model`/`effort`; `review_gate` selects a
+cross-family reviewer by capability, current provider limits, and measured
+daily cost, and discloses the choice in `policy_selection`. Do not name a
+reviewer host or model, do not probe provider catalogs, and do not rotate
+providers yourself. A human operator may still name an explicit
+`provider`/`model` override; agents must not.
+
+### 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 `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 `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 / delivery approval: use `review_gate` purpose delivery
+  on the immutable subject, exactly once with the selected provider, for
+  sensitive and standard PRs alike. The gate has one mode: each newly executed
+  provider review that reaches a verdict is one 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 (an approval withheld for
+  incomplete adjudication of prior findings — not all briefed, or a briefed
+  claim still open without a matching finding — grants no authority and
+  spends none). Do not run a separate
+  provider probe.
+- Two gates on the same subject cannot run concurrently — every
+  `review_gate` call claims the subject's active marker. 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.
+- `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 MCP tools 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.
+
+**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 `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.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.