@webpresso/agent-kit 0.21.0

package/catalog/agent/rules/cmd-execution.md

@@ -0,0 +1,121 @@
+---
+type: rule
+slug: cmd-execution
+title: Command Execution Rules
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+paths: 
+  - '**/*'
+---
+
+# Command Execution Rules
+
+## BOOKEND Rule: Full QA Runs Exactly Twice
+
+The full QA pipeline (e.g. `webpresso project check`, `pnpm qa`, `turbo run check`) is a
+**bookend command** — run it once at the START and once at the END. Never in
+between.
+
+```
+START:  qa command              → captures baseline (minutes)
+MIDDLE: scoped commands only    → fast iteration (seconds each)
+END:    qa command              → final verification (minutes)
+```
+
+### Scoped Commands (Use These In Between)
+
+Use the narrowest scope that proves your change:
+
+| Concern    | Scoped form                          |
+| ---------- | ------------------------------------ |
+| Lint       | `lint --file <paths...>` / `--package <name>` |
+| Tests      | `test --file <paths...>` / `--package <name>` |
+| Typecheck  | `typecheck --package <name>`         |
+
+When this repo exposes the webpresso quality MCP/CLI surface, prefer
+`wp_qa`/`wp_lint`/`wp_typecheck`/`wp_test` leaves (or the equivalent wrapped
+`wp qa` surface) for local-dev agent runs. Their compact output filters return
+summary-first payloads with `failures`, `tier`, `bytes`, and `tokensSaved`, so
+agents can reason over the error set without dumping full test/lint logs into
+context. Use `wp err <cmd>` only for ad hoc commands that do not yet have a
+specific wrapper; it strips non-failure-looking lines and preserves the
+subcommand exit code.
+
+**Multi-target:** `--file` and `--package` typically accept multiple
+space-separated values. Check your repo's task runner for the exact flag
+surface.
+
+### Log Files
+
+If the repo's task runner saves output to timestamped logs, treat the log file
+as the source of truth. Re-reading a log is always cheaper than re-running the
+command.
+
+Common conventions:
+
+- One log per command invocation
+- QA runs may split into several stage logs (root checks, typecheck, test)
+- Log path is displayed after the command completes
+
+Do not assume the newest log alone is the source of truth. Check related
+stage logs and confirm progress with file `mtime`/size changes. If logs are
+unchanged, verify whether the underlying process is still alive before
+treating the run as stalled.
+
+**Critical:** Read the log file after completion. Never re-run to check
+results.
+
+**Forbidden:** Never pipe quality commands (e.g., `test | grep`). Piping
+breaks auto-logging and hides real output.
+
+## Formatting
+
+Use the `wp_format` MCP tool, `wp format`, or the repo script through
+`vp run format`. Do not present raw TypeScript/Bun source-entrypoint commands as
+agent-facing fallbacks; those belong inside source-level tests only. **Never
+invoke `oxfmt` directly without the correct flags** — it requires
+`--ignore-path .gitignore` to skip `.prettierignore` (which contains `*` and
+silently excludes every file), and the binary lives in `node_modules/.bin`, not a
+global install.
+
+If `wp_format` is unavailable, the correct direct invocation is:
+
+```bash
+cd <repo-root> && ./node_modules/.bin/oxfmt --write --ignore-path .gitignore
+```
+
+## Other Rules
+
+- MCP tools are the primary agent-facing surface when available. If no MCP tool
+  exists for the operation, use the repo-owned wrapper command.
+- Agent-facing commands should use MCP tools, `wp ...`, or repo scripts through
+  `vp run ...`. The raw TypeScript/Bun CLI entrypoint is an implementation
+  detail, not an instruction surface for users or agents.
+- Package-manager/runtime wrapper chains such as Corepack, `vp exec`/`vp dlx`,
+  pnpm `exec`/optional exec, `npm exec`/`npx`, `yarn exec`/`yarn dlx`, `bunx`,
+  and TypeScript runtimes do not make quality tools or repo source entrypoints
+  agent-facing. Use the matching MCP tool such as `wp_test`, `wp_lint`, or
+  `wp_e2e`.
+- Secret-touching source entrypoints such as CI act runners must go through a
+  secret-aware MCP wrapper or be blocked until one exists. They should reuse the
+  repo secret-provider gate and must not ask agents to call `doppler` or
+  `infisical` directly.
+- Use the `WP_` environment variable namespace for webpresso CLI behavior. For
+  update checks, the opt-out is `WP_SKIP_UPDATE_CHECK=1`.
+- Audit commands are `wp audit <kind>` or MCP `wp_audit`; do not invent a
+  separate generic agent subcommand namespace.
+- Always use the repo-owned command wrappers (`just`, `pnpm`, `turbo`, etc.)
+  for repo-owned workflows. Do not invoke underlying tools directly when a
+  wrapped recipe exists.
+- If you are about to run `vitest`, `test`, `lint`, `typecheck`, `build`,
+  `qa`, `e2e`, or repo CLIs directly through a package manager, stop and look
+  for the wrapped recipe first.
+- Prefer the repo's recipe surface over raw package-manager execution when
+  the repo expects a wrapped CLI invocation.
+- Never pipe quality commands at all — they typically auto-log (and piping
+  may be blocked by pretool hooks). Use compact wrappers such as `wp err`
+  instead of piping through `grep`/`tail`.

