@webpresso/agent-kit 0.21.0

package/catalog/agent/rules/package-conventions.md

@@ -0,0 +1,80 @@
+---
+type: rule
+slug: package-conventions
+title: Webpresso Public Package Conventions
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-28'
+paths: 
+  - '**/*.ts'
+  - 'package.json'
+  - '.npmrc'
+---
+
+# Webpresso Public Package Conventions
+
+These rules apply to this repository and downstream consumers. The canonical
+package identity is `@webpresso/agent-kit`; do not use unscoped `webpresso` as
+the package contract.
+
+## Import hygiene
+
+- **No `../` parent-relative imports.** Use workspace package deps or subpath
+  exports. `import { x } from '../../utils'` is always wrong; find the
+  package that exports it and add it as a dep.
+- **Use `@webpresso/agent-kit/*` subpaths for folded agent config.** Consumers
+  should add `@webpresso/agent-kit` and import subpaths such as
+  `@webpresso/agent-kit/oxlint`, `@webpresso/agent-kit/vitest/node`,
+  `@webpresso/agent-kit/test-preset`, `@webpresso/agent-kit/e2e-preset`,
+  `@webpresso/agent-kit/tsconfig/base.json`,
+  `@webpresso/agent-kit/docs-lint`, `@webpresso/agent-kit/stryker`,
+  `@webpresso/agent-kit/launch`, and `@webpresso/agent-kit/workers-test`.
+  Do not tell consumers to install retired split `@webpresso/agent-*` config
+  packages.
+- **No `.mjs` source files.** Write `.ts` with a Bun/Node shebang or as a
+  plain module. Never convert existing `.ts` to `.mjs`. Config files that a
+  tool requires in `.mjs` are the only documented exception, and only when the
+  tool explicitly rejects `.ts`.
+
+## Package manager
+
+- **Vite+ facade first** — run repo workflows through `vp` (`vp install`,
+  `vp run <script>`, `vp exec <bin>`). Vite+ selects the repo-declared package
+  manager substrate from `packageManager`/lockfiles; do not use `npm`, `npx`,
+  or raw package-manager globals for normal repo operations.
+- The Webpresso package substrate remains `pnpm@11.x`; keep `pnpm-workspace.yaml`
+  and `pnpm-lock.yaml`, but access them through `vp` unless a release procedure
+  explicitly requires the raw package-manager command.
+
+## Publishing & registry
+
+- The canonical package is `@webpresso/agent-kit`.
+- Publish target is the public npm registry (`https://registry.npmjs.org/`).
+- Keep checked-in npm config pointed at the public npm registry; do not remap
+  the `@webpresso` scope to GitHub Packages.
+- Auth belongs only to publish flows. Prefer npm trusted publishing; otherwise
+  use `NPM_TOKEN` in CI/manual publish contexts. Never hardcode tokens or
+  create `.env` files with credentials.
+- `prepublishOnly` builds the package before every publish. If a
+  package outputs a `dist/`, it must have `prepublishOnly: "vp run build"` (or
+  equivalent) so that Changesets publishing always ships built output.
+- Scoped public npm releases must publish with public visibility. Encode that
+  in `package.json#publishConfig.access` unless a deeper release workflow owns
+  the flag explicitly.
+- All public packages are `"type": "module"` — ESM-only output.
+- Run `vp run lint:pkg` (publint / attw) before releasing to catch broken export
+  maps.
+
+## Module format
+
+- Prefer `tshy` for dual CJS/ESM output when broad compatibility is needed;
+  `tsup` for bundled output with full tree-shaking.
+- Exports map (`package.json#exports`) is the contract — never rely on deep
+  path imports that are not listed there.
+
+## Versioning
+
+Version bumps are automated via Changesets. See `changeset-release.md`.

package/catalog/agent/rules/pre-implementation.md

