@webpresso/agent-kit 3.1.28 → 3.2.0

package/catalog/agent/rules/parallel-orchestration-quota.md

@@ -0,0 +1,100 @@
+---
+type: rule
+slug: parallel-orchestration-quota
+title: Parallel orchestration and quota discipline
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - ci-cost-local-first
+  - cmd-execution
+  - pre-implementation
+  - engineering-principles
+  - supported-agent-clis
+created: "2026-07-24"
+last_reviewed: "2026-07-24"
+paths:
+  - "blueprints/**"
+  - "catalog/agent/**"
+---
+
+# Parallel orchestration and quota discipline
+
+How to execute multi-blueprint work: one orchestrator, many cheap executors,
+lowest defensible token/quota/CI cost. This is the **default** execution model
+for programs of more than ~3 blueprints — not an opt-in mode.
+
+Companion rules (do not restate them here): `ci-cost-local-first.md` for runner
+policy, `cmd-execution.md` for the scoped-command surface,
+`pre-implementation.md` for the blueprint gate, `engineering-principles.md` for
+scope filters, `supported-agent-clis.md` for host tiers.
+
+## Orchestrator / executor split
+
+The session that owns the program is an **orchestrator**: it plans, sequences,
+dispatches, reviews, and lands. It does not implement. Implementation is
+delegated to **executor subagents**, one per blueprint, each confined to that
+blueprint's owner worktree.
+
+- Spawn a **fresh executor per task** inside a multi-task blueprint. Long
+  single-session runs drift; a fresh executor per task keeps a consolidated
+  blueprint cheap to run correctly.
+- Executors never touch the primary checkout or another blueprint's worktree.
+- The orchestrator runs from its own controller worktree cut from
+  `origin/main`, never from the primary checkout.
+
+## Model tier by intrinsic difficulty
+
+Pick the **cheapest model that can do the job**, judged by the hardest task in
+the blueprint — never by aggregate diff size or file count.
+
+| Complexity                                          | Executor                                     |
+| --------------------------------------------------- | -------------------------------------------- |
+| L / XL, design-heavy, security- or protocol-bearing | premium reasoning tier                       |
+| M                                                   | mid tier, high effort                        |
+| S / XS, mechanical                                  | mid tier, medium effort — or small/fast tier |
+
+A blueprint bundling many mechanically-trivial edits stays a cheap-tier job. If
+a blueprint would need a premium tier only because of one hard task, that task
+is mis-homed: move it to a blueprint whose tier it matches.
+
+**Exception: design, UI, and frontend work always gets the premium tier**,
+whatever its sized complexity — components, panels, layout, styling, UX flows,
+design systems, and the frontend half of any feature. Mechanical work degrades
+gracefully at a cheaper tier: it is either correct or it fails a test. Interface
+work does not. A technically-correct but badly-judged UI passes every check and
+still has to be redone, so the cheaper tier is not actually cheaper. Backend and
+mechanical work keeps the cheapest-capable rule above.
+
+## Quota awareness across hosts
+
+Provider subscriptions are the budget. Treat weekly quota as a shared,
+exhaustible resource across every host (see `supported-agent-clis.md`).
+
+- Route each job — implementation and review alike — to the host whose
+  subscription can absorb it, not reflexively to the strongest one.
+- On a provider usage-limit error, **rotate provider and resume** rather than
+  waiting or retrying the same host. Review gates are resumable by gate id.
+- Never spend a premium tier on work a cheap tier finishes identically.
+
+## Review and CI cost
+
+Blueprint count is the dominant cost driver: one executable blueprint is one
+PR, one external review, and one full CI matrix run.
+
+- **Consolidate coherent work.** One blueprint = one reviewable contract in one
+  subsystem. Never straddle a dependency cut, mix intrinsic-difficulty tiers, or
+  merge unrelated subsystems just to reduce count.
+- **Route each review gate to the cheapest adequate provider.** Reserve premium
+  reviewers for premium-tier blueprints.
+- **Prefer work that needs no gate at all.** Markdown-only PRs are exempt from
+  blueprint PR coverage; pure git hygiene (branch/worktree pruning) needs no PR.
+- Verify locally before pushing, and rebase onto fresh `origin/main` before
+  landing so cached CI layers are reused.
+
+## Parallelism
+
+Run 3–4 blueprints concurrently. Widen only when the extra lanes touch disjoint
+files; serialize where they contend. When several features would edit one hot
+file, land a **behavior-preserving split first** so each feature owns its own
+file — that split pays for itself across the whole program.

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

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents, humans]
 related: []
 created: "2026-05-06"