package/catalog/agent/rules/context-mode-routing.md

@@ -0,0 +1,64 @@
+---
+type: rule
+slug: context-mode-routing
+title: Context-Mode Tool Routing
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+paths: 
+  - '**/*'
+---
+
+# Context-Mode Tool Routing
+
+Fallback-only note: if SessionStart already injected `WP_ROUTING_BLOCK`, or the
+context-mode plugin already injected its own ctx_* guidance, follow that and do
+not duplicate it. This rule exists to preserve the same routing in plain repo
+contexts where no injected routing block is present.
+
+Use `ctx_*` MCP tools (context-mode) instead of raw Bash/Read for any operation
+that produces or processes large output. Keeps the context window clean.
+
+Agent-kit owns `wp_*` dev-workflow routing. If context-mode is installed, it
+owns `ctx_*` routing nudges; webpresso should not duplicate them in
+SessionStart guidance.
+
+## When to use ctx_* tools
+
+| Trigger | Tool |
+| --- | --- |
+| Running tests, lint, typecheck, qa, audit | `wp_test`, `wp_lint`, `wp_typecheck`, `wp_qa`, `wp_audit` |
+| Shell commands producing >20 lines | `ctx_execute` or `ctx_batch_execute` |
+| Multiple commands + searches in one shot | `ctx_batch_execute` |
+| Searching previously indexed content | `ctx_search` |
+| Fetching web pages / remote docs | `ctx_fetch_and_index` |
+| Log analysis, data processing, computation | `ctx_execute` / `ctx_execute_file` |
+
+## Hard rules
+
+- **Never** use raw `Bash` for commands that produce >20 lines — use `ctx_execute`.
+- **Never** use `WebFetch` — use `ctx_fetch_and_index`.
+- **Never** use `Read` for large-file analysis — use `ctx_execute_file`.
+- `Bash` is for: `git`, `mkdir`, `rm`, `mv`, navigation only.
+- `Read` is for: files you intend to immediately `Edit`.
+
+## Think in code
+
+When `ctx_batch_execute` commands produce data to analyze, count, compare, or
+transform — add a JS processing step that `console.log()`s only the answer.
+Never pull raw output into context to reason over it manually.
+
+## Forbidden alternatives (use wp_* instead)
+
+`webpresso project test`, `pnpm test`, `webpresso project lint`, `webpresso project check`, `vitest`, `oxlint`, `tsc`
+
+## Ownership boundary
+
+- webpresso owns `wp_*` dev-workflow routing and MCP-shaped deny wording
+- context-mode owns its own `ctx_*` nudging when that plugin is installed
+- rtk owns `rtk *` shell-tool filtering for the long-tail command surface
+- this rule is fallback-only; it should not compete with SessionStart routing
+- `.omx` is runtime/state, not a direct hook surface

package/catalog/agent/rules/engineering-principles.md