@@ -0,0 +1,44 @@
+---
+type: rule
+slug: pre-implementation
+title: Pre-implementation rules
+status: active
+scope: repo
+applies_to: [agents, humans]
+related: []
+created: '2026-05-06'
+last_reviewed: '2026-05-06'
+---
+
+# Pre-Implementation Rules
+
+Applies before non-trivial implementation (new features, bug fixes with
+unclear repro, refactors). Skip for typos, renames, and one-line fixes.
+
+## Surface Multiple Interpretations
+
+When a request admits more than one plausible reading, list them with rough
+effort/tradeoffs and ask — do not pick silently.
+
+- "Make X faster" → latency, throughput, or perceived speed?
+- "Fix auth" → which symptom? which user flow?
+- "Export data" → which records, which fields, which delivery?
+
+If only one reading is plausible, proceed and state the reading in one
+sentence before editing.
+
+## Define Verifiable Success Criteria
+
+Before editing, state the signal that proves the change is done. Vague plans
+("review and improve", "clean up") are not acceptable.
+
+Acceptable signals:
+
+- A failing test that must pass (preferred for bug fixes)
+- A specific QA command from the consumer repo's command surface that must
+  exit green (e.g. the repo's full QA recipe, or a targeted e2e suite)
+- A reproducible repro step whose observed output changes
+
+For UI changes, the signal is an end-to-end test (Playwright spec or
+equivalent) under the consumer repo's e2e directory, not manual
+click-through.

package/catalog/agent/rules/public-package-safety.md

@@ -0,0 +1,56 @@
+---
+type: rule
+slug: public-package-safety
+title: Public Package Safety
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - package-conventions
+  - repo-restrictions
+created: '2026-05-26'
+last_reviewed: '2026-05-26'
+paths:
+  - 'package.json'
+  - '.npmignore'
+  - '.npmrc'
+  - 'README.md'
+  - 'docs/**'
+  - 'catalog/**'
+---
+
+# Public Package Safety
+
+Treat every publishable package tarball as public, even when today's registry
+or `publishConfig.access` is restricted. A package release is a disclosure
+boundary: only intentional API, documentation, and assets belong inside it.
+
+## Keep out by default
+
+- secrets, credentials, private keys, tokens, and token-shaped fixtures;
+- absolute local paths such as `<absolute-local-path>` or machine-specific
+  cache paths;
+- private repo names, customer/workspace examples, and internal package aliases
+  such as `<workspace-alias>/*` unless they are deliberately public examples;
+- strategy notes, research docs, founder/market context, private roadmaps, and
+  unpublished architecture rationale;
+- raw `src/`, tests, fixtures, snapshots, generated IDE/agent surfaces, and
+  sourcemaps with embedded source unless the package is intentionally
+  open-sourcing that material;
+- helper binaries, subpath exports, or files that are not meant to be durable
+  public API.
+
+## Required release gate
+
+Before any package is made public, or before changing `files`, `bin`, `exports`,
+publish workflow, registry, or catalog assets:
+
+1. Run a dry tarball inspection with the repo's package manager facade or
+   `npm pack --dry-run --json`.
+2. Review the resulting file list as the source of truth for what will ship.
+3. Run the package-surface/secret guardrail available in the repo.
+4. Confirm public `bin`, `exports`, and `files` are intentional API.
+5. Remove or quarantine denied content before publishing.
+
+If the tarball includes a denied class of content, the package is not ready to
+publish. Fix the package surface instead of documenting the leak as acceptable.

package/catalog/agent/rules/repo-restrictions.md

@@ -0,0 +1,175 @@
+---
+type: rule
+slug: repo-restrictions
+title: Repository Restriction Guide
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+paths: 
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.test.ts'
+---
+
+# Repository Restriction Guide
+
+> How restrictions are enforced across the monorepo.
+> When adding a new restriction, follow the enforcement layers below.
+
+## Enforcement Layers (Priority Order)
+
+| Layer                      | Mechanism                                                      | When It Runs                    | Catches                                       |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------- | --------------------------------------------- |
+| **1. Linter**              | Built-in rules + plugins (e.g. oxlint, eslint)                 | `lint`, pre-commit, CI          | Import paths, code patterns, safety, perf     |
+| **2. Pre-commit Hook**     | Husky / repo pre-commit script                                 | Every `git commit`              | Lint, typecheck, drift, quality               |
+| **3. Agent Hooks**         | Agent-tool pretool guard (Claude Code / Cursor / etc.)         | Every Write/Edit in agent tool  | Forbidden commands, test quality, conventions |
+| **4. Agent Instructions**  | `AGENTS.md`, `.agent/rules/*.md`, `.agent/guides/*.md`         | Agent context loading           | Soft enforcement for all AI agents            |
+| **5. CI Workflows**        | `.github/workflows/*.yml` or equivalent                        | PRs and pushes                  | Full QA, security, drift detection            |
+| **6. Boundaries Lint**     | `eslint-plugin-boundaries` or similar tier enforcer            | `lint-boundaries`               | Architectural tier violations                 |
+
+## Import Path Restrictions
+
+Most monorepos benefit from a small set of path restrictions enforced by a
+linter plugin. Typical bans:
+
+### `../src/` Imports → Use `#` (or package subpath)
+
+Within-package deep relative imports into a sibling `src/` tree are brittle;
+they break whenever files move or when the package is consumed by source
+export from another package. Prefer Node.js subpath imports (`#`) that resolve
+via the declaring package's `package.json` `imports` field.
+
+### Cross-Package Relative Imports
+
+`../../other-package/src/foo` imports bypass the package boundary and break
+path resolution across workspaces. Ban them; require the package name.
+
+### `vi.mock()` Relative Paths
+
+`vi.mock('../../services/auth')` breaks when vitest projects use
+`extends: false` or when test files sit at different directory depths.
+Always match the source code's import style.
+
+### `../` Parent Imports → Prefer `#`
+
+Any cross-directory import that reaches outside the current directory
+generally wants a subpath import instead.
+
+### Hardcoded Relative Filesystem Paths in Executable Code / Config
+
+`resolve(__dirname, '../../..')`, `join(import.meta.dirname, './fixture.json')`,
+and `new URL('../../../schema.sql', import.meta.url)` are all brittle. They
+quietly encode file depth into runtime behavior and break when files move,
+bundled output changes shape, or the same module is consumed from a different
+package boundary.
+
+Provide an explicit absolute anchor instead (for example a repo-root helper,
+package-root helper, or runtime-provided absolute base path), then derive child
+paths from that anchor without `./` / `../` traversal.
+
+Prefer the shared `wp audit absolute-path-policy` surface over a consumer-local
+duplicate scanner when the repo has been scaffolded by agent-kit.
+
+## Adding a New Restriction
+
+### Step 1: Choose the Right Mechanism
+
+| What You Want to Ban                        | Use This                                |
+| ------------------------------------------- | --------------------------------------- |
+| Import path pattern (`from 'xxx'`)          | Linter plugin                           |
+| Structural code pattern (AST node matching) | Linter plugin                           |
+| String content in function args             | Linter plugin + agent instructions      |
+| Command execution pattern                   | Agent hooks (forbidden-commands)        |
+| File naming / placement                     | Agent hooks + pre-commit                |
+
+### Step 2: Implement
+
+#### For Linter Plugins
+
+1. Add the rule to an existing plugin or create a new one in a plugin package.
+2. Register the rule in the lint config and add the plugin to the active set.
+3. Add overrides if certain file patterns need exemptions.
+
+#### For Agent Hooks
+
+Edit the pretool-guard validators:
+
+- Add validation logic in a new or existing validator
+- Register it in the pretool runner
+- Scope it to the agent tools that need it
+
+#### For Agent Instructions
+
+Edit the appropriate file:
+
+- `.agent/rules/agent-guide.md` — import / path / schema rules (all agents)
+- `AGENTS.md` — cross-platform agent rules
+- `.agent/guides/agent-guardrails.md` — agent-operational guidance and
+  current repo surfaces
+
+### Step 3: Document
+
+- Update this file with the new restriction.
+- Add examples to agent instructions showing correct alternatives.
+
+## Common Active Restrictions
+
+### Linter Built-in Rules (Always Enforced)
+
+- Zero `any` types
+- Bounded cognitive complexity (e.g. ≤ 8)
+- Ban `alert()` / `confirm()` / `prompt()`
+- Ban TypeScript enums
+- Use let / const (no var)
+- Import cycle detection, duplicate imports
+
+### Linter Plugin Rules (Always Enforced)
+
+**Import hygiene**:
+
+- `no-relative-parent-imports` — ban `../` imports (use `#`)
+- `no-src-path-imports` — ban `../src/` imports (use `#`)
+- `no-relative-mock-paths` — ban `vi.mock('../')` (use `#` or package name)
+
+**Monorepo paths**:
+
+- `no-hardcoded-repo-root` — ban `__dirname` / `import.meta.dirname` + `../../`
+  for repo root
+- `no-cross-package-paths` — ban `__dirname` + traversal into other packages
+
+**Testing quality**:
+
+- `no-weak-assertions` — ban `toBeTruthy()` / `toBeFalsy()` / `toBeDefined()`
+  / `toBeUndefined()` / `toBeTypeOf()`
+- `no-bare-spy-assertions` — ban `toHaveBeenCalled()` without args
+- `no-internal-mocks` — ban mocking internal workspace packages
+- `no-real-timers-in-tests` — ban `setTimeout` in `Promise` constructor
+
+**Code safety**:
+
+- `as-any-audit` — audit unsafe `as any` casts
+- `no-swallowed-errors` — ban catch blocks that only `console.error`
+
+### Architectural Tier Enforcement
+
+Use a boundaries plugin (e.g. `eslint-plugin-boundaries`) or dependency-cruiser
+rules to prevent tier inversions (e.g. feature → app, package → feature).
+
+### Agent Hooks (Agent-Tool Only)
+
+- Forbidden commands (suggest wrapped recipe equivalents)
+- Package import deduplication
+- Test quality validation
+- Blueprint / docs governance
+- File conventions
+
+### Pre-commit Hook (All Developers)
+
+- Format + lint auto-fix
+- Typecheck affected packages
+- Generated file drift detection
+- Schema drift detection
+- Blueprint format validation

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

@@ -0,0 +1,50 @@
+---
+type: rule
+slug: rtk-routing
+title: RTK Tool Routing
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+paths: 
+  - '**/*'
+---
+
+# RTK Tool Routing
+
+Fallback-only note: if SessionStart already injected `WP_ROUTING_BLOCK`, or
+rtk already injected its own `rtk *` 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 `rtk *` for shell-tool output filtering on the long-tail command surface
+that webpresso and context-mode do not own.
+
+## Ownership boundary
+
+- webpresso owns `wp_*` dev-workflow routing and MCP-shaped deny wording
+- context-mode owns `ctx_*` nudging when that plugin is installed
+- rtk owns shell-tool output filtering for the long-tail surface (`git`, `gh`,
+  `kubectl`, `cargo`, `pytest`, `ruff`, and similar non-quality-engine tools)
+- this rule is fallback-only; it should not compete with SessionStart routing
+- `.omx` is runtime/state, not a direct hook surface
+
+## Hard rules
+
+- Never reimplement upstream rtk filters in webpresso.
+- Never wrap the `rtk` prefix behind `wp rtk`.
+- Keep `wp_*`, `ctx_*`, and `rtk *` as independent lanes.
+
+## Lane 4: gstack (interactive/browser workflows)
+
+gstack owns interactive/browser workflows (slash-skill invocation, AskUserQuestion-gated).
+This rule is fallback-only; it should not compete with SessionStart routing.
+Owned by: ~/.claude/skills/gstack/
+
+## 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.

package/catalog/agent/rules/supported-agent-clis.md

@@ -0,0 +1,80 @@
+---
+type: rule
+slug: supported-agent-clis
+title: Supported Agent CLIs (Tier 1 / Tier 2)
+status: active
+scope: repo
+applies_to: [agents, humans]
+related: [package-conventions]
+created: '2026-05-14'
+last_reviewed: '2026-05-14'
+paths:
+  - '**/*'
+---
+
+# Supported Agent CLIs
+
+webpresso ships building blocks for AI coding-agent CLIs. We
+support a fixed set of CLIs at a defined tier. Plans, benchmarks, docs, and
+plugins MUST honor this tier list. Do not add a CLI without tier classification.
+
+## Tier 1 — must work perfectly (P0)
+
+| CLI | Provider model | Why Tier 1 |
+|---|---|---|
+| **Claude Code** (`claude`) | Anthropic | webpresso's native plugin runtime; primary reference consumer uses it |
+| **Codex CLI** (`codex`) | OpenAI (configurable) | Already integrated via `/codex` skill for second-opinion review; widely used by webpresso engineers |
+
+Tier 1 requirements:
+- Per-call token-usage extraction (stream-json or equivalent)
+- Plugin/extension surface with isolatable scope (`--plugin-dir`, etc.)
+- Reproducible session lifecycle (`--no-session-persistence` or equivalent)
+- Tested in CI for every relevant webpresso release
+
+## Tier 2 — fairly well, best-effort (P1)
+
+| CLI | Provider model | Tier 2 caveats |
+|---|---|---|
+| **OpenCode** (`opencode`) | Provider-agnostic (Anthropic, OpenAI, local, etc.) | Session-level token totals only (`-f json` + `opencode stats`); no per-call granularity; cache isolation depends on dispatched provider |
+
+Tier 2 requirements:
+- At minimum: session-level token totals captured
+- Best-effort: per-call attribution if the CLI exposes it
+- Documented degradation in any benchmark/report cell using a Tier 2 CLI
+- May be skipped in CI when prerequisites are missing
+
+## Tier 3 — not supported
+
+Any other agent CLI (Aider, Cursor terminal mode, Gemini CLI, custom tools).
+Plans and docs MUST NOT introduce Tier 3 CLIs without first promoting them via
+this rule. Adding a new tier-3 CLI is a separate decision, not an in-band scope
+expansion.
+
+## Hard rules
+
+- **Plans MUST classify each CLI they reference by tier.** A plan that says
+  "supports Claude, Codex, and Aider" without a tier table is incomplete.
+- **Benchmark reports MUST label every cell with the CLI's tier.** Tier 2 cells
+  show degraded-granularity disclaimers; tier 2 numbers are NOT directly
+  comparable to tier 1 numbers without explicit caveat.
+- **Docs MUST refer back to this rule** rather than re-listing CLIs. If a doc
+  says "supported CLIs", it links here. Single source of truth.
+- **Adding a new tier-1 CLI requires** plan-eng-review approval + integration
+  test coverage + per-call usage extractor.
+- **Promoting tier 2 → tier 1** requires the same gate plus a 1-week sowp test
+  in actual benchmark runs.
+- **Removing a tier-1 CLI** requires CEO-review-level scope decision (it's a
+  product position change).
+
+## Non-goals
+
+- Universal agent-CLI abstraction. We pick winners per tier.
+- Wrapping vendor SDKs. We integrate via CLI subprocess only — keeps our code
+  vendor-agnostic and dependency-free.
+
+## See also
+
+- `package-conventions.md` for which packages may import which CLI
+- `gstack-routing.md` for how interactive workflows route to CLIs
+- `docs/research/2026-05-14-token-savings-benchmark-methodology.md` for the
+  benchmark methodology that exercises this CLI matrix

package/catalog/agent/rules/ts-coding-conventions.md

@@ -0,0 +1,68 @@
+---
+type: rule
+slug: ts-coding-conventions
+title: TypeScript coding conventions
+status: active
+scope: 'path:**/*.{ts,tsx}'
+applies_to: [agents, humans]
+related: []
+created: '2026-05-06'
+last_reviewed: '2026-05-06'
+---
+
+# TypeScript coding conventions
+
+Principal-level non-negotiables. Most are enforced via oxlint; the rest are
+enforced by review and by the commit-msg + pre-push hooks.
+
+## Type safety
+
+- **Zero `any`** — not in source, not in tests, not in `// @ts-ignore` comments. Use `unknown` + a narrowing step, or a real type.
+- **No non-null assertions (`!`)** unless paired with a comment that explains the invariant. Prefer a runtime check.
+- **No TypeScript `enum`** — use `as const` objects + union literals. Enums produce runtime code and defeat tree shaking.
+- **No `namespace`** — ES modules only.
+- **Prefer `type` over `interface`** for non-extended shapes; use `interface` only when declaration merging is genuinely needed.
+- **Readonly by default** — `readonly T[]` for array params that aren't mutated; `Readonly<T>` for object params; `as const` for literal maps.
+
+## Control flow and complexity
+
+- **Max cognitive complexity 8** (oxlint). Break out early returns; extract helpers.
+- **No `var`**. `const` everywhere; `let` only when reassigned.
+- **No `alert` / `confirm` / `prompt`** in app/worker code.
+- **No default exports** in new code. Named exports improve refactors, renames, and auto-imports.
+- **No `any`-typed catch bindings** — `catch (error: unknown)` then narrow.
+
+## Imports and module boundaries
+
+- **No `../../../..` relative ladders**. Use the nearest workspace alias (e.g. `@scope/<package>/<surface>` — pnpm workspaces with TS path aliases).
+- **No cross-package deep imports** — import only from a package's public entry points. If you need something internal, export it or add it to the public surface deliberately.
+- **No import cycles**. Oxlint flags them.
+- **One-line imports only** for `type` — `import type { Foo } from "…"` — not `import { type Foo } from "…"` unless other non-type names are already there.
+- **No side-effect imports** outside a small allowlist (polyfills, CSS). Tree-shaking breaks otherwise.
+
+## Async and errors
+
+- **No `async` without `await`**.
+- **Every Promise resolves or is explicitly `void`ed** — unhandled-promise lint is on.
+- **Never `throw` a non-Error** — throw `new Error(...)` or a domain error class.
+- **Don't swallow errors** to satisfy a handler contract. Log with context, re-throw, or convert to a typed `Result`.
+- **No bare `setTimeout`/`setInterval`** without a cleanup path (abort, clearTimeout in finally, structured concurrency).
+
+## Logging
+
+- Structured logs only via the repo's shared logger. No `console.log` in app code.
+- Log `level`, `msg`, and a structured context object — never string-concatenate.
+- Redact secrets at the logger boundary.
+
+## Tests
+
+- **Every test file sits next to its subject** (`foo.ts` → `foo.test.ts`), except integration/e2e tests which live under `tests/`.
+- **Test file names include the suite level**: `foo.test.ts`, `foo.integration.test.ts`, `foo.e2e.test.ts`.
+- **No `.skip` / `.only`** checked in. Hook blocks these.
+- **Assertions are strict**: `expect(value).toStrictEqual(...)`, not `.toMatchObject` unless intentional.
+- **One behavior per test**. If you need `&& expect`, split the test.
+
+## Files that are off-limits
+
+See `generated-code-governance.md`. Do not edit generated code, lockfiles,
+or vendored SDKs by hand.