@webpresso/agent-kit 0.21.4 → 0.23.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
-    "version": "0.21.4"
+    "version": "0.23.0"
   },
   "plugins": [
     {
@@ -23,5 +23,5 @@
       ]
     }
   ],
-  "version": "0.21.4"
+  "version": "0.23.0"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webpresso",
-  "version": "0.21.3",
+  "version": "0.23.0",
   "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
   "skills": "./skills",
   "commands": "./commands",

package/README.md

@@ -1,100 +1,127 @@
 # @webpresso/agent-kit
 
-> Plug-and-play setup for AI coding agents. Run one command and every agent in
-> the repo gets the same instructions, skills, hooks, planning files, and quality
-> gates. MIT. Experimental v0.x.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![CI](https://github.com/webpresso/agent-kit/actions/workflows/ci.webpresso.yml/badge.svg)](https://github.com/webpresso/agent-kit/actions/workflows/ci.webpresso.yml)
 
-## Install
+> TypeScript infrastructure for AI-agent-driven development. One `wp` runtime
+> gives agents planning, tests, mutation, e2e, CI, docs, and debt tracking —
+> all summary-first so they keep context, and enforced as contracts so docs,
+> intent, and code can't drift. MIT. Experimental v0.x.
 
-Requires Node.js 24 or newer.
+## What it is
 
-Install from the public npm registry:
+`@webpresso/agent-kit` is a TypeScript toolkit — the `wp` CLI plus an MCP
+server — that gives AI coding agents a summary-first, contract-enforced way to
+plan, test, and keep a repo correct.
 
-```bash
-npm install -g @webpresso/agent-kit
-wp setup
-```
+## Why use it
+
+- **Agents keep context.** The `wp_*` MCP tools return summary-first JSON
+  (failures + `bytes` + `tokensSaved`), not thousand-line logs.
+- **Docs, plans, and code can't silently diverge.** Every audit runs as both an
+  MCP tool and a pre-commit/CI gate.
+- **Zero hand-wiring onboarding.** `wp setup` scaffolds the quality config and
+  keeps `AGENTS.md` / `CLAUDE.md` plus per-agent surfaces in sync.
+
+## Quick start
 
-That's the product.
+Requires Node.js 24 or newer. No private registry setup is required.
 
-No private registry setup is required.
+```bash
+npm install -g @webpresso/agent-kit && wp setup
+```
 
-If you do not want a global install, run it one-shot instead:
+Prefer not to install globally? Run it one-shot:
 
 ```bash
 npm exec --yes --package @webpresso/agent-kit@latest -- wp setup
 ```
 
-`wp setup` is safe to run again. It refreshes the webpresso-owned pieces and
-preserves consumer-owned files.
+**Success signal:** `wp setup` completes and is idempotent. On a fresh repo it
+scaffolds the `base-kit` quality assets (`tsconfig`, Vitest, Oxlint, Stryker,
+Playwright, unit-test and file-based e2e smoke assets), wires `AGENTS.md` /
+`CLAUDE.md` plus per-agent command/skill/hook surfaces, and prints
+execution-owned vs authoring-owned dependency migration guidance. Re-running
+refreshes the webpresso-owned pieces and preserves consumer-owned files.
 
-## What it gives you
+`wp` owns **execution** for the generic tool lanes it manages (test / mutation /
+e2e / lint / format / typecheck). That does **not** mean every local
+devDependency disappears — keep dependencies your repo imports directly (e.g.
+`vitest`, `@playwright/test`, `typescript`); review execution-only binaries
+(e.g. `oxlint`, `oxfmt`) for removal only when nothing imports them. See
+[`docs/getting-started.md`](docs/getting-started.md).
 
-- **One repo brain** — major coding agents read the same operating contract.
-- **Skills that travel** — repo skills show up across supported agent surfaces.
-- **Hooks that help** — generated hooks steer common work through repo quality gates.
-- **Blueprints by default** — planning files and templates are ready when the task needs them, and Blueprint markdown stays the canonical plan while OMX handoff files remain derived metadata.
-- **Agent-friendly checks** — tests, lint, typecheck, E2E, and audits are easy to run and cite.
-- **Context-efficient evidence by default** — `wp_*` MCP wrappers return
-  compact test/lint/typecheck/audit summaries, and `wp setup` includes `rtk`
-  in its default workstation preset set.
+Verify install claims against the packed artifact:
 
-## Why it exists
+```bash
+vp run public:consumer-smoke -- --setup-only
+```
 
-AI-agent repos usually grow six copies of the same thing:
+## Features
 
-- one instruction file for Claude,
-- another for Codex,
-- another for Cursor,
-- separate hooks,
-- separate skills,
-- separate planning conventions.
+| Capability | What it does | Proof |
+| --- | --- | --- |
+| **`wp setup` onboarding** | Idempotent scaffolder for the base-kit quality config + `AGENTS.md` / `CLAUDE.md` wiring | [`src/cli/commands/init/`](src/cli/commands/init/), verified by [`scripts/public-consumer-smoke.ts`](scripts/public-consumer-smoke.ts) |
+| **Summary-first `wp_*` MCP tools** | `wp_test` / `wp_typecheck` / `wp_lint` / `wp_qa` / `wp_e2e` / `wp_format` / `wp_ci_act` / `wp_audit` return JSON with `bytes` / `tokensSaved` budget metadata | [`src/mcp/tools/`](src/mcp/tools/) (each with co-located `.test.ts`), [`src/mcp/server.integration.test.ts`](src/mcp/server.integration.test.ts) |
+| **MCP server + CLI surface** | Registers the tool set and exposes it to agents | [`src/mcp/server.ts`](src/mcp/server.ts), [`src/mcp/cli.ts`](src/mcp/cli.ts), [`src/mcp/cli.integration.test.ts`](src/mcp/cli.integration.test.ts) |
+| **Blueprint runtime** | Lifecycle states, dependency-aware task graph, structured authoring control plane (`wp_blueprint_depgraph` / `put` / `transition`) | [`src/mcp/blueprint-server.ts`](src/mcp/blueprint-server.ts), [`docs/lifecycle.md`](docs/lifecycle.md), [`docs/blueprint-format.md`](docs/blueprint-format.md) |
+| **Audit contract family** | `blueprint-lifecycle`, `docs-frontmatter`, `catalog-drift`, `vision`, `architecture-drift`, `bundle-budget`, `commit-message` (Lore), `tech-debt`, `absolute-path-policy`, `open-source-licenses`, … — each runs as a `wp_audit` MCP tool **and** a pre-commit/CI gate | [`src/audit/`](src/audit/), [`src/mcp/tools/audit.ts`](src/mcp/tools/audit.ts), [`.github/workflows/ci.webpresso.yml`](.github/workflows/ci.webpresso.yml) |
+| **Symlinker** | Syncs canonical `.agent/` to per-IDE surfaces (Codex/Amp skills, Gemini TOML commands) via rulesync | [`src/symlinker/index.ts`](src/symlinker/index.ts), [`src/symlinker/symlinker.integration.test.ts`](src/symlinker/symlinker.integration.test.ts), [`docs/symlinker.md`](docs/symlinker.md) |
+| **Mutation testing** | `wp audit mutation` (Stryker) catches tests that pass without asserting | [`src/config/stryker/`](src/config/stryker/), `./stryker` + `./mutation` exports |
+| **Tech-debt lifecycle** | `accepted → needs-remediation → monitoring → resolved`, auto-filed from failing audits | [`src/blueprint/tech-debt/`](src/blueprint/tech-debt/), [`src/cli/commands/tech-debt/`](src/cli/commands/tech-debt/) |
+| **Shared config subpaths** | `tsconfig/*`, `vitest/*`, `oxlint/*`, `workers-test`, `test-preset`, `e2e-preset`, `docs-lint`, `launch` | [`package.json` exports](package.json), [`src/config/`](src/config/) |
+| **Claude Code plugin** | Ships as a plugin; `vp run lint:pkg` runs `claude plugin validate .` | `.claude-plugin/` (in `package.json#files`) |
 
-Those copies drift. webpresso makes the repo feel like one product again:
+## Architecture
 
-```bash
-wp setup
+```
+                 ┌──────────────────────────────────────────┐
+   AI agent  ───▶ │  MCP server  (summary-first wp_* tools)   │
+   (Claude /      │  test · typecheck · lint · qa · e2e ·     │
+    Codex)        │  format · ci-act · audit · blueprint_*    │
+                 └───────────────┬──────────────────────────┘
+   human     ───▶  wp CLI  ──────┤  (same logic, shell surface)
+                                 ▼
+        ┌────────────┬───────────────┬───────────────┬─────────────┐
+        │ Blueprints │ Audit family  │ Symlinker      │ base-kit     │
+        │ lifecycle  │ MCP + CI gate │ .agent/ → IDEs │ scaffold     │
+        └────────────┴───────────────┴───────────────┴─────────────┘
 ```
 
-## Why agents keep more useful context
-
-Coding agents waste context in two predictable ways: duplicated repo guidance and
-verbose tool output. Agent Kit attacks both:
+Two properties make it *agent-grade*: output is **summary-first** (agents keep
+context) and tooling is **enforced** (pre-commit + CI gates, not just
+available). See [`docs/qa-output.md`](docs/qa-output.md) and
+[`VISION.md`](./VISION.md).
 
-- **Default compact quality evidence:** `wp_test`, `wp_lint`, `wp_typecheck`, `wp_qa`,
-  `wp_e2e`, and `wp_audit` are MCP-first wrappers that return summary-first
-  JSON, clipped raw output, and budget metadata such as `bytes` and
-  `tokensSaved`. See [`docs/qa-output.md`](docs/qa-output.md).
-- **Default RTK shell filtering lane:** `wp setup` includes `rtk` in its
-  default preset set. The setup command skips RTK in CI and when
-  `WP_SKIP_RTK=1` is set. See [`docs/add-ons.md`](docs/add-ons.md).
-- **Default context-mode lane:** `wp setup` includes `context-mode` in its
-  default preset set. The setup command skips context-mode in CI and when
-  `WP_SKIP_CONTEXT_MODE=1` is set, and the published package still does not
-  bundle the external tool. See
-  [`docs/migration/context-mode-default.md`](docs/migration/context-mode-default.md).
+## Verify
 
-The result: agents spend more of the window on code, plans, decisions, and
-errors that matter, and less on repeated instructions or thousand-line command
-logs.
+**Fast contributor check** — narrowest scope that proves a change:
 
-## Add-ons
+```bash
+vp run typecheck   # wp typecheck — no TS errors
+vp run lint        # wp lint (oxlint) — no violations
+vp run test        # unit then integration vitest suites — all green
+```
 
-Most repos should start with the default setup. Extra integrations and their
-default/opt-in behavior are documented in [`docs/add-ons.md`](docs/add-ons.md).
+**Full maintainer check** (bookend — run once at start, once at end):
 
-## Package references
+```bash
+vp run qa          # build + typecheck + lint + format:check + test + lint:pkg + audits:check
+```
 
-If you need config subpaths or dependency references, use the appendix:
-[`docs/markdown-fact-check.md`](docs/markdown-fact-check.md).
+`vp run qa` exits 0 when every stage passes. The package-surface gate runs
+separately as `vp run lint:pkg` (publint + attw `--pack`, plus `claude plugin
+validate` when `claude` is present).
 
-## Docs
+## Contribute / Security / License
 
-- [Getting started](docs/getting-started.md)
-- [Is webpresso for me?](docs/is-agent-kit-for-me.md)
-- [Add-ons](docs/add-ons.md)
-- [Blueprint format](docs/blueprint-format.md)
-- [Skills catalog](docs/skills-catalog.md)
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — setup, verify commands, Lore Commit
+  Protocol, and the Changesets release flow.
+- [SECURITY.md](./SECURITY.md) — private vulnerability reporting.
+- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — Contributor Covenant.
+- [CHANGELOG.md](./CHANGELOG.md) — release history (Changesets-managed).
+- [VISION.md](./VISION.md) — why this exists and where it's going.
+- [docs/markdown-fact-check.md](./docs/markdown-fact-check.md) — appendix: fact-check of current-state documentation claims and package references.
 
 ## Status
 

package/bin/_run.js

@@ -22,6 +22,25 @@ export const BIN_ENTRYPOINTS = {
   'docs-migrate': 'src/config/docs-lint/cli/migrate.ts',
 }
 
+const LATENCY_SENSITIVE_BUILT_BINS = new Set([
+  'wp-pretool-guard',
+  'wp-post-tool',
+  'wp-stop-qa',
+  'wp-guard-switch',
+  'wp-test-quality-check',
+  'wp-sessionstart-routing',
+  'wp-check-dev-link',
+])
+
+const RUNTIME_BIN_ARGS = {
+  wp: [],
+  'wp-pretool-guard': ['hook', 'pretool-guard'],
+  'wp-post-tool': ['hook', 'post-tool'],
+  'wp-stop-qa': ['hook', 'stop-qa'],
+  'wp-guard-switch': ['hook', 'guard-switch'],
+  'wp-sessionstart-routing': ['hook', 'sessionstart-routing'],
+}
+
 function resolvePackageRoot() {
   return join(dirname(fileURLToPath(import.meta.url)), '..')
 }
@@ -38,6 +57,46 @@ function readTextIfExists(path) {
   return existsSync(path) ? readFileSync(path, 'utf8').trim() : null
 }
 
+function readRuntimeManifest(repoRoot) {
+  const manifestPath = join(repoRoot, 'bin', 'runtime-manifest.json')
+  if (!existsSync(manifestPath)) return null
+
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (error) {
+    throw new Error(
+      `Unable to read compiled runtime manifest at ${manifestPath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+}
+
+function resolveRuntimeTarget(manifest, platform, arch) {
+  const targets = Array.isArray(manifest?.targets) ? manifest.targets : []
+  return targets.find((target) => target?.os === platform && target?.cpu === arch) ?? null
+}
+
+function runtimeBinaryFilename(manifest, target) {
+  const binaryName = typeof manifest?.binaryName === 'string' ? manifest.binaryName : 'wp'
+  return target?.os === 'win32' ? `${binaryName}.exe` : binaryName
+}
+
+function runtimePackageDirName(packageName) {
+  return String(packageName).split('/').at(-1)
+}
+
+function resolveRuntimeBinaryCandidates(repoRoot, manifest, target) {
+  const filename = runtimeBinaryFilename(manifest, target)
+  const packageDir = runtimePackageDirName(target.packageName)
+  return [
+    join(repoRoot, 'bin', 'runtime', target.id, filename),
+    join(repoRoot, 'dist', 'runtime', target.id, filename),
+    join(repoRoot, '..', packageDir, 'bin', filename),
+    join(repoRoot, 'node_modules', '@webpresso', packageDir, 'bin', filename),
+  ]
+}
+
 export function resolvePinnedNodeVersion(repoRoot = resolvePackageRoot()) {
   const nodeVersionFile = readTextIfExists(join(repoRoot, '.node-version'))
   if (nodeVersionFile && isExactNodeVersion(nodeVersionFile)) return nodeVersionFile
@@ -82,6 +141,66 @@ function buildSourceLaunchPlan(sourceEntrypoint, forwardedArgs) {
   }
 }
 
+function shouldPreferBuiltDist(binName) {
+  return LATENCY_SENSITIVE_BUILT_BINS.has(binName)
+}
+
+function buildRuntimeLaunchPlan({
+  binName,
+  repoRoot,
+  forwardedArgs,
+  platform,
+  arch,
+  runtimeManifest,
+  runtimeBinaryExists,
+  runtimeBinaryPath,
+  forceCompiledRuntime,
+}) {
+  const selectorArgs = RUNTIME_BIN_ARGS[binName]
+  if (!selectorArgs) return null
+
+  const manifest = runtimeManifest ?? readRuntimeManifest(repoRoot)
+  if (!manifest) return null
+
+  const target = resolveRuntimeTarget(manifest, platform, arch)
+  if (!target) {
+    if (!forceCompiledRuntime) return null
+    throw new Error(
+      `Unable to launch ${binName}: no compiled runtime target for ${platform}/${arch}.`,
+    )
+  }
+
+  const candidates = runtimeBinaryPath
+    ? [runtimeBinaryPath]
+    : resolveRuntimeBinaryCandidates(repoRoot, manifest, target)
+  const binaryPath = candidates.find((candidate) =>
+    runtimeBinaryExists ? runtimeBinaryExists(candidate) : existsSync(candidate),
+  )
+
+  if (!binaryPath) {
+    if (!forceCompiledRuntime) return null
+    throw new Error(
+      [
+        `Unable to launch ${binName}: compiled runtime target ${target.id} is missing.`,
+        `Looked for ${candidates.join(', ')}.`,
+        'Run `wp hooks doctor` to diagnose the install, or rebuild/reinstall the runtime package.',
+      ].join(' '),
+    )
+  }
+
+  return {
+    mode: 'runtime',
+    runtime: binaryPath,
+    entrypoint: binaryPath,
+    args: [...selectorArgs, ...forwardedArgs],
+    env: {
+      ...process.env,
+      WP_COMPILED_RUNTIME: '1',
+      WP_MCP_TOOL_MODE: 'registry',
+    },
+  }
+}
+
 export function resolveInvokedBinName(argv = process.argv.slice(1)) {
   const invoked = argv[0]
   if (typeof invoked !== 'string' || invoked.length === 0) {
@@ -94,8 +213,14 @@ export function buildLaunchPlan({
   binName,
   repoRoot = resolvePackageRoot(),
   forwardedArgs = process.argv.slice(2),
+  platform = process.platform,
+  arch = process.arch,
   builtExists,
   sourceExists,
+  runtimeBinaryExists,
+  runtimeBinaryPath,
+  runtimeManifest,
+  forceCompiledRuntime = process.env.WP_FORCE_COMPILED_RUNTIME === '1',
   nodeExecPath = process.execPath,
   currentNodeVersion = process.version,
   pinnedNodeVersion = resolvePinnedNodeVersion(repoRoot),
@@ -108,6 +233,19 @@ export function buildLaunchPlan({
     throw new Error(`Unknown webpresso bin: ${binName}`)
   }
 
+  const runtimePlan = buildRuntimeLaunchPlan({
+    binName,
+    repoRoot,
+    forwardedArgs,
+    platform,
+    arch,
+    runtimeManifest,
+    runtimeBinaryExists,
+    runtimeBinaryPath,
+    forceCompiledRuntime,
+  })
+  if (runtimePlan) return runtimePlan
+
   const builtRelativePath = sourceToBuiltRelativePath(sourceRelativePath)
   const builtEntrypoint = join(repoRoot, builtRelativePath)
   const sourceEntrypoint = join(repoRoot, sourceRelativePath)
@@ -121,6 +259,7 @@ export function buildLaunchPlan({
     sourceMtimeMs ??
     (sourceExists === undefined && hasSource ? statSync(sourceEntrypoint).mtimeMs : null)
   const shouldPreferSource =
+    !shouldPreferBuiltDist(binName) &&
     hasSource &&
     typeof resolvedBuiltMtimeMs === 'number' &&
     typeof resolvedSourceMtimeMs === 'number' &&
@@ -183,7 +322,10 @@ export function buildLaunchPlan({
 
 export function runNamedBin(binName, argv = process.argv.slice(2)) {
   const plan = buildLaunchPlan({ binName, forwardedArgs: argv })
-  const child = spawnSync(plan.runtime, plan.args, { stdio: 'inherit' })
+  const child = spawnSync(plan.runtime, plan.args, {
+    stdio: 'inherit',
+    env: plan.env ?? process.env,
+  })
 
   if (child.error) {
     const detail =

package/bin/runtime-manifest.json

@@ -0,0 +1,40 @@
+{
+  "binaryName": "wp",
+  "targets": [
+    {
+      "id": "darwin-arm64",
+      "bunTarget": "bun-darwin-arm64",
+      "os": "darwin",
+      "cpu": "arm64",
+      "packageName": "@webpresso/agent-kit-runtime-darwin-arm64"
+    },
+    {
+      "id": "darwin-x64",
+      "bunTarget": "bun-darwin-x64",
+      "os": "darwin",
+      "cpu": "x64",
+      "packageName": "@webpresso/agent-kit-runtime-darwin-x64"
+    },
+    {
+      "id": "linux-x64",
+      "bunTarget": "bun-linux-x64",
+      "os": "linux",
+      "cpu": "x64",
+      "packageName": "@webpresso/agent-kit-runtime-linux-x64"
+    },
+    {
+      "id": "linux-arm64",
+      "bunTarget": "bun-linux-arm64",
+      "os": "linux",
+      "cpu": "arm64",
+      "packageName": "@webpresso/agent-kit-runtime-linux-arm64"
+    },
+    {
+      "id": "windows-x64",
+      "bunTarget": "bun-windows-x64",
+      "os": "win32",
+      "cpu": "x64",
+      "packageName": "@webpresso/agent-kit-runtime-windows-x64"
+    }
+  ]
+}

package/catalog/AGENTS.md.tpl

@@ -34,7 +34,7 @@ vp install && vp run setup:agent  # setup:agent runs wp setup, which scaffolds .
 ```
 
 agent-kit's catalog is the single source of truth for generated agent surfaces.
-`wp` is the canonical public CLI surface for setup, sync, and repo automation.
+Agent-kit owns the generated agent surfaces in this file; the Webpresso CLI host owns the end-user command surface.
 To customize skills, commands, or workflows, edit them in agent-kit's catalog
 and publish — not in individual repos. The default `omx` preset chains
 `omx setup --yes --scope user` and installs missing OMX through
@@ -52,7 +52,7 @@ Tracked vs ignored rule of thumb:
   `.agents/`, generated `.claude/rules/`, `.claude/skills/`,
   `.claude/worktrees/`, editor-local state, and other runtime projections).
 
-`wp setup` / `wp sync` are the canonical bootstrap commands.
+Current-state bootstrap commands remain `wp setup` / `wp sync`; future unified CLI replacements are `webpresso agent setup` / `webpresso agent sync`.
 
 ## Plan
 
@@ -96,7 +96,7 @@ behavior and any broader checks this repo requires. Typical gates are:
 - repo policy checks such as `verify:paths` / `verify:secrets` when setup
   scaffolded them
 - docs or blueprint validation when docs/plans changed
-- `wp sync --check` after `wp setup` to verify surfaces are in sync
+- `wp sync --check` after `wp setup` to verify surfaces are in sync today; treat `webpresso agent setup` / `webpresso agent sync` as the future cutover replacements
 
 If a gate fails, fix the root cause or record the blocker with evidence.
 
@@ -145,9 +145,10 @@ this block is preserved verbatim across `wp sync` runs.
 ## Durable planning surface
 
 - Materialized by setup: blueprint lifecycle directories under
-  `{{BLUEPRINTS_DIR}}/` (`planned/`, `in-progress/`, `completed/`) and durable
-  plan files under `{{DURABLE_PLANNING_ROOT}}plans/` when PRDs or test specs
-  are generated.
+  `{{BLUEPRINTS_DIR}}/` (`planned/`, `in-progress/`, `completed/`).
+- PRDs, test specs, and other blueprint-owned planning artifacts should live
+  under the configured blueprint root (`{{BLUEPRINTS_DIR}}/`), colocated with
+  the blueprint they refine, rather than under the durable planning root.
 - Generated on demand (not created by setup): boundary contracts at
   `{{DURABLE_PLANNING_ROOT}}contracts/`, lifecycle state at
   `{{DURABLE_PLANNING_ROOT}}state/`, session notes at

package/catalog/agent/commands/plan-refine.md

@@ -20,7 +20,7 @@ Refine a blueprint by applying the canonical plan-refine methodology to the actu
 
 ## What This Command Does
 
-Edits `blueprints/*/<slug>/_overview.md` so the blueprint is:
+Edits the canonical blueprint markdown (`blueprints/*/<slug>.md` by default, or `blueprints/*/<slug>/_overview.md` for folder-shaped plans) so the blueprint is:
 
 - fact-checked against current docs and repo reality
 - aligned with planning and testing rules
@@ -32,7 +32,7 @@ Edits `blueprints/*/<slug>/_overview.md` so the blueprint is:
 ### Step 1: Locate the blueprint
 
 ```bash
-find blueprints -name "_overview.md" -path "*/$SLUG/*"
+find blueprints \\( -path "*/$SLUG.md" -o -path "*/$SLUG/_overview.md" \\)
 ```
 
 If no matching blueprint exists, stop and report that.
@@ -83,7 +83,7 @@ Run the blueprint parser check:
 wp blueprint show <slug>
 ```
 
-If the refinement changes markdown structure enough to warrant a lint pass, also run your repo's markdown linter against `blueprints/*/<slug>/_overview.md` (for example, `just lint-md` with webpresso's just recipes).
+If the refinement changes markdown structure enough to warrant a lint pass, also run your repo's markdown linter against the canonical blueprint markdown for that slug (for example, `just lint-md` with webpresso's just recipes).
 
 ### Step 6: Report the outcome
 

package/catalog/agent/commands/pll.md

@@ -41,6 +41,7 @@ It does three things:
 
 ```text
 /pll tasks.md
+/pll blueprints/in-progress/my-blueprint.md
 /pll blueprints/in-progress/my-blueprint/_overview.md
 ```
 
@@ -162,6 +163,7 @@ If the model would diverge between the two surfaces, fix the contract instead of
 ```text
 /pll "lint auth, lint utils, typecheck auth [depends: 1], test auth [depends: 3]"
 
+/pll blueprints/in-progress/converge-omx-and-blueprint-planning-surfaces.md
 /pll blueprints/in-progress/converge-omx-and-blueprint-planning-surfaces/_overview.md
 
 /pll

package/catalog/agent/guides/parallel-execution.md

@@ -22,6 +22,8 @@ wp blueprint start <slug>
 wp blueprint show <slug>
 
 # 3. Execute via the parallel orchestration surface
+/pll blueprints/in-progress/<slug>.md
+# or, for folder-shaped blueprints:
 /pll blueprints/in-progress/<slug>/_overview.md
 
 # 4. Monitor and complete

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

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents, humans]
 related: [blueprint-scoping]
 created: '2026-05-11'
-last_reviewed: '2026-05-11'
+last_reviewed: '2026-05-31'
 ---
 
 # Extraction parity — byte-identity + mutation-score verification
@@ -144,6 +144,32 @@ Reference in the blueprint overview:
 
 ---
 
+## 5. Deploy-contract relocation parity
+
+If the relocation touches shared deploy-contract material (workflow templates,
+policy docs, fixtures, or verifier handoff docs), parity evidence must also
+state that these semantics remained unchanged:
+
+- internal lane IDs stay internal and remain exactly `dev`, `preview_main`,
+  `preview_pr_<n>`, and `prd`;
+- cloud/provider-facing environment names are derived separately and must be
+  dash-safe rather than reusing the internal lane IDs as public contract;
+- Durable Object-backed previews do **not** rely on provider Preview URLs;
+  custom-domain environment previews are the default and `workers_dev_env` is
+  exception-only;
+- production release metadata stays anchored at
+  `infra/release-metadata.production.json`;
+- migration-bearing Durable Object releases fail closed in the consuming
+  repo's deploy verifier/workflow;
+- provider-specific deployment plumbing does not move into shared
+  `@webpresso/agent-kit` surfaces during the extraction.
+
+When any of the above changes intentionally, the move is no longer "pure
+relocation" and the blueprint must document the contract delta explicitly
+instead of claiming parity.
+
+---
+
 ## Why this rule exists
 
 Task 1.4 of the `fold-webpresso-quality-engine-into-webpresso`

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

@@ -9,7 +9,7 @@ related:
   - package-conventions
   - repo-restrictions
 created: '2026-05-26'
-last_reviewed: '2026-05-26'
+last_reviewed: '2026-05-31'
 paths:
   - 'package.json'
   - '.npmignore'
@@ -54,3 +54,26 @@ publish workflow, registry, or catalog assets:
 
 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.
+
+## Shared deploy-contract surfaces stay provider-neutral
+
+If a public package or template documents the approved Durable Object preview
+lanes contract, keep the shared surface policy-only:
+
+- treat `dev`, `preview_main`, `preview_pr_<n>`, and `prd` as internal lane
+  IDs, not as Cloudflare-facing environment names;
+- derive provider env names separately and make them dash-safe;
+- document that Durable Object-backed previews must not depend on Preview
+  URLs; the default is custom-domain environment previews, with
+  `workers_dev_env` reserved for explicit exception cases;
+- keep the canonical production release metadata path at
+  `infra/release-metadata.production.json`;
+- require the consuming repo's workflow/verifier to fail closed for
+  migration-bearing Durable Object releases;
+- keep provider-specific plumbing, secrets, bindings, and release mechanics
+  out of shared `@webpresso/agent-kit` code, docs, and examples.
+
+Shared packages may define the contract and the guardrail names
+(`verify:deploy-contract`, metadata path, internal lane IDs), but the
+provider-specific implementation belongs in the consuming repo that owns the
+deployment target.

package/catalog/agent/skills/plan-refine/SKILL.md

@@ -16,10 +16,11 @@ description: Methodology for refining, fact-checking, and hardening implementati
 >
 > Blueprint hardening and lifecycle infrastructure are production-ready:
 >
-> - Kahn's Algorithm DAG analysis (fully tested)
-> - `ParallelExecutor` concurrency engine with abort, timeout, per-type limits
-> - Blueprint dependency format and validation
-> - Failed tasks block dependents automatically
+> - Blueprint dependency parsing, format validation, and the lifecycle state
+>   machine with evidence-gated task completion (fully tested, in-package)
+> - Parallel execution is delegated to the `/pll` runtime adapter (OMX), which
+>   batches independent tasks by dependency order and blocks dependents of
+>   failed tasks
 >
 > **Remaining gaps:** execution docs and wrappers must stay aligned with the currently shipped runtime and CLI surface.
 

package/catalog/agent/skills/pll/SKILL.md

@@ -81,5 +81,6 @@ When no explicit task list is supplied, ground lane selection in `wp blueprint l
 ```bash
 /pll "lint auth, lint utils, typecheck api [depends: lint auth], test api [depends: typecheck api]"
 /pll tasks.md --max=6
+/pll blueprints/in-progress/new-launch.md
 /pll blueprints/in-progress/new-launch/_overview.md
 ```