-last_reviewed: "2026-05-06"
+last_reviewed: "2026-07-23"
 ---
 
 # Pre-Implementation Rules
@@ -157,6 +157,10 @@ as finished.
 A blueprint is a **folder** (`blueprints/<status>/<slug>/_overview.md`) and may
 not be promoted from `draft/` to `planned/` until it has **1 provenance-backed
 approval from Claude/Codex/Grok or an OpenCode-Go model** on the current content.
+Legacy flat blueprints (`blueprints/<status>/<slug>.md`) remain readable and
+lifecycle-valid, but they have no sibling review authority; run
+`wp blueprint canonicalize <slug>` before recording review ledgers, artifacts,
+Ultragoal events, or approval frontmatter.
 
 - **Gate input = committed in-folder review authority.** The preferred path is a
   content-addressed v2 `review-events.jsonl` event produced by `wp review gate`.
@@ -203,6 +207,19 @@ approval from Claude/Codex/Grok or an OpenCode-Go model** on the current content
   `approvals:` frontmatter with first-hand knowledge that reviewer actually
   produced that verdict — there is intentionally no MCP-reachable shortcut
   around that.
+- **`wp review override <slug> --reason "…" --confirm` is the gated CLI escape
+  hatch for a genuinely un-convergeable gate** — a strong reviewer legitimately
+  rejected the subject but its sole remaining blocker is physically
+  un-remediable (e.g. a platform residual the code cannot fix). It records a
+  `maintainer-override` approval that satisfies the promotion gate DISTINCTLY
+  (never counted as a strong or OpenCode-Go approval). It is not a way to skip
+  review: it REFUSES unless a formal Claude/Codex/Grok/OpenCode-Go gate has
+  already rejected the exact current subject, and it requires an explicit reason
+  plus `--confirm`. `maintainer-override` is not in the `wp review log` /
+  `wp_blueprint_review_log` reviewer enum, so this command is the only writer —
+  there is no MCP-reachable or frontmatter shortcut to mint it. Reserve it for
+  the residual that no code change can close; a normal blocker is fixed and
+  re-reviewed, not overridden.
 - **Retry interrupted or structurally failed gates with the same immutable
   target** by running `wp review gate ... --resume <gate-id>`. Aborted,
   timed-out, incomplete, and protocol/transport failures append a new attempt
@@ -210,6 +227,16 @@ approval from Claude/Codex/Grok or an OpenCode-Go model** on the current content
   killed writer is never overwritten. A complete content rejection is terminal
   for that unchanged target, while active provider limits/unavailability remain
   suppressed until their recorded retry window permits another attempt.
+- **Completed rejections have a two-subject circuit breaker.** Plan review
+  lineage uses the canonical `wp-blueprint-v1` subject, so lifecycle/trust
+  bookkeeping commits reuse the prior rejection and do not invoke another
+  reviewer. One semantically changed remediation subject may receive the final
+  formal review; its prompt includes the prior rejection artifact and requires
+  all remaining blockers together. After two distinct semantic subjects are
+  rejected, `wp review gate` returns `scope-exhausted` before provider
+  invocation. Stop automated retries and obtain an explicit human scope
+  decision before creating a successor blueprint. Plan and delivery purposes
+  have separate budgets; delivery retains its existing whole-tree subject.
 - **`provider-event-too-large` means one captured provider JSON event exceeded
   the bounded event limit; it is not a reviewer verdict.** Keep the bound in
   place, retry the same gate id, and switch provider/model when possible because
