@webpresso/agent-kit 3.1.30 → 3.3.0

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/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/verify/SKILL.md

@@ -235,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

@@ -262,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) {

package/dist/esm/audit/blueprint-trust.js

@@ -4,15 +4,16 @@ import matter from "gray-matter";
 import { parseTrustDossier } from "#trust/dossier.js";
 import { validateBlueprintTrust } from "#trust/validator.js";
 import { parseBlueprintDocumentRelativePath } from "#utils/document-paths.js";
+import { stableSlugForBlueprintFile } from "#lifecycle/review-provenance.js";
+import { isBlueprintExemptFromRollout, ROLLOUT_DATE } from "#lifecycle/rollout-anchor.js";
 const EXECUTABLE_DIRS = ["planned", "in-progress", "completed"];
-const TRUST_DOSSIER_ROLLOUT_DATE = "2026-07-12";
 export function auditBlueprintTrust(rootDirectory = process.cwd()) {
     const violations = [];
     let checked = 0;
     for (const file of findExecutableBlueprints(rootDirectory)) {
         checked += 1;
         const markdown = readFileSync(path.join(rootDirectory, file), "utf8");
-        const grandfatherMissingDossier = isPreContractBlueprintMissingDossier(markdown);
+        const grandfatherMissingDossier = isPreContractBlueprintMissingDossier(markdown, rootDirectory, file);
         const status = readStatus(markdown);
         const normalizedStatus = isBlueprintTrustStatus(status) ? status : "planned";
         if (!isBlueprintTrustStatus(status)) {
@@ -40,20 +41,23 @@ export function auditBlueprintTrust(rootDirectory = process.cwd()) {
     }
     return { ok: violations.length === 0, title: "Blueprint trust", checked, violations };
 }
-function isPreContractBlueprintMissingDossier(markdown) {
+function isPreContractBlueprintMissingDossier(markdown, repoRoot, file) {
     const parsedDossier = parseTrustDossier(markdown);
     if (parsedDossier.violations.length !== 1 ||
         parsedDossier.violations[0]?.section !== "Trust Dossier" ||
         parsedDossier.violations[0]?.message !== "missing Trust Dossier section") {
         return false;
     }
-    const created = matter(markdown).data["created"];
-    const createdDate = created instanceof Date
-        ? created.toISOString().slice(0, 10)
-        : typeof created === "string" && /^\d{4}-\d{2}-\d{2}$/u.test(created)
-            ? created
-            : null;
-    return createdDate !== null && createdDate < TRUST_DOSSIER_ROLLOUT_DATE;
+    // Was a compare against frontmatter `created`, which the blueprint own
+    // author controls -- writing an old date suppressed the missing-dossier
+    // violation outright. Presence at the rollout anchor commit is the
+    // unforgeable equivalent; see `#lifecycle/rollout-anchor.js`. Fails closed.
+    return isBlueprintExemptFromRollout({
+        repoRoot,
+        slug: stableSlugForBlueprintFile(file),
+        created: matter(markdown).data["created"],
+        rolloutDate: ROLLOUT_DATE,
+    });
 }
 export function findExecutableBlueprints(rootDirectory) {
     const root = path.join(rootDirectory, "blueprints");

package/dist/esm/audit/changeset-evidence.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared "does this change carry release evidence" predicate.
+ *
+ * Single source of truth for the `changeset-missing` rule described in
+ * `catalog/agent/rules/changeset-release.md`: release-visible changes need a
+ * `.changeset/*.md` entry (or an all-docs change, or a `Changeset-exempt:`
+ * trailer). Consumed by both the live-PR readiness evaluator
+ * (`#status/snapshot.js`) and the local branch-scoped audit
+ * (`#audit/changeset-required.js`) so the two verdicts can never diverge.
+ */
+export declare const CHANGESET_EXEMPT_PATTERN: RegExp;
+/**
+ * True when `files` carries release evidence for its own change: every
+ * changed file is documentation, one of the changed files is itself a
+ * `.changeset/*.md` entry, or one of `exemptionTexts` (PR body, commit
+ * messages, ...) carries a `Changeset-exempt: <reason>` trailer.
+ *
+ * Mirrors the original `wp_pr_status` behavior exactly: an empty `files` list
+ * is NOT treated as evidence (fails closed) — callers that consider "no
+ * changed files" a legitimate, non-suspicious state (e.g. a freshly rebased
+ * local branch) must short-circuit before calling this function.
+ */
+export declare function hasChangesetEvidence(files: readonly string[], exemptionTexts: readonly string[]): boolean;

package/dist/esm/audit/changeset-evidence.js

@@ -0,0 +1,30 @@
+/**
+ * Shared "does this change carry release evidence" predicate.
+ *
+ * Single source of truth for the `changeset-missing` rule described in
+ * `catalog/agent/rules/changeset-release.md`: release-visible changes need a
+ * `.changeset/*.md` entry (or an all-docs change, or a `Changeset-exempt:`
+ * trailer). Consumed by both the live-PR readiness evaluator
+ * (`#status/snapshot.js`) and the local branch-scoped audit
+ * (`#audit/changeset-required.js`) so the two verdicts can never diverge.
+ */
+const CHANGESET_FILE_PATTERN = /^\.changeset\/[^/]+\.md$/u;
+export const CHANGESET_EXEMPT_PATTERN = /Changeset-exempt:\s*\S/iu;
+/**
+ * True when `files` carries release evidence for its own change: every
+ * changed file is documentation, one of the changed files is itself a
+ * `.changeset/*.md` entry, or one of `exemptionTexts` (PR body, commit
+ * messages, ...) carries a `Changeset-exempt: <reason>` trailer.
+ *
+ * Mirrors the original `wp_pr_status` behavior exactly: an empty `files` list
+ * is NOT treated as evidence (fails closed) — callers that consider "no
+ * changed files" a legitimate, non-suspicious state (e.g. a freshly rebased
+ * local branch) must short-circuit before calling this function.
+ */
+export function hasChangesetEvidence(files, exemptionTexts) {
+    if (files.length > 0 && files.every((file) => file.endsWith(".md")))
+        return true;
+    if (files.some((file) => CHANGESET_FILE_PATTERN.test(file)))
+        return true;
+    return exemptionTexts.some((text) => CHANGESET_EXEMPT_PATTERN.test(text));
+}

package/dist/esm/audit/changeset-required.d.ts

@@ -0,0 +1,10 @@
+import type { RepoAuditResult } from "./repo-guardrails.js";
+export interface ChangesetRequiredOptions {
+    /** Base ref for the branch diff. Defaults to `origin/${GITHUB_BASE_REF:-main}`. */
+    readonly baseRef?: string;
+    /** Test/adapter seam for an already-resolved changed-file list. */
+    readonly changedFiles?: readonly string[];
+    /** Test/adapter seam for already-resolved commit messages. */
+    readonly commitMessages?: readonly string[];
+}
+export declare function auditChangesetRequired(rootDirectory?: string, options?: ChangesetRequiredOptions): RepoAuditResult;

package/dist/esm/audit/changeset-required.js

@@ -0,0 +1,73 @@
+import { spawnSync } from "node:child_process";
+import { defaultBranchBaseRef, getBranchChangedFiles } from "#git/changed-files";
+import { hasChangesetEvidence } from "./changeset-evidence.js";
+/**
+ * `wp audit changeset-required` — the local, branch-scoped mirror of the
+ * `changeset-missing` blocker `wp_pr_status` computes against a live PR (see
+ * `#status/snapshot.js`). Both call the same `hasChangesetEvidence` predicate
+ * so a locally-green `wp ci-preflight` can never diverge from the landing
+ * verdict (`catalog/agent/rules/ci-cost-local-first.md`).
+ *
+ * Unlike the PR-based check (which reads `pr.files`/`pr.body` from the GitHub
+ * API), this audit resolves its own branch diff and scans local commit
+ * messages for a `Changeset-exempt: <reason>` trailer, so it works fully
+ * offline pre-push.
+ */
+const TITLE = "Changeset required";
+const GIT_LOG_PROBE_OPTIONS = { timeout: 1_500, maxBuffer: 1024 * 1024 };
+export function auditChangesetRequired(rootDirectory = process.cwd(), options = {}) {
+    const baseRef = options.baseRef?.trim() || defaultBranchBaseRef();
+    let changedFiles;
+    if (options.changedFiles) {
+        changedFiles = options.changedFiles;
+    }
+    else {
+        const resolved = resolveChangedFiles(rootDirectory, baseRef);
+        if (resolved.error)
+            return fail(resolved.error, 0);
+        changedFiles = resolved.files;
+    }
+    if (changedFiles.length === 0) {
+        return passWithWarning(`[warn] changeset-required: no changed files vs ${baseRef} — skipping`, 0);
+    }
+    const exemptionMessages = options.commitMessages ?? readCommitMessages(rootDirectory, baseRef);
+    if (hasChangesetEvidence(changedFiles, exemptionMessages)) {
+        return pass(changedFiles.length);
+    }
+    return fail("release-visible changes require a .changeset/*.md entry (`wp run changeset`) " +
+        "or a `Changeset-exempt: <reason>` commit trailer", changedFiles.length);
+}
+function pass(checked) {
+    return { ok: true, title: TITLE, checked, violations: [] };
+}
+function passWithWarning(message, checked) {
+    return { ok: true, title: TITLE, checked, violations: [{ message }] };
+}
+function fail(message, checked) {
+    return { ok: false, title: TITLE, checked, violations: [{ message }] };
+}
+function resolveChangedFiles(cwd, baseRef) {
+    const result = getBranchChangedFiles(cwd, baseRef);
+    if (result.degraded) {
+        return {
+            files: [],
+            error: `unable to resolve changed files vs ${baseRef} (${result.reason}); ` +
+                "refusing to skip changeset enforcement",
+        };
+    }
+    return { files: result.files };
+}
+function readCommitMessages(cwd, baseRef) {
+    const result = spawnSync("git", ["log", "--format=%B%x00", `${baseRef}...HEAD`], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        ...GIT_LOG_PROBE_OPTIONS,
+    });
+    if (result.status !== 0 || result.error)
+        return [];
+    return result.stdout
+        .split("\0")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}

package/dist/esm/audit/ci-guardrails-detection.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared content-absence detection for the `wp audit guardrails` CI wiring
+ * contract. Both the audit (`ci-guardrails-wiring.ts`) and the self-healing
+ * injector (`scaffold-base-kit.ts`'s `ensureGuardrailsCiStep`) must agree on
+ * what counts as a "live" test-run step to anchor guardrails after — keeping
+ * that detection in one place is what keeps the two from silently diverging.
+ *
+ * Prior to this module, the audit matched the test-run pattern against whole
+ * file content (including inside `#`-commented lines) while the injector's
+ * anchor scan already skipped comment lines. A workflow whose only test-run
+ * mention was commented out therefore tripped the audit red with no anchor
+ * for the injector to repair — an unrepairable-red state (tech-debt h-016).
+ */
+/** True when `content` invokes `wp audit guardrails` anywhere (including
+ * inside comments — see the pattern's doc comment above). */
+export declare function hasGuardrailsInvocation(content: string): boolean;
+/**
+ * Scans `content` line by line, skipping commented-out lines, tracking the
+ * most recent step-start line (`- ...`), and returning the index of the step
+ * that owns the first non-commented line matching the live test-run pattern.
+ * Returns -1 when no such line exists.
+ *
+ * This is the single source of truth for "is there a live test-run step to
+ * anchor a guardrails step before" — used by the audit (as a boolean) and by
+ * the injector (as an insertion index).
+ */
+export declare function findLiveTestRunAnchor(content: string): number;

package/dist/esm/audit/ci-guardrails-detection.js

@@ -0,0 +1,68 @@
+/**
+ * Shared content-absence detection for the `wp audit guardrails` CI wiring
+ * contract. Both the audit (`ci-guardrails-wiring.ts`) and the self-healing
+ * injector (`scaffold-base-kit.ts`'s `ensureGuardrailsCiStep`) must agree on
+ * what counts as a "live" test-run step to anchor guardrails after — keeping
+ * that detection in one place is what keeps the two from silently diverging.
+ *
+ * Prior to this module, the audit matched the test-run pattern against whole
+ * file content (including inside `#`-commented lines) while the injector's
+ * anchor scan already skipped comment lines. A workflow whose only test-run
+ * mention was commented out therefore tripped the audit red with no anchor
+ * for the injector to repair — an unrepairable-red state (tech-debt h-016).
+ */
+/**
+ * The guardrails invocation, keyed on the command itself (not the `wp`
+ * prefix nor a marker comment) so `wp audit guardrails`,
+ * `./bin/wp audit guardrails`, and the `--affected`/`--full` variants all
+ * count as wired.
+ *
+ * NOTE: this intentionally matches inside comments too — it is a
+ * whole-content test, not line-scanned. A commented-out `wp audit
+ * guardrails` line therefore still counts as "wired" by both the audit and
+ * the injector. This is an inherent limitation of content-absence
+ * pattern-matching (neither side parses YAML as executable steps) rather
+ * than a bug unique to either detector — see tech-debt h-016. Do not "fix"
+ * this by line-scanning here without first solving real YAML-step parsing;
+ * a half-parsed heuristic would be worse than the documented limitation.
+ */
+const GUARDRAILS_INVOCATION_PATTERN = /\baudit guardrails\b/u;
+/**
+ * Lines that run the default test suite — the signal that a workflow is a
+ * quality-CI pipeline that owes a guardrails step. Comment lines are
+ * excluded: a commented-out test-run mention is not a live test run.
+ */
+const TEST_RUN_PATTERN = /(?:\bvp\s+run\s+test\b|\bpnpm\s+(?:run\s+)?test\b|\bnpm\s+(?:run\s+)?test\b|\bbun\s+(?:run\s+)?test\b|\bwp\s+test\b|\bvitest\s+run\b)/iu;
+function isCommentLine(line) {
+    return line.trim().startsWith("#");
+}
+/** True when `content` invokes `wp audit guardrails` anywhere (including
+ * inside comments — see the pattern's doc comment above). */
+export function hasGuardrailsInvocation(content) {
+    return GUARDRAILS_INVOCATION_PATTERN.test(content);
+}
+/**
+ * Scans `content` line by line, skipping commented-out lines, tracking the
+ * most recent step-start line (`- ...`), and returning the index of the step
+ * that owns the first non-commented line matching the live test-run pattern.
+ * Returns -1 when no such line exists.
+ *
+ * This is the single source of truth for "is there a live test-run step to
+ * anchor a guardrails step before" — used by the audit (as a boolean) and by
+ * the injector (as an insertion index).
+ */
+export function findLiveTestRunAnchor(content) {
+    const lines = content.split("\n");
+    let lastStepStart = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        // Safe: index is bounded by the loop condition against lines.length.
+        const line = lines[index];
+        if (isCommentLine(line))
+            continue;
+        if (/^\s*-\s/u.test(line))
+            lastStepStart = index;
+        if (TEST_RUN_PATTERN.test(line))
+            return lastStepStart;
+    }
+    return -1;
+}

package/dist/esm/audit/ci-guardrails-wiring.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Guardrail: keep `wp audit guardrails` wired into a repo's own CI.
+ *
+ * `wp audit guardrails` is the delivery vehicle for every guardrail that ships
+ * inside the suite (e.g. `typescript-version` from #810). A consumer inherits a
+ * new guardrail automatically on their next agent-kit bump ONLY IF their CI
+ * still invokes `wp audit guardrails`. If that step is deleted, the whole suite
+ * silently stops running in CI and new guardrails never reach the consumer.
+ *
+ * This audit is dogfood / defense-in-depth — NOT the delivery guarantee. It
+ * cannot run if the very invariant it checks is already broken (a CI with no
+ * guardrails step never executes this audit in CI). The actual self-healing
+ * guarantee is the managed inject-by-content-absence repair in
+ * `scaffold-base-kit.ts` (`ensureGuardrailsCiStep`), which re-inserts the step
+ * on every `wp setup`. This audit's value is LOCAL: it is registered as
+ * affected-safe + MCP-visible, so `wp audit guardrails --affected` (pre-commit /
+ * IDE) catches the drift on the developer's machine even when CI has drifted.
+ *
+ * Modeled on the self-CI checks in `ci-test-perf.ts`.
+ */
+import type { RepoAuditResult } from "./repo-guardrails.js";
+export declare function auditCiGuardrailsWiring(rootDirectory?: string): RepoAuditResult;

package/dist/esm/audit/ci-guardrails-wiring.js

@@ -0,0 +1,80 @@
+/**
+ * Guardrail: keep `wp audit guardrails` wired into a repo's own CI.
+ *
+ * `wp audit guardrails` is the delivery vehicle for every guardrail that ships
+ * inside the suite (e.g. `typescript-version` from #810). A consumer inherits a
+ * new guardrail automatically on their next agent-kit bump ONLY IF their CI
+ * still invokes `wp audit guardrails`. If that step is deleted, the whole suite
+ * silently stops running in CI and new guardrails never reach the consumer.
+ *
+ * This audit is dogfood / defense-in-depth — NOT the delivery guarantee. It
+ * cannot run if the very invariant it checks is already broken (a CI with no
+ * guardrails step never executes this audit in CI). The actual self-healing
+ * guarantee is the managed inject-by-content-absence repair in
+ * `scaffold-base-kit.ts` (`ensureGuardrailsCiStep`), which re-inserts the step
+ * on every `wp setup`. This audit's value is LOCAL: it is registered as
+ * affected-safe + MCP-visible, so `wp audit guardrails --affected` (pre-commit /
+ * IDE) catches the drift on the developer's machine even when CI has drifted.
+ *
+ * Modeled on the self-CI checks in `ci-test-perf.ts`.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { findLiveTestRunAnchor, hasGuardrailsInvocation } from "./ci-guardrails-detection.js";
+const WORKFLOW_DIR = ".github/workflows";
+const WORKFLOW_FILE_PATTERN = /\.(ya?ml)$/iu;
+function walkWorkflowFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const files = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkWorkflowFiles(fullPath));
+            continue;
+        }
+        if (entry.isFile() && WORKFLOW_FILE_PATTERN.test(entry.name)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+export function auditCiGuardrailsWiring(rootDirectory = process.cwd()) {
+    const workflowsRoot = join(rootDirectory, WORKFLOW_DIR);
+    const files = walkWorkflowFiles(workflowsRoot);
+    const testWorkflows = [];
+    let anyWorkflowWiresGuardrails = false;
+    for (const file of files) {
+        const content = readFileSync(file, "utf8");
+        if (hasGuardrailsInvocation(content))
+            anyWorkflowWiresGuardrails = true;
+        if (findLiveTestRunAnchor(content) !== -1) {
+            testWorkflows.push(relative(rootDirectory, file).replace(/\\/gu, "/"));
+        }
+    }
+    // No quality-CI pipeline (no workflow runs the default test suite) → nothing
+    // to enforce; a repo without agent-kit CI is not "drifted".
+    const violations = [];
+    if (testWorkflows.length > 0 && !anyWorkflowWiresGuardrails) {
+        for (const workflow of testWorkflows) {
+            violations.push({
+                file: workflow,
+                severity: "error",
+                ruleId: "ci-guardrails-wiring",
+                message: `${workflow} runs the test suite but no workflow invokes \`wp audit guardrails\`. ` +
+                    `Guardrails (e.g. typescript-version) reach this repo only while CI runs ` +
+                    `\`wp audit guardrails\`. Re-run \`wp setup\` to restore the managed CI step.`,
+            });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: "CI guardrails wiring",
+        checked: files.length,
+        sources: files.map((file) => ({
+            path: relative(rootDirectory, file).replace(/\\/gu, "/"),
+            kind: "workflow",
+        })),
+        violations,
+    };
+}