@webpresso/agent-kit 0.21.5 → 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.5"
+    "version": "0.23.0"
   },
   "plugins": [
     {
@@ -23,5 +23,5 @@
       ]
     }
   ],
-  "version": "0.21.5"
+  "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,164 +1,127 @@
 # @webpresso/agent-kit
 
+[![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)
+
 > 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.
 
-## Install
+## What it is
 
-Requires Node.js 24 or newer.
+`@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.
 
-Install from the public npm registry:
+## Why use it
 
-```bash
-npm install -g @webpresso/agent-kit
-wp setup
-```
+- **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,
-creates the default `base-kit` quality scaffold when files are absent, 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.
 
-The guarantee is **zero hand-wiring**, not zero local dependencies. Fresh repos
-get starter `tsconfig`, Vitest, Oxlint, Stryker, Playwright, unit-test, and
-file-based e2e smoke assets. Repos still keep authoring-time dependencies that
-their configs and tests import directly.
+`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).
 
-Default workstation presets are separate from repo bootstrap. `omx`, `omc`,
-`gstack`, `vision`, `rtk`, and `context-mode` are requested by default and
-degrade with explicit skipped/warning output when the matching host or auth is
-unavailable. The repo bootstrap is `base-kit`.
+Verify install claims against the packed artifact:
+
+```bash
+vp run public:consumer-smoke -- --setup-only
+```
 
-### Execution-owned vs authoring-owned dependencies
+## Features
 
-`wp` now owns **execution** for the generic tool lanes it manages:
+| 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`) |
 
-- test / mutation
-- e2e
-- lint
-- format
-- typecheck
+## Architecture
 
-That does **not** mean every local devDependency should disappear.
+```
+                 ┌──────────────────────────────────────────┐
+   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     │
+        └────────────┴───────────────┴───────────────┴─────────────┘
+```
 
-- Keep local dependencies that your repo **imports directly** from tests,
-  config files, or tsconfig types — for example `vitest`,
-  `@playwright/test`, `@testing-library/jest-dom`, or `typescript`.
-- Review execution-only binaries for removal **only if** they were installed
-  just to invoke them locally and nothing imports them directly — for example
-  `oxlint`, `oxfmt`, or `markdownlint-cli2`.
+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).
 
-`wp setup` prints this migration guidance after scaffolding so consumers do not
-accidentally strip authoring-time dependencies just because `wp` can execute
-the tool.
+## Verify
 
-Public install claims are checked against the packed artifact with:
+**Fast contributor check** — narrowest scope that proves a change:
 
 ```bash
-vp run public:consumer-smoke -- --setup-only
+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
 ```
 
-Use the full smoke without `--setup-only` when you want to install the generated
-starter dependencies and run the generated quality commands.
-
-## What it does
-
-`wp` is the toolkit agents use to do real work in a repo. Every piece is built
-on two properties that make it *agent-grade* rather than yet-another-bundle:
-its output is **summary-first** (agents keep context) and it is **enforced**
-(pre-commit + CI gates, not just available).
-
-### The toolkit
-
-- **Planning** — blueprints: markdown plans with a lifecycle
-  (`wp audit blueprint-lifecycle`) and a dependency-aware task graph.
-  `wp_blueprint_depgraph` returns its dependency graph (nodes + edges), and
-  optional runtime adapters (OMX `/pll`) use those dependencies to run
-  independent tasks in parallel.
-  Authoring now has a structured control plane: `wp_blueprint_put` writes the
-  blueprint from typed input and `wp_blueprint_transition` advances lifecycle
-  state with revision-aware optimistic concurrency. A future MCP Apps editor is
-  explicitly a follow-on enhancement layered on top of those tools, not a
-  separate required write surface. See [`docs/lifecycle.md`](docs/lifecycle.md).
-- **Tests, types, lint** — `wp_test`, `wp_typecheck`, `wp_lint` over your
-  vitest/oxlint setup.
-- **Mutation testing** — `wp audit mutation` (Stryker) catches tests that pass
-  without actually asserting.
-- **End-to-end** — `wp_e2e` runs suite-aware Playwright flows.
-- **CI, locally** — `wp_ci_act` runs your GitHub Actions through `act` behind
-  the repo secret contract.
-- **Docs** — `wp docs lint` and `wp audit docs-frontmatter` keep docs
-  structured and current.
-- **Tech-debt** — `wp tech-debt` tracks debt through a status lifecycle
-  (accepted → needs-remediation → monitoring → resolved), auto-filed from
-  failing audits.
-
-### What makes it agent-grade
-
-- **Summary-first output** — the `wp_*` MCP wrappers return summary-first JSON
-  with clipped raw output and budget metadata (`bytes`, `tokensSaved`), and
-  `wp setup` wires the `rtk` and `context-mode` output-filtering lanes by
-  default (skipped in CI and via `WP_SKIP_RTK=1` / `WP_SKIP_CONTEXT_MODE=1`;
-  never bundled in the package). Agents reason over the failure set, not the
-  thousand-line log. See [`docs/qa-output.md`](docs/qa-output.md).
-- **Enforced as contracts** — `wp audit vision` keeps `VISION.md` current,
-  `wp audit architecture-drift` keeps architecture docs aligned with the
-  implementation they describe, `wp audit bundle-budget` caps client output,
-  and the Lore commit protocol (`wp audit commit-message --require-lore`)
-  records the *why* behind each change. Every audit runs as a `wp_audit` MCP
-  tool **and** as a pre-commit and CI gate — so intent, docs, and code can't
-  silently diverge.
-- **One operating contract, managed for you** — `wp` generates and keeps your
-  `AGENTS.md`, `CLAUDE.md`, and each agent's command, skill, and hook surfaces
-  in sync, emitted through rulesync across every supported runtime (see
-  [`catalog/agent/rules/supported-agent-clis.md`](catalog/agent/rules/supported-agent-clis.md)).
-  `AGENTS.md` is the standard; `wp` keeps everything around it coherent.
-
-## Why it exists
-
-Sharing instructions across agents is largely solved: `AGENTS.md` is the
-standard, and emitters like rulesync fan one source out to every runtime. `wp`
-manages that layer for you — but the hard part of agent-driven development isn't
-a missing instruction file. It is keeping agents **effective** (they burn the
-context window on verbose tool output) and keeping the repo **correct** (docs,
-plans, and code drift apart as agents move fast).
-
-`wp` is the TypeScript layer for both: summary-first tooling so the window goes
-to code, and enforced contracts so the work stays coherent.
+**Full maintainer check** (bookend — run once at start, once at end):
 
 ```bash
-wp setup
+vp run qa          # build + typecheck + lint + format:check + test + lint:pkg + audits:check
 ```
 
-## Add-ons
-
-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).
-
-## Package references
-
-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)
-- [Blueprint lifecycle](docs/lifecycle.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`