@webpresso/agent-kit 3.1.28 → 3.1.30

package/catalog/AGENTS.md.tpl

@@ -63,10 +63,10 @@ asynchronously.
 
 ## Verify
 
-Before claiming completion, run the narrowest checks that prove the change:
-MCP/`wp` quality tools, typecheck, lint/format, affected tests, policy checks,
-docs/blueprint validation when those changed, and `wp sync --check` after
-template/catalog changes. On failure, fix root cause or record the blocker.
+Before claiming completion, run the narrowest MCP/`wp` checks that prove the
+change: typecheck, lint/format, affected tests, policy, docs/blueprint, and
+`wp sync --check` after template/catalog changes. Fix root cause or record the
+blocker. Before pushing, run `wp ci-preflight` (see `ci-cost-local-first`).
 
 ## Communicate
 

package/catalog/agent/rules/ci-cost-local-first.md

@@ -0,0 +1,139 @@
+---
+type: rule
+slug: ci-cost-local-first
+title: CI cost and local-first gates
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - cmd-execution
+  - ci-test-perf
+  - pre-implementation
+  - hook-hot-path
+  - no-timeout-as-fix
+created: "2026-07-21"
+last_reviewed: "2026-07-21"
+paths:
+  - ".github/workflows/**"
+  - "catalog/agent/**"
+  - "AGENTS.md"
+  - ".husky/**"
+---
+
+# CI cost and local-first gates
+
+Agents waste money when they treat remote CI as the primary debugger.
+**Catch failures locally first.** Remote CI is confirmation, not exploration.
+
+Monthly spend on private repos (Ubicloud + GitHub-hosted minutes + artifact
+storage) is a product constraint. Prefer cheap local loops over burning full
+PR matrices to discover format/lint/type/test/governance failures.
+
+## Iron law
+
+1. **Never open or update a PR you already know will fail** a locally-runnable
+   gate (format, guardrails, typecheck, lint, affected tests, PR body contract,
+   changeset/blueprint trailers when applicable).
+2. **Never use `git push --no-verify` / `HUSKY=0` / skip hooks** to “save
+   time.” That only moves the failure to paid CI and trains a red-loop habit.
+3. **Never re-run a failed CI job “to see if it flaked”** until you have a
+   local reproduction or a concrete flake hypothesis with evidence.
+4. **Never add GitHub-hosted runners** (`ubuntu-latest`, `macos-*`,
+   `windows-*`) on private-repo workflows except the **Release / npm OIDC
+   publish** path (and release-native targets that truly need that OS). Default
+   is **Ubicloud** (`ubicloud-standard-2` / `-4` only when justified).
+
+## Local gate stack (must pass before push)
+
+| When                       | Command / check                                                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Every commit               | Managed pre-commit (format + staged guardrails)                                                                                  |
+| Every push                 | `wp ci-preflight` before pushing; in agent-kit itself this is also enforced by `.husky/pre-push`                                 |
+| Before PR open / body edit | PR template fields filled; trailers exact (`Blueprint-exempt`, `Changeset-exempt`, `Review-skip` as **start-of-line** when used) |
+| Before claim merge-ready   | `/verify <target>` then `/verify <target> --merge-ready` when landing                                                            |
+
+`wp ci-preflight` is fail-fast and **branch-scoped**:
+
+1. `wp format --affected --branch --check`
+2. `wp audit guardrails --affected --branch`
+3. `wp typecheck --affected --branch`
+4. `wp lint --affected --branch`
+5. `wp test --affected --branch`
+
+If preflight fails: **fix locally**, do not push. Reproduce with the printed
+`wp …` line.
+
+### Bootstrap before preflight
+
+Missing `node_modules` in a worktree → run `wp install` (or the repo’s setup),
+then preflight. Use `vp install` only when `wp` has no equivalent. Do not push a
+bare worktree “to let CI install.”
+
+## Cost model (private repos)
+
+| Resource                       | Cost driver                                       | Agent duty                                     |
+| ------------------------------ | ------------------------------------------------- | ---------------------------------------------- |
+| Ubicloud minutes               | Every PR job matrix (lint, tests, smokes, shards) | Local preflight; avoid drive-by full re-runs   |
+| GitHub-hosted `ubuntu-latest`  | Billable Actions minutes                          | Only release/OIDC publish unless proven needed |
+| GitHub `macos-*` / `windows-*` | ~10× Linux minutes                                | Release natives only; never default PR CI      |
+| Actions artifacts / caches     | Storage quota; can block Release uploads          | Prefer short retention; do not spam artifacts  |
+| Failed CI loops                | Full matrix × attempts                            | Fix from logs locally before `gh run rerun`    |
+
+Related: `ci-test-perf.md` (keep coverage; speed via workers/cache/shards — not
+by skipping tests). Prefer **fewer/cheaper runners + sharding** over raising
+timeouts (`no-timeout-as-fix.md`).
+
+## Workflow authoring (when you touch CI)
+
+- Private non-release jobs: `runs-on: ubicloud-standard-2` by default.
+- Use `ubicloud-standard-4` only when wall-time evidence shows standard-2 is
+  insufficient **with** full coverage and workers (document why).
+- Release publish job may use `ubuntu-latest` for npm trusted publishing /
+  provenance. Session-memory / platform native matrices that require Darwin or
+  Windows may use GH-hosted OS runners **only on the Release (publish=true)
+  path**, never on ordinary PR CI.
+- Path filters, `concurrency` cancel-in-progress, and change-scope skips are
+  preferred over always-on heavy jobs.
+- Do not add nightly/macOS “perf” jobs that run on every PR; keep them opt-in
+  (`workflow_dispatch`, label, or schedule) and prefer Ubicloud for any check
+  that is not Apple-signing/display-bound.
+
+## PR governance without burning CI
+
+These fail **before** expensive tests if you get them wrong — fix **before**
+push/open:
+
+- PR description AI/model disclosure + `Session id` (or `Session-skip`)
+- `Review-skip: SKIP <reason>` must match `^Review-skip:` at **line start**
+  (not nested under a bullet)
+- `Blueprint-exempt:` / `Changeset-exempt:` in **commit message** and/or body
+  when required (blueprint-pr-coverage reads **git trailers**, not only the PR body)
+- Version Packages / bot CI: do not invent admin-merge; use the runbook
+  (`docs/runbooks/version-packages-bot-ci.md` when present)
+
+## Forbidden agent habits
+
+- Push → watch red CI → tweak → push again (the “CI as unit test” loop)
+- Broaden CI timeouts / disable flakes instead of root-cause fix
+- Schedule or matrix-expand macOS/Windows for convenience
+- Upload large artifacts every PR “for debugging”
+- Claim “CI is green” from a partial check while WP check / required jobs pending
+- Force-push past hooks to land red work for “later fix”
+
+## Good loop
+
+```text
+edit → scoped lint/type/test → commit (hooks) → wp ci-preflight → push
+→ open PR with complete body → watch CI once → fix root cause locally if red
+```
+
+When CI fails: download/read the failed job log, reproduce with the matching
+local `wp` command, fix, preflight, push **one** corrective commit.
+
+## Related
+
+- `cmd-execution.md` — bookend QA; scoped commands in the middle
+- `ci-test-perf.md` — parallelism and install cache
+- `pre-implementation.md` — blueprint gates that only fail in CI if left open
+- `hook-hot-path.md` — pre-push stays local and non-network
+- CLI: `wp ci-preflight` (pre-push owner)

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

