@webpresso/plugin-codex 0.0.4

package/skills/deep-research/SKILL.md

@@ -0,0 +1,258 @@
+---
+type: skill
+slug: deep-research
+title: Deep Research
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: deep-research
+description: "Deep web research with dated credible sources, pro/con synthesis, and project-alignment notes."
+argument-hint: "<subject or question to research>"
+---
+
+<Purpose>
+Deep Research is a multi-phase web research workflow that produces a balanced, citation-backed analysis of a subject. It collects both positive and negative sentiments from credible sources, evaluates alignment with the project's vision and tech stack, identifies 2026 state-of-the-art best practices, and logs the result to `docs/research/` with a date-prefixed filename.
+</Purpose>
+
+<Use_When>
+
+- Evaluating a technology, library, pattern, or product direction
+- Comparing alternatives before making an architectural or product decision
+- The user says "research", "deep research", "investigate", or "what does the community think about"
+- You need a balanced view of trade-offs before recommending something
+  </Use_When>
+
+<Do_Not_Use_When>
+
+- The user wants a quick factual lookup (use WebSearch directly)
+- The user wants codebase exploration (use explore)
+- The user wants a requirements interview (use deep-interview)
+- The answer is already well-established and non-controversial
+  </Do_Not_Use_When>
+
+<Output_Contract>
+A single markdown file written to:
+
+```
+docs/research/{YYYY-MM-DD}-{slug}.md
+```
+
+Where `{YYYY-MM-DD}` is today's date and `{slug}` is a kebab-case summary of the subject.
+
+The file MUST have this frontmatter and structure (see Phase 5 for full template).
+</Output_Contract>
+
+<Steps>
+
+## Phase 0: Scope and Context Load
+
+1. Parse `{{ARGUMENTS}}` into a research subject and any qualifiers (e.g., "for our use case", "vs X").
+2. Derive a short kebab-case slug for the filename.
+3. Read `docs/research/product/VISION.md` (or the project's equivalent — check `docs/` for a vision doc) to load the current vision context. Skip if not present.
+4. Identify the relevant tech stack context by reading project config files (e.g., `package.json` workspaces, `tsconfig.json`, key dependencies) — keep this lightweight, just enough to judge alignment.
+5. Announce the research plan to the user:
+   - Subject
+   - Key questions to investigate
+   - Output path
+
+## Phase 1: Broad Discovery (parallel)
+
+Run **5-8 parallel WebSearch queries** covering different angles:
+
+1. **Overview**: `"{subject} 2026 overview best practices"`
+2. **Positive sentiment**: `"{subject} benefits advantages why use 2026"`
+3. **Negative sentiment / criticism**: `"{subject} problems criticism drawbacks 2026"`
+4. **Community opinion**: `"{subject} reddit hacker news experience production 2026"`
+5. **Comparison / alternatives**: `"{subject} vs alternatives comparison 2026"`
+6. **State of the art**: `"{subject} state of the art latest 2026"`
+7. **(If applicable)** Stack-specific: `"{subject} TypeScript Cloudflare Workers React 2026"`
+8. **(If applicable)** Domain-specific query based on the project's problem space
+
+For each search, record:
+
+- Source URL
+- Source type (docs, blog, forum, official, academic)
+- Key claims or data points
+- Sentiment direction (positive / negative / neutral)
+
+## Phase 2: Deep Dive (sequential, selective)
+
+From Phase 1 results, identify the **5-10 most credible and information-dense sources**.
+
+Use `WebFetch` on each to extract deeper detail. Prioritize:
+
+- Official documentation or announcements
+- Production experience reports (postmortems, migration stories)
+- Benchmark data or technical comparisons
+- Strong critical takes with specific evidence
+
+For each fetched source, extract:
+
+- Specific claims with evidence
+- Sentiment and strength (strong positive, mild positive, neutral, mild negative, strong negative)
+- Credibility assessment (official docs > production experience > blog opinion > forum anecdote)
+
+## Phase 3: Triangulate and Score
+
+1. **Cluster findings** into themes (e.g., "developer experience", "performance", "ecosystem maturity", "production readiness").
+2. **Cross-reference claims**: if only one source makes a claim, flag it as unverified. Claims supported by 2+ independent sources get higher weight.
+3. **Score source credibility** using:
+   - Official docs / specs: high
+   - Production postmortems with data: high
+   - Respected engineering blogs: medium-high
+   - Community forums (HN, Reddit) with detail: medium
+   - Marketing material / vendor blogs: low (note bias)
+   - Undated or anonymous content: very low
+4. **Identify gaps**: what questions remain unanswered? If critical gaps exist, run 1-2 additional targeted searches.
+
+## Phase 4: Vision and Stack Alignment Analysis
+
+Using the project's vision from Phase 0 and the research findings:
+
+1. **Vision alignment**: How does this subject relate to the project's stated mission? Does it help or hinder current priorities?
+2. **Tech stack fit**: How well does this integrate with the existing stack (read `package.json`, key deps, framework choices)? What's the integration cost?
+3. **Trade-off assessment**: Given the project's current stage, what are the most relevant trade-offs?
+4. **Recommendation**: Based on the evidence, what's the suggested path? Be explicit about confidence level.
+
+## Phase 5: Write Report
+
+Write the report to `docs/research/{YYYY-MM-DD}-{slug}.md` using this template:
+
+```markdown
+---
+type: research
+title: "{Title}"
+subject: "{subject}"
+date: { YYYY-MM-DD }
+confidence: { high|medium|low }
+verdict: { adopt|trial|assess|hold|reject }
+---
+
+# {Title}
+
+> One-line summary of the finding.
+
+## TL;DR
+
+3-5 bullet executive summary covering: what it is, key finding, recommendation.
+
+## What This Is
+
+Brief neutral description of the subject being researched.
+
+## State of the Art (2026)
+
+Current best practices, latest developments, where the ecosystem stands today.
+Cite sources inline as [Source Name](url).
+
+## Positive Signals
+
+Evidence-backed reasons in favor. Group by theme.
+Each point should cite its source and note credibility level.
+
+### {Theme 1}
+
+- ...
+
+### {Theme 2}
+
+- ...
+
+## Negative Signals
+
+Evidence-backed criticism and risks. Group by theme.
+Each point should cite its source and note credibility level.
+
+### {Theme 1}
+
+- ...
+
+### {Theme 2}
+
+- ...
+
+## Community Sentiment
+
+What practitioners actually say. Include direct quotes where available.
+Note the balance: if sentiment skews one way, say so explicitly.
+
+## Project Alignment
+
+### Vision Fit
+
+How this relates to the project's current goals.
+
+### Tech Stack Fit
+
+Integration with the project's stack (from `package.json`, framework configs).
+
+### Trade-offs for Current Stage
+
+What matters most given where the project is now.
+
+## Recommendation
+
+Clear recommendation with confidence level and reasoning.
+Include conditions under which the recommendation would change.
+
+## Sources
+
+Numbered list of all sources used, with:
+
+- [N] [Title](url) — type, credibility, sentiment direction
+```
+
+## Phase 6: Present Summary
+
+After writing the file, present to the user:
+
+1. The output file path
+2. The verdict and confidence
+3. A 3-line summary of the key finding
+4. Any critical gaps or caveats
+
+</Steps>
+
+<Quality_Gates>
+
+- Minimum 8 distinct sources cited
+- At least 2 sources per major claim
+- Both positive AND negative signals sections must be substantive (not token)
+- Sources section must include credibility and sentiment annotations
+- Vision alignment section must reference specific project goals (not generic)
+- All inline citations must be clickable links
+- Frontmatter must include confidence and verdict fields
+  </Quality_Gates>
+
+<Verdict_Scale>
+
+- **adopt**: Strong evidence, clear fit, community consensus positive. Use it.
+- **trial**: Promising evidence, worth a bounded experiment. Try it in a limited scope.
+- **assess**: Mixed signals or insufficient evidence. Research more before committing.
+- **hold**: Significant concerns or poor fit. Don't invest now, revisit later.
+- **reject**: Clear evidence against. Don't use this.
+  </Verdict_Scale>
+
+<Tool_Usage>
+
+- `WebSearch` for broad discovery (Phase 1) and gap-filling (Phase 3)
+- `WebFetch` for deep source extraction (Phase 2)
+- `Read` for loading vision and tech stack context (Phase 0)
+- `Write` for the final report (Phase 5)
+- `Agent` with `subagent_type=Explore` if codebase context is needed for alignment analysis
+- Use parallel tool calls wherever searches are independent
+  </Tool_Usage>
+
+<Common_Mistakes>
+
+- Writing a report that's all positive or all negative — always find both sides
+- Citing marketing material as if it were neutral evidence — flag vendor bias
+- Making alignment claims without reading the actual vision doc
+- Using stale search results — always include "2026" in queries
+- Writing the report before triangulating — don't just concatenate search results
+  </Common_Mistakes>
+
+Task: {{ARGUMENTS}}

package/skills/delivery-program/SKILL.md

@@ -0,0 +1,57 @@
+---
+type: skill
+slug: delivery-program
+title: Delivery Program
+status: active
+scope: repo
+applies_to: [agents]
+related: [ultragoal, team, verify]
+created: "2026-07-29"
+last_reviewed: "2026-07-29"
+name: delivery-program
+description: "Run merge-last multi-blueprint programs through a typed delivery branch."
+argument-hint: "<parent-roadmap-slug>"
+---
+
+# Delivery Program
+
+Use this workflow when a typed `parent-roadmap` owns multiple child blueprints:
+
+```yaml
+delivery_branch: delivery/<program>
+delivery_base: main
+child_review_quorum: 1
+final_review_quorum: 1
+```
+
+Child membership comes only from `parent_roadmap`; do not maintain a second list.
+
+## Loop
+
+1. Call `wp_delivery_status({ slug })`.
+2. Treat its `version`, blockers, and exact returned action as the current derived
+   truth. Do not reconstruct state from transcripts.
+3. Dispatch only returned `wp_worktree` actions. Child work starts from the
+   delivery branch and child PRs target that branch.
+4. Integrate at most one child at a time. Recheck status immediately before
+   calling `wp_pr_merge` with the exact returned head SHA.
+5. An `enqueued` merge is not integrated. Call `wp_delivery_status` again and
+   wait for the merged postcondition.
+6. After every child PR is merged, verify the delivery branch and land its final
+   PR to `delivery_base` through the same exact-SHA merge tool.
+
+## Invariants
+
+- Executors do not merge their own PRs or act as their own outside reviewer.
+- Never push directly to the delivery branch or `main`.
+- Never use admin override, auto-merge, branch deletion, or a caller-invented SHA.
+- GitHub head matching is atomic; base matching is not. Preserve the reported
+  pre/post base evidence and rerun status after every mutation.
+- Use `queue_policy: merge_queue` only when policy explicitly requires it and
+  CI has a valid `merge_group` workflow. Queued state remains serialized.
+- Unknown dependencies, unverified completed children, stale heads, wrong bases,
+  path overlaps, missing review evidence, and partial provider state block landing.
+- Provider timeouts and discovery limits return blockers/warnings; do not increase
+  timeouts or bypass guards.
+
+Fallback when MCP is unavailable: `wp pr merge` uses the same exact-SHA service.

package/skills/design-review/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: design-review
+description: "Report-first visual/browser design audit for hierarchy, spacing, consistency, responsive, a11y, and interactions."
+license: MIT
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Design review
+
+Use for live visual QA or design polish requests. For pre-implementation plan critique, use `/plan-design-review`.
+
+## Default behavior
+
+- The `allowed-tools` frontmatter is an audited disclosure for supported hosts;
+  pretool-guard remains the enforced mutation backstop when a host does not prove
+  skill-frontmatter enforcement.
+- Report first; do not edit source unless the user explicitly asks for fixes.
+- Inspect key viewports and states.
+- Capture evidence with browser screenshots or precise observations.
+- Rank findings by user impact and implementation effort.
+
+If fixes are authorized, make small visual changes and verify before/after.

package/skills/devex-review/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: devex-review
+description: "Report-first developer-experience audit for onboarding, docs, examples, CLI help, and time-to-hello-world."
+license: MIT
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Live DX review
+
+Use after or during developer-facing work to test the real user journey.
+
+This is report-only by default. The `allowed-tools` frontmatter is an audited
+disclosure for supported hosts; pretool-guard remains the enforced mutation
+backstop when a host does not prove skill-frontmatter enforcement.
+
+## Evidence to gather
+
+- Docs route or README entrypoint.
+- Install/setup command path.
+- CLI help and error messages.
+- Time-to-hello-world estimate.
+- Browser evidence for docs or local app flows when relevant.
+
+Return a scorecard with blockers, papercuts, screenshots/artifacts when available, and concrete next fixes.

package/skills/fix/SKILL.md

@@ -0,0 +1,174 @@
+---
+type: skill
+slug: fix
+title: Fix
+status: active
+scope: repo
+applies_to: [agents]
+related: [verify, testing-philosophy]
+created: "2026-05-13"
+last_reviewed: "2026-07-21"
+name: fix
+description: "Root-cause fix workflow that runs investigate first when diagnosis or failing proof is still missing."
+argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
+---
+
+# Fix Command
+
+Fix the issue at its root, future-proof, aligned with repo philosophy.
+
+**Arguments**: $ARGUMENTS
+
+This command turns "please fix it well" into an enforceable workflow: diagnose
+first, repair at the owner, prove the repair, and escalate to `/verify` when
+the blast radius is broader than a local fix.
+
+## Tooling map
+
+| Need                   | Prefer                                                                      |
+| ---------------------- | --------------------------------------------------------------------------- |
+| Reproduce / large logs | `wp_session_execute`, `wp_session_batch_execute`, `wp_session_execute_file` |
+| Recall prior evidence  | `wp_session_search`, `wp_session_restore`, `wp_session_retrieve`            |
+| Capture decisions      | `wp_session_capture` (do not paste full reports back as user text)          |
+| Scoped proof           | `wp_test`, `wp_lint`, `wp_typecheck`, or `wp_qa`                            |
+| Audits                 | `wp_audit` / `wp_audits`                                                    |
+| Worktree isolation     | `wp_blueprint_put` / `wp_worktree` — never thrash primary checkout          |
+| PR follow-up           | `wp_pr_status`, `wp_pr_upsert` when landing the fix                         |
+
+## Non-negotiable invariants
+
+1. **Root cause, not symptom.** Trace the failure to the invariant that actually broke. Do not patch callers when the owner is fixable.
+2. **Loud failures, no silent fallbacks.** No default shims, sentinel returns, or catch-and-continue behavior that hides missing config, bad state, or broken boundaries.
+3. **Use the repo's real execution surface.** Prefer MCP `wp_*` tools and repo wrappers over host Bash for search/test/lint. Use bounded session-memory paths for large output.
+4. **Regression proof is mandatory.** Add or strengthen a test or other reliable proof that would fail against the old behavior.
+5. **Raising timeouts is not a fix.** If a timeout fires, investigate the bottleneck. Only raise a bound when the repo already documents that workload and you can cite measurement.
+6. **Zero suppressions, zero papering over.** No lint disables, ts-ignore, compat aliases, or "temporary" branches to sneak the fix through.
+7. **Minimal correct diff.** Update every consumer of a changed contract in the same change, but do not bundle unrelated cleanup.
+8. **Primary checkout is sacred.** If HEAD is detached, primary is dirty with unrelated work, or you are not on a managed worktree for non-trivial edits → **stop** and move to `wp_worktree` / blueprint owner. Never leave the primary checkout broken.
+
+## Opportunistic fix budget (when called from ultragoal / autopilot)
+
+- At most **`fix_budget` (default 1)** pre-existing issues per controller phase.
+- Each must have: named invariant, failing proof, owning path.
+- If the repair needs its own blueprint or expands epic scope → **handoff backlog**, do not inline.
+- Additional discoveries: list in the final report; do not thrash.
+
+## Protocol
+
+### Step 0a — Worktree preflight
+
+Before editing: confirm you are on a managed worktree or an explicitly allowed branch.
+If the primary checkout is dirty/detached with unrelated state, stop and isolate first.
+
+### Step 0 — Run the investigate phase when evidence is missing
+
+Before editing, check whether the current context already contains all of the
+following:
+
+- a named root-cause hypothesis
+- a failing proof tied to that hypothesis
+- the owning boundary that should be repaired
+
+If any of those are missing, run the `investigate` phase inline first:
+
+- reproduce or capture the failure
+- read the full error site and one nearby working pattern
+- disconfirm cheap alternative explanations
+- produce failing proof
+- stop only when you can name the broken invariant and owner
+
+Do not skip this phase because the fix "looks obvious". If the evidence is not
+there, the investigation work is part of `fix`.
+
+### Step 1 — Reproduce and name the broken invariant
+
+- Run the exact command, test, or user flow that surfaces the failure.
+- Capture the evidence that matters: error text, file:line, exit code, failing assertion, or log path.
+- 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.
+
+If the "issue" is actually several unrelated failures, stop and ask which one to fix first.
+
+### Step 2 — Decide where the fix belongs
+
+State briefly:
+
+- the broken invariant
+- the owner that should enforce it
+- whether the fix changes a public contract
+- which direct consumers must change in the same diff
+
+If the blast radius is broader than the owner + direct consumers, keep going with `/fix` only if the change is still one coherent repair. If the work becomes a broader hardening pass, plan a `/verify` handoff before claiming done.
+
+### Step 3 — Write failing proof first when feasible
+
+- For a reproducible bug, write or strengthen the smallest regression test that fails on the old behavior.
+- Verify that it fails for the right reason before changing production code.
+- If test-first is genuinely infeasible at that boundary, record why and create the nearest reliable proof instead (for example a deterministic integration reproduction, fixture, or logged command).
+
+Do not keep production code written before the test as "reference". If you wrote code first, throw it away and restart from the failing proof.
+
+### Step 4 — Implement the minimal correct fix
+
+- Edit the file or module that owns the invariant.
+- Update every changed consumer in the same diff. No half-migrations.
+- Delete compat shims, dead aliases, and TODO branches made obsolete by the repair.
+- Keep complexity down by extracting helpers instead of nesting conditionals.
+
+### Step 5 — Run scoped verification
+
+Run the narrowest checks that prove the repaired behavior on the real repo surface:
+
+- `wp_test` / targeted tests for the repaired path
+- `wp_lint` / `wp_typecheck` for changed surfaces
+- `wp_qa` only when the blast radius needs the bookend
+- Before push: `wp_ci_preflight` (use global `wp ci-preflight` only when MCP is
+  unavailable). Do not use remote CI
+  re-runs as the primary fix loop (`ci-cost-local-first`).
+
+Rules:
+
+- Prefer MCP `wp_*` over raw host Bash.
+- Reuse fresh logs / session-memory indexed output; do not re-run long commands just to re-read.
+- Read the exit code and summary before making a claim.
+- Never `git push --no-verify` to land an unproven fix.
+
+Escalate to `/verify <target>` (local) or `/verify <target> --merge-ready` when any of these are true:
+
+- the fix crosses packages
+- the fix changes a public or shared contract
+- the fix touched docs, plans, blueprints, or repo SSOT
+- the fix needs dead-code / compat / broad regression review before claiming done
+
+If the repaired behavior is already green but the diff still needs a bounded
+cleanup pass, use `ai-deslop` before the final verify handoff.
+
+### Step 6 — Report with evidence
+
+Keep it short:
+
+- what invariant broke
+- how the change restores it
+- what proof ran (tests, commands, log paths, exit codes)
+- adjacent issues noticed but intentionally not fixed
+
+## Done looks like
+
+- [ ] Root cause named in one sentence
+- [ ] Fix applied at the owning boundary
+- [ ] Regression proof fails against the old behavior
+- [ ] Minimal code change restores the invariant
+- [ ] Scoped verification passed on the changed surface
+- [ ] `/verify` handoff used when blast radius exceeded a local fix
+- [ ] Report cites evidence, not intent
+
+## Anti-patterns this command refuses
+
+- Fixing the nearest symptom while leaving the real invariant broken
+- Catching an error and returning a sentinel to "keep things moving"
+- Raising a timeout, retry count, or polling interval instead of finding the bottleneck
+- Adding a deprecated alias instead of updating consumers
+- Introducing `any`, suppressions, or lint disables to unblock the fix
+- Bundling unrelated refactors with the repair
+- Claiming done from intuition, partial output, or another agent's success message
+- Writing a planning/doc artifact when the user asked for a fix

package/skills/grok/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: grok
+description: "Grok outside-voice review."
+license: MIT
+---
+
+Use for bounded Grok Build outside-voice review.
+
+- One bounded review invocation per request.
+- No fan-out, probe, retry, account rotation, or provider switch unless the user sets `review_budget`/`N` > 1.
+- Use `wp_review_run` unless MCP is unavailable.
+- Grok review is prompt-only: gather diff excerpts and verification yourself;
+  pass that supplied artifact to Grok.
+- Call `wp_review_run` exactly once with `repository_access: "none"`. The runtime
+  owns the empty execution workspace.
+- The prompt must say "supplied artifact text only", "do not inspect a
+  workspace", "do not announce future work", and require a final `VERDICT:` line.
+
+```jsonc
+{
+  "prompt": "You are doing a bounded advisory code review of the supplied artifact text only. Do not inspect a workspace. Do not announce future work. <diff excerpts + verification + questions>. Final line must start with VERDICT:",
+  "provider": "grok",
+  "repository_access": "none",
+  "skipProbe": true,
+  "stage": "review",
+  "expectedMarker": "VERDICT:",
+}
+```
+
+`wp_review_gate` is plan-only exact-version draft approval/auto-promotion.
+Implementation/phase review uses advisory `wp_review_run` and never mutates
+blueprint approval state. CLI delivery gates are MCP-unavailable compatibility only.

package/skills/hooks-doctor/SKILL.md

@@ -0,0 +1,78 @@
+---
+type: skill
+slug: hooks-doctor
+title: Hooks Doctor
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: hooks-doctor
+description: "Webpresso hook/plugin doctor: verify install health and debug broken hooks or plugin integration."
+argument-hint: "[--skip-mcp]"
+allowed-tools:
+  - Bash
+---
+
+# Hooks Doctor
+
+Verify the webpresso plugin hooks installation is healthy. Run this first when:
+
+- A hook seems not to be firing
+- The plugin was just installed or updated
+- Claude Code can't find expected tools
+- Any plugin integration issue arises
+
+## Running the Check
+
+Run the doctor command directly:
+
+```
+wp hooks doctor
+```
+
+Or skip the MCP server check (for CI environments):
+
+```
+wp hooks doctor --skip-mcp
+```
+
+## Interpreting Results
+
+Each check prints `[x]` (pass) or `[ ]` (fail) with a detail line:
+
+```
+[x] pretool-guard
+[x] post-tool (lint-after-edit)
+[x] stop (qa-changed-files)
+[x] guard-switch
+[x] sessionstart
+[x] test-quality-check
+[x] plugin.json integrity
+[x] MCP server liveness: MCP server already running (sentinel found)
+```
+
+## 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                          |
+
+After fixing, re-run `wp hooks doctor` to confirm.
+
+## How It Works
+
+The doctor runs five categories of checks:
+
+1. **Bin existence** — each hook binary exists at the expected `dist/esm/hooks/...` path
+2. **Executable bit** — bins have execute permission (skipped on Windows)
+3. **stdin response** — interactive hooks (`pretool-guard`, `guard-switch`, `sessionstart`) respond to `{}` input with valid JSON and exit 0; fire-and-forget hooks (`lint-after-edit`, `qa-changed-files`) exit 0
+4. **plugin.json integrity** — adapter manifest exists, has required fields, and all referenced bins exist on disk
+5. **MCP server liveness** — spawns the MCP server and sends a `tools/list` JSON-RPC request; times out at 5s (soft-fail — warning only, does not fail the overall check)
+
+If `isMcpReady()` detects a live MCP sentinel, the MCP check fast-passes without spawning.