@@ -264,7 +291,8 @@ Doing it post-merge is also impossible without a second PR: you cannot push the
 **Local pre-push check (catches the CI failure before it costs minutes):** the
 local lifecycle audit gives a false pass here because the owner worktree resolves
 on your machine. So do not rely on it alone — before opening or updating the PR,
-confirm no changed blueprint is still under `blueprints/in-progress/`:
+run `wp ci-preflight` for ordinary quality gates and confirm no changed blueprint
+is still under `blueprints/in-progress/`:
 
 ```bash
 git diff --name-only origin/main...HEAD | grep -q '^blueprints/in-progress/' \

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

@@ -56,6 +56,15 @@ This is a product control-plane surface, not a silent Tier-1 promotion:
 - Missing binary/auth degrades with an explicit UI reason (never silent omit).
 - Benchmarks/plugins that require Tier-1 guarantees MUST still treat Grok as
   outside Tier 1 until a separate tier promotion lands.
+- `wp setup` also delivers the native project surfaces for Grok: the
+  `.grok/config.toml` `[mcp_servers.webpresso]` entry and trust-gated
+  `.grok/hooks/webpresso.json` managed hooks (run `/hooks-trust` once in Grok).
+  Grok reads `AGENTS.md`/`CLAUDE.md` natively, so no instruction projection is
+  needed.
+- After trusting the project hooks, operators verify native discovery with
+  `grok inspect --json`, `grok mcp list --json`, and
+  `grok mcp doctor --json`. Grok remains a trial host until its protected
+  privacy/native-proof job passes for the release SHA.
 
 ## Tier 3 — not supported
 

package/catalog/agent/rules/test-scan-perf.md

@@ -0,0 +1,80 @@
+---
+type: rule
+slug: test-scan-perf
+title: Test scan performance (no full-repo FS walks)
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - testing-philosophy
+  - ci-test-perf
+created: "2026-07-20"
+last_reviewed: "2026-07-20"
+paths:
+  - "**/*.{test,spec}.{ts,tsx,js,jsx}"
+  - "src/audit/test-scan-perf.ts"
+---
+
+# Test scan performance
+
+Unit and contract tests must not walk the whole repository with
+`readdirSync` / `statSync` / `readFileSync` and paper over the cost with a
+30s+ per-test timeout.
+
+## Forbidden pattern
+
+```ts
+const repoRoot = findRepoRoot();
+const walk = (dir: string) => {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      walk(full);
+      continue;
+    }
+    const text = readFileSync(full, "utf8");
+    // ...
+  }
+};
+walk(repoRoot);
+
+it("scan", () => {
+  /* ... */
+}, 30_000); // band-aid
+```
+
+## Preferred
+
+```ts
+// Tracked files only — seconds, not tens of seconds.
+const stdout = execFileSync(
+  "git",
+  ["-C", root, "grep", "-l", "-I", "-E", "RETIRED_SPECIFIER_A|RETIRED_SPECIFIER_B"],
+  { encoding: "utf8" },
+);
+```
+
+Or walk a **bounded** fixture / package tree (not `findRepoRoot()` / `process.cwd()`).
+
+## Guardrail
+
+| Surface    | Contract                           |
+| ---------- | ---------------------------------- |
+| Audit      | `wp audit test-scan-perf`          |
+| Guardrails | included in `wp audit guardrails`  |
+| Scope      | affected-safe (changed test files) |
+
+### Opt-out
+
+```ts
+// test-scan-perf-allow — one-off inventory with justification
+walk(repoRoot);
+
+// or once per file:
+// test-scan-perf-allow-file — full inventory intentionally walks the tree
+```
+
+## Related
+
+- Implementation: `src/audit/test-scan-perf.ts`
+- CI workers/cache: `ci-test-perf` (workflow-level, separate concern)

package/catalog/agent/rules/typescript-version.md

@@ -0,0 +1,50 @@
+---
+type: rule
+slug: typescript-version
+title: TypeScript 7 required at consumers
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - package-conventions
+  - ci-test-perf
+created: "2026-07-24"
+last_reviewed: "2026-07-24"
+paths:
+  - "pnpm-workspace.yaml"
+  - "**/package.json"
+---
+
+# TypeScript 7 required at consumers
+
+The Webpresso toolchain runs on **TypeScript 7** — the native (Go) compiler that
+`tsc` resolves to since the 7.0 GA. Consumer repos must stay on the 7 major so
+their typecheck, build, and shipped `.d.ts` match the compiler agent-kit ships
+and tests against.
+
+## What is enforced
+
+`wp audit typescript-version` (bundled in `wp audit guardrails`, so it runs in
+every consumer CI that calls guardrails, and updates automatically on the next
+`wp` / agent-kit bump — no CI edits) fails when the `typescript` compiler
+dependency is pinned below major 7, in either:
+
+- the `catalog.typescript` pin in `pnpm-workspace.yaml`, or
+- a direct `typescript` dependency/devDependency in any `package.json`
+  (`catalog:` / `workspace:` references are skipped — they resolve through the
+  catalog, which is checked directly).
+
+## `@typescript/typescript6` is allowed — it is not legacy
+
+TypeScript 7's **programmatic** compiler API is not stable until 7.1, so tooling
+that calls the compiler API (e.g. `wp typecheck`) bridges through
+`@typescript/typescript6`, the Microsoft-published TS6 compiler-API
+compatibility package. That is a distinct dependency from the `typescript`
+compiler and is **never** flagged by this audit. Keep `typescript` on `^7` and
+`@typescript/typescript6` on `^6` — do not downgrade the `typescript` compiler.
+
+## Temporary exception
+
+A consumer mid-migration may add a `typescript-version-allow` comment in
+`pnpm-workspace.yaml` (or the manifest) to suppress the check. Treat it as
+temporary and remove it once the repo is on TypeScript 7.

package/catalog/agent/rules/workflow-skills-routing.md

@@ -74,8 +74,10 @@ Map routing intent like this:
 - debugging and regressions → `investigate` then `fix`
 - bounded cleanup after behavior is green → `ai-deslop`
 - multi-task / parallel execute → `ultragoal` + `/pll` (ready-queue, worktrees)
-- local completeness → `/verify`; merge-ready outside voice → `/verify --merge-ready`
-  (exactly one sequential outside reviewer unless user sets N)
+- local completeness → `/verify` then `wp ci-preflight` before push; merge-ready
+  outside voice → `/verify --merge-ready` (exactly one sequential outside
+  reviewer unless user sets N). Do not use remote CI as the first debugger
+  (`ci-cost-local-first`).
 
 Use the full `wp_*` MCP surface for tests, lint, typecheck, audits, session memory,
 ultragoal, worktrees, PRs, and quality gates — not shell reimplementations. Use

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

@@ -8,13 +8,37 @@ license: MIT
 
 Use this skill from Claude or another non-Codex host when the user wants Codex to independently review a diff, challenge a plan, or answer a repo question. Keep Codex read-only by default and treat its answer as external advice until independently verified.
 
+## Primary path: the `wp_review_run` MCP tool
+
+When the webpresso MCP server is available, call `wp_review_run` directly instead of any bash block below — it is the same `wp review run` typed runtime, called in-process, with two ergonomic wins: it takes a `prompt` string (no `--prompt-file` bookkeeping) and it runs the probe stage and the review stage in **one call** by default (the review stage is skipped automatically if the probe fails, so you never waste a full review invocation on a cold/broken provider).
+
+```jsonc
+// wp_review_run MCP tool call
+{
+  "prompt": "<diff summary + what to look for>",
+  "provider": "codex",
+  // model, effort, artifactRoot, idleSeconds are all optional and default
+  // the same way the `wp review run` CLI does. Omit `stage` for automatic
+  // probe-then-review; pass stage: "probe" or stage: "review" only for
+  // manual single-stage control.
+}
+```
+
+**Provider fallback lives in this one call.** If your primary provider (e.g. Codex) is unavailable — out of credits, auth expired — switch the `provider` parameter to another supported value (`claude`, `opencode`, `grok`) in the SAME `wp_review_run` call. Never shell into a different provider's CLI directly; that bypasses artifact capture under `.webpresso/reviews`, availability tracking, and the probe-then-review handshake this tool exists to provide. The pretool guard hook actively blocks shelling straight into a provider CLI's review-launching subcommand and redirects here.
+
+The bash blocks in this skill (below) are the **MCP-unavailable fallback only** — use them when the webpresso MCP server itself is not reachable in the current host, not as a provider-fallback mechanism.
+
 ## Single-shot budget (anti-stampede)
 
 - Default: **one** review invocation per request.
 - Do **not** fan out parallel multi-host review matrices unless the user set `review_budget`/`N` > 1.
-- Prefer `wp review run` / `wp review gate` over spawn/wait agent loops for review.
+- Prefer `wp_review_run` (MCP) or `wp review run` / `wp review gate` (CLI fallback) over spawn/wait agent loops for review.
 - Keep prompts bounded; no whole-repo paste.
 
+## MCP-unavailable fallback (raw CLI)
+
+Everything from here down is the manual `wp review run` CLI path documented for hosts or sessions where the webpresso MCP server is not reachable. Prefer `wp_review_run` above whenever MCP is available.
+
 ## Auth check
 
 ```bash

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