@@ -56,9 +56,13 @@ Mutation/Stryker jobs are auto-exempt when the step/job name or nearby lines men
 When a single job still exceeds budget **with full coverage**:
 
 1. Prefer **Vitest sharding** (`vitest run --shard=i/n` + blob reporter merge) over raising isolation-off globally.
-2. Prefer a **larger runner** (`ubicloud-standard-4`, etc.) + more `VITEST_MAX_WORKERS` over dropping suites.
+2. Prefer a **larger runner** (`ubicloud-standard-4`, etc.) + more `VITEST_MAX_WORKERS` over dropping suites — only after `ubicloud-standard-2` is proven insufficient. Do not jump to GitHub-hosted macOS/Windows for ordinary test jobs.
 3. Cache **native/build artifacts** when warm steps rebuild every PR (producer-specific).
 
+Private-repo default is **Ubicloud** for non-release jobs. GitHub-hosted
+runners are reserved for Release/OIDC publish (and release-native OS builds).
+See `ci-cost-local-first.md`.
+
 ## Related
 
 - Vitest performance: https://vitest.dev/guide/improving-performance

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

@@ -14,6 +14,15 @@ paths:
 
 # Command Execution Rules
 
+## Local-first before remote CI
+
+Paid CI (Ubicloud + GitHub-hosted) is for confirmation. Use scoped commands
+while iterating, then **`wp ci-preflight` before every push**. In agent-kit
+itself, `.husky/pre-push` enforces that gate; consumer templates may leave
+pre-push checks user-owned. Never `git push --no-verify` to skip a configured
+local gate. See `ci-cost-local-first.md` for runner policy and anti-red-loop
+habits.
+
 ## BOOKEND Rule: Full QA Runs Exactly Twice
 
 The full QA pipeline (e.g. `wp qa`, `bun run qa`) is a

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