@@ -0,0 +1,42 @@
+---
+type: rule
+slug: engineering-principles
+title: Engineering Principles
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - package-conventions
+  - pre-implementation
+created: '2026-05-26'
+last_reviewed: '2026-05-26'
+---
+
+# Engineering Principles
+
+Use these as design filters before adding code, abstractions, packages, or
+process. They are guardrails, not slogans.
+
+## Core filters
+
+- **DRY:** remove real duplication after the second concrete use. Do not invent
+  shared abstractions for hypothetical future callers.
+- **SOLID:** keep responsibilities narrow, dependencies pointed inward, and
+  extension seams explicit. Prefer existing interfaces and module boundaries
+  over new framework layers.
+- **YAGNI:** do not add config knobs, adapters, packages, extensibility points,
+  or migration layers until a current task needs them.
+- **KISS:** choose the smallest readable implementation that preserves behavior
+  and passes tests. Prefer deletion and existing utilities before new code.
+
+## Planning and review gate
+
+Before approving or implementing a plan, verify:
+
+- the change solves the stated user/product need without speculative scope;
+- each new abstraction has at least two concrete users or a hard boundary need;
+- each new dependency replaces more code/risk than it adds;
+- the task can be explained in one direct sentence;
+- tests prove behavior rather than implementation ceremony.
+
+If a plan fails this gate, simplify it before execution.

package/catalog/agent/rules/extraction-parity.md