@@ -122,12 +122,15 @@ Run the narrowest checks that prove the repaired behavior on the real repo surfa
 - `wp_test` / targeted tests for the repaired path
 - `wp_lint` / `wp_typecheck` for changed surfaces
 - `wp_qa` only when the blast radius needs the bookend
+- Before push: `wp ci-preflight` (local pre-push owner). Do not use remote CI
+  re-runs as the primary fix loop (`ci-cost-local-first`).
 
 Rules:
 
 - Prefer MCP `wp_*` over raw host Bash.
 - Reuse fresh logs / session-memory indexed output; do not re-run long commands just to re-read.
 - Read the exit code and summary before making a claim.
+- Never `git push --no-verify` to land an unproven fix.
 
 Escalate to `/verify <target>` (local) or `/verify <target> --merge-ready` when any of these are true:
 

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

@@ -109,6 +109,9 @@ workflow:
 1. Identify target type (file / package / blueprint slug / all).
 2. Map each claim you plan to make to the exact command or log that proves it.
 3. If the target is a blueprint slug, run the repo's blueprint show/audit surface and record the acceptance boxes that still need proof.
+4. **CI cost / local-first:** treat remote CI as confirmation, not the first
+   debugger. Load `ci-cost-local-first` expectations: no hook skips, no
+   blind `gh run rerun`, Ubicloud for private non-release jobs.
 
 ## Phase 1 — Governance gates
 