@@ -264,7 +264,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/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/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/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
 

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;

package/dist/esm/audit/registry.d.ts

@@ -14,11 +14,11 @@ export interface AuditKindDescriptor {
 }
 export declare const SCRIPT_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e"];
 export declare const SPECIAL_AUDIT_KIND_IDS: readonly ["bundle-budget", "commit-message", "blueprint-pr-coverage", "mutation", "guardrails", "quality"];
-export declare const REPO_AUDIT_KIND_IDS: readonly ["catalog-drift", "package-surface", "command-surface", "reference-parity-matrix", "blueprint-readme-drift", "blueprint-lifecycle", "blueprint-trust", "roadmap-links", "docs-frontmatter", "agents", "vision", "tech-debt", "supported-agent-clis", "no-relative-parent-imports", "no-link-protocol", "no-relative-package-scripts", "test-isolation", "bucket-boundary", "skill-sizes", "broken-refs", "memory-rotation", "gitignore-agent-surfaces", "memory-unified", "compile-drift", "no-legacy-cli-bin", "architecture-drift", "cloudflare-deploy-contract", "toolchain-isolation", "absolute-path-policy", "no-first-party-mjs", "outside-review-runtime-ownership", "no-math-random", "agent-cost", "blueprint-db-consistency", "tech-debt-cadence", "cross-repo-correlation", "ai-contracts", "atomic-state-writes", "hook-surface", "hook-vendor-drift", "session-memory-hardcut", "open-source-licenses", "secrets-policy", "no-dev-vars", "secret-provider-quarantine", "github-actions-secrets", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "legacy-workflow-identity", "rules", "skills"];
+export declare const REPO_AUDIT_KIND_IDS: readonly ["catalog-drift", "package-surface", "command-surface", "reference-parity-matrix", "blueprint-readme-drift", "blueprint-lifecycle", "blueprint-trust", "roadmap-links", "docs-frontmatter", "agents", "vision", "tech-debt", "supported-agent-clis", "no-relative-parent-imports", "no-link-protocol", "no-relative-package-scripts", "test-isolation", "bucket-boundary", "skill-sizes", "broken-refs", "memory-rotation", "gitignore-agent-surfaces", "memory-unified", "compile-drift", "no-legacy-cli-bin", "architecture-drift", "cloudflare-deploy-contract", "toolchain-isolation", "absolute-path-policy", "no-first-party-mjs", "outside-review-runtime-ownership", "no-math-random", "agent-cost", "blueprint-db-consistency", "tech-debt-cadence", "cross-repo-correlation", "ai-contracts", "atomic-state-writes", "hook-surface", "hook-vendor-drift", "session-memory-hardcut", "open-source-licenses", "secrets-policy", "no-dev-vars", "secret-provider-quarantine", "github-actions-secrets", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "legacy-workflow-identity", "rules", "skills"];
 export declare const AUDIT_KIND_DESCRIPTORS: readonly AuditKindDescriptor[];