@@ -0,0 +1,157 @@
+---
+type: rule
+slug: extraction-parity
+title: Extraction parity — byte-identity + mutation-score verification
+status: active
+scope: repo
+applies_to: [agents, humans]
+related: [blueprint-scoping]
+created: '2026-05-11'
+last_reviewed: '2026-05-11'
+---
+
+# Extraction parity — byte-identity + mutation-score verification
+
+Applies to any blueprint that claims to be a **pure relocation** (moving code
+between packages without behaviour changes), including:
+
+- **Fold blueprints** — absorbing one package into another (e.g. folding
+  `@webpresso/quality-engine` into `webpresso`).
+- **Extraction blueprints** — splitting a module out of a monorepo into a
+  standalone public package.
+- Any task annotated with "zero behaviour change", "pure move", "rename only",
+  or equivalent.
+
+Without an explicit evidence bar, these claims are unverifiable. This rule
+establishes the bar.
+
+---
+
+## 1. Byte-identity check (source parity)
+
+Run a recursive diff between the old source tree and its new location
+immediately after the relocation lands:
+
+```bash
+diff -ru <old-src-dir> <new-src-dir>
+```
+
+**Expected result:** empty output, exit code 0.
+
+Any line starting with `+` or `-` (excluding whitespace-only lines) is a
+candidate difference. Classify each one before marking the task DONE.
+
+### Acceptable diff categories
+
+The following changes do **not** invalidate a pure-relocation claim, but each
+line must be listed in the blueprint task with its category:
+
+| Category | Example |
+| --- | --- |
+| Import path updates | `@scope/old-package` → `@scope/new-package` |
+| Subpath alias changes | `@workspace/utils` → `@webpresso/runtime/utils` |
+| Shebang line adjustments | `#!/usr/bin/env node` unchanged; path to bin updated |
+| `package.json` name / version fields | `"name": "old"` → `"name": "new"` |
+
+### Unacceptable without explicit justification
+
+If the diff contains any of the following, the task is **not** a pure
+relocation and the blueprint must document why the change was intentional:
+
+- Logic changes in production `.ts` / `.js` source files
+- Test removal, test weakening, or assertion changes
+- Export surface changes (added / removed / renamed exports not already
+  documented in the blueprint's API-delta section)
+- Dependency additions or removals not driven by a package rename
+
+If you cannot justify a diff line in one sentence, treat it as an unintended
+behaviour change and revert it before proceeding.
+
+---
+
+## 2. Mutation-score parity check (test quality)
+
+A relocation that silently drops coverage defeats the purpose of moving code
+with its tests. Capture a Stryker baseline before the move and verify the score
+is preserved afterward.
+
+```bash
+# Step 1 — capture baseline in the old location (before relocation)
+pnpm test:mutation 2>&1 | tee /tmp/stryker-old.txt
+# Note the final "Mutation score" line, e.g. "Mutation score: 87.50%"
+
+# Step 2 — after relocation, run the same suite in the new location
+pnpm test:mutation 2>&1 | tee /tmp/stryker-new.txt
+# Note the final "Mutation score" line
+```
+
+If the repo uses a JSON reporter instead:
+
+```bash
+vp exec vitest run --config vitest.stryker.config.ts --reporter=json \
+  > /tmp/stryker-old.json   # before
+vp exec vitest run --config vitest.stryker.config.ts --reporter=json \
+  > /tmp/stryker-new.json   # after
+```
+
+**Acceptance threshold:** new score ≥ old score − 2 (two-point tolerance
+accounts for statistical variance in survivor sampling).
+
+A drop larger than two points signals that tests were lost or weakened during
+the move. Investigate and restore coverage before marking the task DONE.
+
+---
+
+## 3. Acceptance criteria template
+
+A blueprint task that claims parity DONE must cite all three items:
+
+```markdown
+**Parity evidence:**
+- `diff -ru <old-src-dir> <new-src-dir>` output:
+  - [ ] Empty (full pass), OR
+  - [ ] Non-empty — listed below with category justification:
+    - `<diff line>` — acceptable: import path update (`@old` → `@new`)
+- Mutation score: **before XX.XX% → after YY.YY%** (Δ = Z pts)
+  - [ ] New score ≥ old score − 2 ✓
+- Any unacceptable diff lines addressed:
+  - [ ] None found, OR  [ ] <line> — reverted / justified: <reason>
+```
+
+---
+
+## 4. How to apply in a blueprint
+
+Add a dedicated task to the blueprint that runs these checks after the
+file-move task completes:
+
+```markdown
+#### Task N.M: Verify byte-identity and mutation-score parity
+- [ ] Run `diff -ru <old-src-dir> <new-src-dir>` — output must be empty or
+      contain only acceptable-category lines (see `extraction-parity` rule).
+- [ ] Capture mutation score before relocation; confirm new score ≥ old − 2.
+- [ ] List every non-empty diff line with its category justification in this
+      task. Unacceptable lines must be reverted before this task closes.
+- [ ] Paste parity evidence block (template from `extraction-parity` rule).
+```
+
+Reference in the blueprint overview:
+
+```markdown
+**Verification standard:** byte-identity + mutation-score parity
+(see `catalog/agent/rules/extraction-parity.md`).
+```
+
+---
+
+## Why this rule exists
+
+Task 1.4 of the `fold-webpresso-quality-engine-into-webpresso`
+blueprint first applied this pattern. Without it, "pure relocation" was an
+unchecked claim — the diff step caught an import-path inconsistency that would
+otherwise have shipped silently. Codifying the bar here means future fold and
+extraction blueprints inherit it rather than re-derive it.
+
+The two-point mutation-score tolerance is intentional: Stryker sampling is
+non-deterministic across runs; a tolerance tighter than two points produces
+false negatives on large suites.

package/catalog/agent/rules/generated-code-governance.md

@@ -0,0 +1,87 @@
+---
+type: rule
+slug: generated-code-governance
+title: Generated Code Governance
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+paths: 
+  - 'schema/**/*.yaml'
+  - '.generated/**'
+  - 'apps/**/generated/**'
+last_updated: 2026-04-22
+---
+
+# Generated Code Governance
+
+## Source of Truth
+
+- Generated artifacts from declarative schema files live under a single
+  checked-in output root (commonly `.generated/` or `@myorg/generated`).
+- The root `package.json` inside that output directory is a tracked workspace
+  package stub — keep it, do not treat it as a regenerated payload.
+- Authored truth stays in the declarative schema directory (e.g. `schema/`,
+  `entities/`) and generator source files.
+- Never create duplicate package-local or app-local generated mirrors, and
+  never edit generated files directly.
+
+## Frontend Codegen Source of Truth
+
+Entity / schema declarations typically own:
+
+- Route configuration (app, layout, paths)
+- UI hints (list / detail / form)
+- Edit / delete capabilities derived from the permissions block
+
+## Commands
+
+Use your repo's wrapped recipes for regeneration. Typical surface:
+
+- Full regeneration (all emitters)
+- ORM / database schema only
+- Runtime artifact fragments only
+- Schema validate (static + runtime)
+- Schema apply (push + validate + apply)
+- SDK only
+- Frontend pages / hooks
+- Frontend drift check
+
+Wire these to your task runner of choice (`just`, `pnpm`, `turbo`, make). The
+rule that matters is that **there is exactly one way to regenerate each
+emitter**, and agents use it.
+
+## Import Rules
+
+Prefer the package export surface of the generated package:
+
+```
+✅ @myorg/generated/frontend/entities
+✅ @myorg/generated/frontend/routes/*
+✅ @myorg/generated/frontend/nav/*
+✅ @myorg/generated/frontend/hooks/*
+✅ @myorg/generated/frontend/query-keys
+✅ @myorg/generated/config/*
+✅ @myorg/generated/runtime/*
+✅ Declare @myorg/generated in `dependencies` when a package or app imports
+    it directly
+```
+
+```
+❌ Package-local mirrors such as packages/**/src/generated/frontend/**
+❌ App-local generated/ folders or codegen paths outside the canonical
+    generator outputs
+❌ Deep relative imports into the generated root from normal source files
+❌ tsconfig.paths / Vite aliases / Vitest aliases that remap
+    @myorg/generated/*
+❌ Editing generated frontend routes or hooks directly
+```
+
+## Enforcement
+
+- Generation runs in deploy / dev setup scripts.
+- Emitters live in one clearly-named package (e.g. `@myorg/schema-engine`).
+- Pre-commit and CI should catch drift between authored source and checked-in
+  generated output.

package/catalog/agent/rules/gstack-routing.md

@@ -0,0 +1,90 @@
+---
+type: rule
+slug: gstack-routing
+title: gstack routing — lane 4 interactive/browser workflows
+applies_to:
+  - agents
+  - humans
+created: '2026-05-11'
+last_reviewed: '2026-05-11'
+---
+
+# gstack routing — lane 4: interactive/browser workflows
+
+Fallback-only note: if SessionStart already injected `WP_ROUTING_BLOCK`, or
+any other routing block is already present, follow that and do not duplicate
+it. This rule exists to preserve the same routing in plain repo contexts.
+
+gstack owns interactive/browser workflows: slash-skill invocation
+(`/qa`, `/ship`, `/review`, `/investigate`, `/browse`, `/plan-ceo-review`,
+etc.), AskUserQuestion-gated decisions, browser automation, and design
+tooling. It is **lane 4** in the webpresso ownership model:
+
+| Lane | Owner | Surface |
+| ---- | ----- | ------- |
+| 1 | webpresso | `wp_*` dev-workflow (blueprint execution, audits, quality) |
+| 2 | context-mode | `ctx_*` (context reduction, knowledge-base indexing) |
+| 3 | rtk | shell-tool output filtering for non-quality-engine commands |
+| **4** | **gstack** | **interactive/browser workflows, skill UX, CEO/design reviews** |
+
+## When to invoke gstack
+
+Use gstack skills when the workflow is:
+
+- **Interactive** — requires AskUserQuestion gates, multi-step human
+  collaboration, or visual review.
+- **Browser-backed** — uses the browse daemon, Playwright, or screenshot
+  capture.
+- **Role-based** — `/plan-ceo-review`, `/plan-eng-review`, `/plan-design
+  -review`, `/qa`, `/ship`, `/investigate` — each skill plays a specific
+  expert role.
+- **Agent-to-browser** — `/browse`, `/design-review`, `/qa-only`, etc.
+
+## When NOT to use gstack
+
+Do not invoke gstack for:
+
+- Running tests, lint, typecheck, or audits → use `wp_test`, `wp_lint`,
+  `wp_typecheck`, `wp_qa`, `wp_audit`.
+- Searching previously indexed content → use `ctx_search`.
+- Shell output filtering → use `rtk`.
+
+## How gstack is installed
+
+gstack is **not bundled or redistributed by webpresso**. It lives at
+`~/.claude/skills/gstack/`, cloned from Garry Tan's repo at
+https://github.com/garrytan/gstack. `wp setup` prints a recommend-install
+line but never clones on the user's behalf.
+
+This is intentional: gstack is Garry Tan's project. Redistributing it
+would bypass the upstream update path and violate the lane-4 boundary.
+
+To install: run `cd ~/.claude/skills && git clone https://github.com/garrytan/gstack`
+and follow the setup instructions.
+
+## Hard rules
+
+- Never implement or replicate gstack skills inside webpresso.
+- Never import gstack internals from `wp` CLI code.
+- Never wire gstack into webpresso's hook chain as a first-class hook
+  (gstack has its own lifecycle; hooks are installed by `./setup --team`).
+- Keep lanes 1-3 (`wp_*`, `ctx_*`, `rtk *`) as independent routing
+  surfaces; lane 4 is advisory, not the primary control surface for
+  dev-workflow operations.
+
+## Ownership boundary
+
+- webpresso owns `wp_*` dev-workflow routing.
+- context-mode owns `ctx_*` nudges when that plugin is installed.
+- rtk owns shell-tool output filtering for the long-tail command surface.
+- **gstack owns lane 4.** webpresso defers to it there; it does not
+  compete, replicate, or absorb it.
+- `.omx` is runtime/state, not a direct hook surface.
+
+## Subprocess coverage note
+
+`wp_*` tools shelling out via `child_process.spawn` own their own
+filtering; `rtk` PreToolUse hook only fires for top-level Bash calls and
+does NOT reach into `wp_*` internals. CLI verbs (`wp <verb>` from a shell)
+ARE rewritten by rtk. gstack skill invocations from within Claude Code
+are NOT filtered by rtk (they go through the Claude Code plugin lifecycle).

package/catalog/agent/rules/no-timeout-as-fix.md

@@ -0,0 +1,90 @@
+---
+type: rule
+slug: no-timeout-as-fix
+title: Raising timeouts is never the fix
+status: active
+scope: repo
+applies_to: [agents, humans]
+related: []
+created: '2026-05-06'
+last_reviewed: '2026-05-06'
+---
+
+# Raising timeouts is never the fix
+
+When a hook, test, request, deploy, fetch, or any other bounded operation hits
+its timeout, **the timeout is the alarm, not the bug**. Raising the bound only
+delays the next failure and silences the diagnostic that would have led to the
+root cause. Investigate WHY it took that long.
+
+This applies — but is not limited — to:
+
+- `hookTimeout`, `testTimeout`, `teardownTimeout` in vitest
+- `setTimeout` / `AbortSignal.timeout` in application code
+- Runtime / compatibility deadline tweaks to dodge a hang
+- HTTP client timeouts, RPC retries, polling intervals
+- "just bump the CI minutes" reactions
+
+## When you see a timeout failure, do this instead
+
+1. **Reproduce deterministically.** Cold cache, fresh process, no warm state.
+   If the failure is intermittent, that's a clue — capture the slow case.
+2. **Profile the actual cost.** What took the time?
+   - Vitest: `--reporter=verbose` to see per-hook duration; check `transform`
+     vs `import` vs `setup` in the run summary.
+   - Bundler / dev-server: clear the bundler cache (e.g. `node_modules/.vite`)
+     and re-run; if cold-cache duration ≫ warm-cache duration, the bottleneck
+     is transform/bundle.
+   - Network calls: log `performance.now()` deltas, check DNS / TLS / TTFB.
+3. **Fix at the source.**
+   - Slow imports → pre-bundle (`optimizeDeps.include` or equivalent), split
+     the module, remove unused re-exports, or eliminate the import path.
+   - Slow tests → reduce setup work, share fixtures across tests, parallelize
+     where safe.
+   - Slow runtime boot → smaller dependency graphs, lazy-load heavy modules,
+     review module-resolution path.
+   - Slow API calls → cache, batch, or move out of the hot path.
+4. **Document what changed.** A code or config diff with a comment that
+   names the actual root cause is the durable artifact. "Bumped to 30s
+   because flaky" is not.
+
+## Acceptable cases for raising a bound (rare)
+
+- The bound was measured against the wrong workload (e.g. unit-default 5s
+  applied to an integration test that legitimately needs 30s of real DB
+  setup). Document the measurement that justifies the new value.
+- The bound came from upstream defaults that don't match this codebase's
+  scale (e.g. a shared config sets `hookTimeout: 120000` for a one-time WASM
+  init — a measured cost). Mirror existing precedent rather than inventing
+  new numbers.
+
+If you cannot point to a concrete measurement that justifies the new bound,
+you are silencing a diagnostic. Don't.
+
+## Why this rule exists
+
+Sessions get burned chasing flakes that were silently retried at higher
+timeouts instead of fixed:
+
+- Tests that "passed at 30s but fail at 10s" turn out to be cold-cache
+  bundler transforms — the right fix is pre-bundling, not a bigger budget.
+- E2E tests where the supervisor is killed by a slow auth call — the call
+  was making a network round-trip that should have been mocked at the test
+  boundary.
+- A hook timing out on schema/engine preload — the right fix is bypassing
+  the preload in tests, not extending the deadline.
+
+In every case, the larger timeout shipped a slower, less reliable test
+suite and hid the real defect for weeks.
+
+## Current repo-specific applications
+
+- **Blueprint MCP discovery:** if `wp_blueprint_projects`, `wp_blueprint_list`,
+  or adjacent resolver paths stall on roots fetches, git worktree probes, or
+  recursive discovery, the fix is to bound those external calls and degrade to
+  partial results + warnings (for example `roots_fetch_timeout` /
+  `project_discovery_timeout`) — **never** to raise the MCP/tool timeout.
+- **Hook runtime failures:** if a Codex hook only fails under a sanitized hook
+  environment, the fix is to make the invoked binaries path-stable (usually
+  absolute-path resolution in setup/scaffolding) — **not** to add retries or
+  larger hook timeouts.