@@ -130,12 +133,27 @@ Run the narrowest checks that prove the touched behavior:
 - `wp_test` / targeted tests
 - `wp_qa`, `wp_e2e`, build / package checks only when the change requires them
 
+**Before push or PR open/update**, run the pre-push owner end-to-end:
+
+```bash
+wp ci-preflight
+```
+
+That is fail-fast branch-scoped format → guardrails → typecheck → lint →
+test. Agent-kit itself enforces it from `.husky/pre-push`; consumer repos may
+keep pre-push checks user-owned, so run the command explicitly before pushing.
+Do **not** claim push-ready if preflight failed. Do **not** bypass hooks to ship
+red work.
+
 Rules:
 
 - Prefer MCP `wp_*` over raw underlying tools.
 - Reuse fresh logs / session-memory indexed output if the runner auto-saves them.
 - Never claim broader correctness than the commands actually proved.
 - If the repo documents a "full QA" bookend, reserve `wp_qa` / `--full` for the final broad pass rather than every iteration.
+- If CI is already red: read the failed job log, reproduce with the matching
+  local `wp` command, fix, re-run `wp ci-preflight`, then push **one**
+  corrective commit — do not burn another full matrix “to check.”
 
 ## Phase 3 — Cross-surface impact scan
 
@@ -217,8 +235,10 @@ Reviewer preference (pick **one** path):
 
 Approval evidence requirements:
 