-export declare const AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", ...("absolute-path-policy" | "agent-cost" | "agents" | "ai-contracts" | "architecture-drift" | "atomic-state-writes" | "blueprint-db-consistency" | "blueprint-lifecycle" | "blueprint-pr-coverage" | "blueprint-readme-drift" | "blueprint-trust" | "broken-refs" | "bucket-boundary" | "bundle-budget" | "catalog-drift" | "ci-test-perf" | "cloudflare-deploy-contract" | "command-surface" | "commit-message" | "compile-drift" | "consumer-agent-kit-dependency" | "cross-repo-correlation" | "docs-frontmatter" | "github-actions-secrets" | "gitignore-agent-surfaces" | "guardrails" | "harness-overlay-evidence" | "harness-surfaces" | "hook-surface" | "hook-vendor-drift" | "legacy-workflow-identity" | "memory-rotation" | "memory-unified" | "mutation" | "no-dev-vars" | "no-first-party-mjs" | "no-legacy-cli-bin" | "no-link-protocol" | "no-math-random" | "no-relative-package-scripts" | "no-relative-parent-imports" | "open-source-licenses" | "outside-review-runtime-ownership" | "package-surface" | "quality" | "reference-parity-matrix" | "roadmap-links" | "rules" | "sast" | "secret-provider-quarantine" | "secrets-config" | "secrets-policy" | "security-quality-regressions" | "session-memory-hardcut" | "skill-sizes" | "skills" | "supported-agent-clis" | "tech-debt" | "tech-debt-cadence" | "test-isolation" | "toolchain-isolation" | "vision" | "weakness-mining" | "worktree-main-ownership")[]];
-export declare const MCP_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", "agents", "catalog-drift", "package-surface", "reference-parity-matrix", "docs-frontmatter", "blueprint-readme-drift", "blueprint-pr-coverage", "blueprint-lifecycle", "blueprint-trust", "architecture-drift", "cloudflare-deploy-contract", "absolute-path-policy", "no-first-party-mjs", "no-math-random", "roadmap-links", "bundle-budget", "commit-message", "tech-debt", "supported-agent-clis", "hook-surface", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "ai-contracts", "atomic-state-writes", "no-relative-package-scripts", "toolchain-isolation", "open-source-licenses", "secrets-policy", "no-dev-vars", "github-actions-secrets", "secret-provider-quarantine", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "session-memory-hardcut", "worktree-main-ownership", "sast"];
-export declare const AFFECTED_SAFE_AUDIT_KIND_IDS: readonly ["blueprint-readme-drift", "blueprint-lifecycle", "bucket-boundary", "skill-sizes", "broken-refs", "no-dev-vars", "absolute-path-policy", "secret-provider-quarantine", "secrets-config", "docs-frontmatter", "no-relative-parent-imports", "no-link-protocol", "no-first-party-mjs", "no-math-random"];
+export declare const AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", ...("absolute-path-policy" | "agent-cost" | "agents" | "ai-contracts" | "architecture-drift" | "atomic-state-writes" | "blueprint-db-consistency" | "blueprint-lifecycle" | "blueprint-pr-coverage" | "blueprint-readme-drift" | "blueprint-trust" | "broken-refs" | "bucket-boundary" | "bundle-budget" | "catalog-drift" | "ci-test-perf" | "cloudflare-deploy-contract" | "command-surface" | "commit-message" | "compile-drift" | "consumer-agent-kit-dependency" | "cross-repo-correlation" | "docs-frontmatter" | "github-actions-secrets" | "gitignore-agent-surfaces" | "guardrails" | "harness-overlay-evidence" | "harness-surfaces" | "hook-surface" | "hook-vendor-drift" | "legacy-workflow-identity" | "memory-rotation" | "memory-unified" | "mutation" | "no-dev-vars" | "no-first-party-mjs" | "no-legacy-cli-bin" | "no-link-protocol" | "no-math-random" | "no-relative-package-scripts" | "no-relative-parent-imports" | "open-source-licenses" | "outside-review-runtime-ownership" | "package-surface" | "quality" | "reference-parity-matrix" | "roadmap-links" | "rules" | "sast" | "secret-provider-quarantine" | "secrets-config" | "secrets-policy" | "security-quality-regressions" | "session-memory-hardcut" | "skill-sizes" | "skills" | "supported-agent-clis" | "tech-debt" | "tech-debt-cadence" | "test-isolation" | "test-scan-perf" | "toolchain-isolation" | "vision" | "weakness-mining" | "worktree-main-ownership")[]];
+export declare const MCP_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", "agents", "catalog-drift", "package-surface", "reference-parity-matrix", "docs-frontmatter", "blueprint-readme-drift", "blueprint-pr-coverage", "blueprint-lifecycle", "blueprint-trust", "architecture-drift", "cloudflare-deploy-contract", "absolute-path-policy", "no-first-party-mjs", "no-math-random", "roadmap-links", "bundle-budget", "commit-message", "tech-debt", "supported-agent-clis", "hook-surface", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "ai-contracts", "atomic-state-writes", "no-relative-package-scripts", "toolchain-isolation", "open-source-licenses", "secrets-policy", "no-dev-vars", "github-actions-secrets", "secret-provider-quarantine", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "session-memory-hardcut", "worktree-main-ownership", "sast"];
+export declare const AFFECTED_SAFE_AUDIT_KIND_IDS: readonly ["blueprint-readme-drift", "blueprint-lifecycle", "bucket-boundary", "skill-sizes", "broken-refs", "no-dev-vars", "absolute-path-policy", "secret-provider-quarantine", "secrets-config", "docs-frontmatter", "no-relative-parent-imports", "no-link-protocol", "no-first-party-mjs", "no-math-random", "test-scan-perf"];
 export type AuditKindId = (typeof AUDIT_KIND_IDS)[number];
 export type RepoAuditKindId = (typeof REPO_AUDIT_KIND_IDS)[number];
 export type MCPAuditKindId = (typeof MCP_AUDIT_KIND_IDS)[number];