-- Blueprint lifecycle: `wp review gate <blueprint-slug> --target HEAD --json` first.
-  Use `wp review log` / `wp review read` for inspection.
+- Blueprint lifecycle: `wp review gate <blueprint-slug> --purpose delivery --target HEAD --json`
+  first. Delivery gates automatically run declared Promotion Gates from the
+  Trust Dossier before outside-review provider probes. Use `wp review log` /
+  `wp review read` for inspection.
 - Each reviewer must return clear `APPROVED`/`BLOCKED` with enough evidence.
 - Record as PR comments when a PR exists (model/tool, verdict, reviewed commit).
 - Unavailable reviewer → try next preferred; if still short, report gap and

package/catalog/docs/templates/blueprint.md

@@ -22,7 +22,7 @@ approvals: [] # Legacy approval mirror; authority may also come from v2 review-e
 - Draft slug: `{{slug}}`
 - Output path: `{{output_path}}`
 - Generated command: `wp blueprint new "{{description}}" --complexity {{complexity}}`
-- Default shape: folder (`blueprints/<status>/<slug>/_overview.md`, with sibling `reviews.md` for approvals); flat `blueprints/<status>/<slug>.md` is legacy-valid
+- Default shape: folder (`blueprints/<status>/<slug>/_overview.md`, with sibling `reviews.md` for approvals); flat `blueprints/<status>/<slug>.md` stays readable but cannot hold review evidence, ledgers, or approvals — run `wp blueprint canonicalize <slug>` first
 - Validation scope: parser compliance before write
 
 ## Architecture Overview

package/dist/esm/audit/agents.js