package/dist/esm/audit/registry.js

@@ -16,6 +16,7 @@ const affectedSafeKinds = [
     "no-link-protocol",
     "no-first-party-mjs",
     "no-math-random",
+    "test-scan-perf",
 ];
 const mcpKindIds = [
     "test-smells",
@@ -56,6 +57,7 @@ const mcpKindIds = [
     "secrets-config",
     "consumer-agent-kit-dependency",
     "ci-test-perf",
+    "test-scan-perf",
     "session-memory-hardcut",
     "worktree-main-ownership",
     "sast",
@@ -130,6 +132,7 @@ const repoKinds = [
     "secrets-config",
     "consumer-agent-kit-dependency",
     "ci-test-perf",
+    "test-scan-perf",
     "worktree-main-ownership",
     "sast",
     "harness-surfaces",

package/dist/esm/audit/roadmap-links.js

@@ -58,7 +58,13 @@ export function auditRoadmapLinks(rootDirectory = process.cwd(), options = {}) {
                 message: "Parent-roadmap execution-wave maps may list local child blueprints only; move cross-repo references to Cross-Plan References and use GitHub links there",
             });
         }
+        // Archived parent-roadmaps are non-executable program records. They may
+        // document completed children without a live execution-wave map or local
+        // children still declaring parent_roadmap. Do not fail CI on that residue.
         if (waveMapChildren.size === 0 && localChildren.length === 0) {
+            if (roadmap.status === "archived") {
+                continue;
+            }
             violations.push({
                 file: roadmap.file,
                 message: "Roadmap declares no children in its wave map",

package/dist/esm/audit/test-scan-perf.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Guardrail: keep tests from silently growing multi-second / multi-ten-second
+ * full-repo filesystem scans, and from "fixing" that cost with elevated
+ * per-test timeouts.
+ *
+ * The private-UI cutover anti-regression suite originally walked the monorepo
+ * with readdirSync/statSync/readFileSync and needed a 30s timeout. Prefer
+ * `git grep` (tracked files) or a bounded fixture tree instead.
+ *
+ * Opt-out: `// test-scan-perf-allow` on the same line or previous line as the
+ * walk/timeout site, or `// test-scan-perf-allow-file` anywhere in the file.
+ */
+import type { RepoAuditResult, RepoAuditViolation } from "./repo-guardrails.js";
+export declare function isTestScanPerfTargetPath(relativePath: string): boolean;
+export declare function findTestScanPerfViolationsInText(relativePath: string, text: string): RepoAuditViolation[];
+export declare function auditTestScanPerf(rootDirectory?: string, options?: {
+    affectedFiles?: readonly string[];
+}): RepoAuditResult;