@@ -13,6 +13,7 @@ const REQUIRED_SUBAGENTS = [
     "security-auditor.md",
     "doc-writer.md",
     "explorer.md",
+    "implementer.md",
 ];
 const EXPLORER_CONTRACT_MARKERS = [
     "3–5 tool calls",

package/dist/esm/audit/blueprint-lifecycle-sql.d.ts

@@ -35,4 +35,16 @@ export interface BlueprintLifecycleAuditOptions {
      */
     readonly affectedFiles?: readonly string[];
 }
+/**
+ * Decide the file scope for the per-file `runBlueprintAudit` pass. In
+ * changed-only mode with a resolved changed scope, audit only the changed
+ * blueprint files (bounded, pre-commit-fast); otherwise audit the whole corpus
+ * (`all: true`, the CI-grade pass). Extracted + exported so the scoping contract
+ * is unit-testable without standing up the full corpus.
+ */
+export declare function resolveRunBlueprintAuditScope(changedOnly: boolean, changedFiles: ReadonlySet<string> | null): {
+    readonly stagedFiles: string[];
+} | {
+    readonly all: true;
+};
 export declare function auditBlueprintLifecycleSql(cwd?: string, options?: BlueprintLifecycleAuditOptions): Promise<RepoAuditResult>;

package/dist/esm/audit/blueprint-lifecycle-sql.js

@@ -357,17 +357,20 @@ function listTrackedBlueprintPaths(cwd) {
 }
 function changedBlueprintScope(candidates) {
     const slugs = new Set();
+    const files = new Set();
     for (const [currentPath, candidate] of candidates) {
+        files.add(currentPath);
         const currentSlug = blueprintSlugFromGitPath(currentPath);
         if (currentSlug)
             slugs.add(currentSlug);
         for (const previousPath of candidate.previousPaths) {
+            files.add(previousPath);
             const previousSlug = blueprintSlugFromGitPath(previousPath);
             if (previousSlug)
                 slugs.add(previousSlug);
         }
     }
-    return { slugs };
+    return { slugs, files };
 }
 /**
  * When `--affected` supplies an explicit file set (pre-commit staged files or
@@ -435,6 +438,19 @@ function readPreviousLifecycleStatusFromCandidate(cwd, row, candidate, trackedPa
     }
     return null;
 }
+/**
+ * Decide the file scope for the per-file `runBlueprintAudit` pass. In
+ * changed-only mode with a resolved changed scope, audit only the changed
+ * blueprint files (bounded, pre-commit-fast); otherwise audit the whole corpus
+ * (`all: true`, the CI-grade pass). Extracted + exported so the scoping contract
+ * is unit-testable without standing up the full corpus.
+ */
+export function resolveRunBlueprintAuditScope(changedOnly, changedFiles) {
+    if (changedOnly && changedFiles !== null) {
+        return { stagedFiles: [...changedFiles] };
+    }
+    return { all: true };
+}
 export async function auditBlueprintLifecycleSql(cwd = process.cwd(), options = {}) {
     const budgets = loadBudgets(cwd);
     const wipInProgressMax = budgets["blueprint-wip-in-progress-max"].max ?? 3;
@@ -522,10 +538,15 @@ export async function auditBlueprintLifecycleSql(cwd = process.cwd(), options =
     if (options.changedOnly && changedScope) {
         titleNotices.push(`changed-only: ${changedScope.slugs.size} blueprint(s)`);
     }
+    // In changed-only mode, scope the per-file blueprint audit to the changed
+    // blueprints. Auditing all blueprints (`all: true`) parses and validates the
+    // entire corpus (~1300 files, ~70s) even for a one-blueprint change — far too
+    // slow for the pre-commit hot path. The whole-corpus pass is CI's job; the
+    // structural + SQL projection checks below still run over every blueprint.
     const { runBlueprintAudit } = await import("../blueprint/lifecycle/audit.js");
     const lifecycle = await runBlueprintAudit({
         projectRoot: cwd,
-        all: true,
+        ...resolveRunBlueprintAuditScope(options.changedOnly === true, changedScope?.files ?? null),
         completedApprovalGate: options.changedOnly === true,
         inProgressApprovalGate: options.changedOnly === true,
         strict: true,

package/dist/esm/audit/blueprint-pr-coverage.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { relative } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 const TITLE = "Blueprint PR coverage";
 const BLUEPRINT_EXEMPT_PATTERN = /^Blueprint-exempt:\s*(\S.*)$/im;
@@ -39,14 +40,33 @@ export function auditBlueprintPrCoverage(rootDirectory = process.cwd(), options
     const configuredRoot = normalizeRoot(normalizePath(relative(rootDirectory, resolveBlueprintRoot(rootDirectory))));
     const blueprintRoots = [...new Set(["blueprints", configuredRoot].filter(Boolean))];
     const finalEntries = entries.filter((entry) => entry.status !== "D");
-    const activePaths = finalEntries.filter((entry) => {
+    const activeEntries = finalEntries.flatMap((entry) => {
         const location = parseBlueprintLocation(entry.path, blueprintRoots);
-        return location !== null && ACTIVE_LIFECYCLE_DIRECTORIES.has(location.lifecycle);
+        if (!location || !ACTIVE_LIFECYCLE_DIRECTORIES.has(location.lifecycle))
+            return [];
+        return [{ entry, location }];
     });
-    if (activePaths.length > 0) {
-        return fail(`non-doc landing PR leaves changed active blueprint content at ${activePaths
-            .map((entry) => entry.path)
-            .join(", ")}; move the owner blueprint to completed before merge`, changedFiles.length);
+    const ownerActive = activeEntries.filter(({ location }) => location.slug === ownerSlug);
+    if (ownerActive.length > 0) {
+        return fail(`non-doc landing PR leaves owner blueprint "${ownerSlug}" in active lifecycle at ${ownerActive
+            .map(({ entry }) => entry.path)
+            .join(", ")}; move completed/${ownerSlug}/_overview.md (or .md) into the PR and drop active-lifecycle owner paths`, changedFiles.length);
+    }
+    // Parent-roadmap program trackers may co-edit on a child land PR while still
+    // active (draft/planned). Executable blueprints (type: blueprint) may not.
+    const nonOwnerActive = activeEntries.filter(({ location }) => location.slug !== ownerSlug);
+    const programTrackers = [];
+    const blockingNonOwner = [];
+    for (const { entry, location } of nonOwnerActive) {
+        if (isParentRoadmapDocument(rootDirectory, entry.path, location)) {
+            programTrackers.push(entry.path);
+        }
+        else {
+            blockingNonOwner.push(entry.path);
+        }
+    }
+    if (blockingNonOwner.length > 0) {
+        return fail(`non-doc landing PR changes active non-owner blueprint content at ${blockingNonOwner.join(", ")}; remove those paths from the PR or complete those blueprints first (owner ${ownerSlug} is separate)`, changedFiles.length);
     }
     const matchingCompletedOwner = finalEntries.some((entry) => {
         const location = parseBlueprintLocation(entry.path, blueprintRoots);
@@ -55,6 +75,9 @@ export function auditBlueprintPrCoverage(rootDirectory = process.cwd(), options
     if (!matchingCompletedOwner) {
         return fail(`non-doc PR on ${headRef} must change its completed owner blueprint at completed/${ownerSlug}/_overview.md (or completed/${ownerSlug}.md)`, changedFiles.length);
     }
+    if (programTrackers.length > 0) {
+        return passWithWarning(`[warn] co-edited parent-roadmap program tracker(s) on non-doc land: ${programTrackers.join(", ")}`, changedFiles.length);
+    }
     return pass(changedFiles.length);
 }
 function pass(checked) {
@@ -134,6 +157,44 @@ function parseBlueprintLocation(filePath, roots) {
     }
     return null;
 }
+/**
+ * True when the changed path belongs to a `type: parent-roadmap` document.
+ * Nested non-overview files under a parent-roadmap folder inherit the overview
+ * type so review artifacts co-travel. Missing paths (unit-test fakes) return
+ * false → fail closed as executable blueprints.
+ */
+function isParentRoadmapDocument(rootDirectory, filePath, location) {
+    const normalized = normalizePath(filePath);
+    const overviewCandidates = [
+        // Prefer the changed overview when it is the document itself.
+        ...(location.ownerDocument ? [normalized] : []),
+        // folder overview: …/<lifecycle>/<slug>/_overview.md
+        normalized.replace(new RegExp(`/(draft|planned|in-progress|parked|completed|archived)/${escapeRegex(location.slug)}(?:/.*)?$`, "u"), `/$1/${location.slug}/_overview.md`),
+        // flat overview: …/<lifecycle>/<slug>.md
+        normalized.replace(new RegExp(`/(draft|planned|in-progress|parked|completed|archived)/${escapeRegex(location.slug)}(?:/.*|\\.md)?$`, "u"), `/$1/${location.slug}.md`),
+    ];
+    const seen = new Set();
+    for (const candidate of overviewCandidates) {
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        const abs = join(rootDirectory, candidate);
+        if (!existsSync(abs))
+            continue;
+        try {
+            const head = readFileSync(abs, "utf8").slice(0, 4_096);
+            if (/^type:\s*['"]?parent-roadmap['"]?\s*$/mu.test(head))
+                return true;
+        }
+        catch {
+            // unreadable → fail closed
+        }
+    }
+    return false;
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
 function isDependabotDependencyOnlyUpdate(cwd, options, changedFiles) {
     if (!changedFiles.every(isDependabotDependencyFile))
         return false;
@@ -201,6 +262,10 @@ function isDependabotDependencyFile(filePath) {
         normalized === "bun.lockb" ||
         normalized === "deno.lock" ||
         normalized === "pnpm-workspace.yaml" ||
+        normalized === "Cargo.toml" ||
+        normalized.endsWith("/Cargo.toml") ||
+        normalized === "Cargo.lock" ||
+        normalized.endsWith("/Cargo.lock") ||
         (normalized.startsWith(".github/workflows/") && /\.ya?ml$/u.test(basename)));
 }
 function normalizeHeadRef(value) {