@webpresso/agent-kit 3.2.0 → 3.3.0

package/bin/_run.js

@@ -382,10 +382,13 @@ function runtimeSourceRequiresSourceLaunch(sourceRootDir, builtRootDir) {
   return false;
 }
 
-function wpSourceRequiresSourceLaunch(repoRoot) {
+export function wpSourceRequiresSourceLaunch(repoRoot) {
   const sourceRoots = [
     ["src", "cli"],
     ["src", "tool-runtime"],
+    ["src", "mcp"],
+    ["src", "blueprint"],
+    ["src", "audit"],
   ];
 
   return sourceRoots.some((segments) =>

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.js

@@ -20,19 +20,9 @@
  */
 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;
-/** 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. */
-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. Mirrors the notion of a
- * test-running workflow used by `ci-test-perf.ts`; kept local so the two audits
- * stay independent.
- */
-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 walkWorkflowFiles(dir) {
     if (!existsSync(dir))
         return [];
@@ -56,9 +46,9 @@ export function auditCiGuardrailsWiring(rootDirectory = process.cwd()) {
     let anyWorkflowWiresGuardrails = false;
     for (const file of files) {
         const content = readFileSync(file, "utf8");
-        if (GUARDRAILS_INVOCATION_PATTERN.test(content))
+        if (hasGuardrailsInvocation(content))
             anyWorkflowWiresGuardrails = true;
-        if (TEST_RUN_PATTERN.test(content)) {
+        if (findLiveTestRunAnchor(content) !== -1) {
             testWorkflows.push(relative(rootDirectory, file).replace(/\\/gu, "/"));
         }
     }

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", "ci-guardrails-wiring", "test-scan-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "host-substitution-risk", "legacy-workflow-identity", "rules", "skills", "typescript-version"];
+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", "ci-guardrails-wiring", "test-scan-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "host-substitution-risk", "legacy-workflow-identity", "rules", "skills", "typescript-version", "changeset-required"];
 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-guardrails-wiring" | "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" | "host-substitution-risk" | "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" | "typescript-version" | "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", "host-substitution-risk", "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", "typescript-version", "ci-guardrails-wiring", "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", "ci-guardrails-wiring"];
+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" | "changeset-required" | "ci-guardrails-wiring" | "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" | "host-substitution-risk" | "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" | "typescript-version" | "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", "host-substitution-risk", "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", "typescript-version", "ci-guardrails-wiring", "sast", "changeset-required"];
+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", "ci-guardrails-wiring", "changeset-required"];
 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

@@ -18,6 +18,7 @@ const affectedSafeKinds = [
     "no-math-random",
     "test-scan-perf",
     "ci-guardrails-wiring",
+    "changeset-required",
 ];
 const mcpKindIds = [
     "test-smells",
@@ -65,6 +66,7 @@ const mcpKindIds = [
     "typescript-version",
     "ci-guardrails-wiring",
     "sast",
+    "changeset-required",
 ];
 const affectedSafe = new Set(affectedSafeKinds);
 const mcpKinds = new Set(mcpKindIds);
@@ -148,6 +150,7 @@ const repoKinds = [
     "rules",
     "skills",
     "typescript-version",
+    "changeset-required",
 ];
 function descriptor(id, kindClass) {
     return {
@@ -158,7 +161,9 @@ function descriptor(id, kindClass) {
         gateClass: signalKinds.has(id) ? "signal" : "blocking",
         scopeSafety: affectedSafe.has(id) ? "affected-safe" : "full-scan-only",
         summaryLabel: id === "sast" ? "SAST" : id,
-        ...(["sast", "host-substitution-risk"].includes(id) ? { includedInGuardrails: false } : {}),
+        ...(["sast", "host-substitution-risk", "changeset-required"].includes(id)
+            ? { includedInGuardrails: false }
+            : {}),
         ...(["blueprint-readme-drift", "docs-frontmatter"].includes(id) ? { fixable: true } : {}),
     };
 }

package/dist/esm/blueprint/core/parser.js

@@ -6,6 +6,7 @@
  */
 import matter from "gray-matter";
 import { planFrontmatterSchema, taskStatusSchema } from "#core/schema";
+import { buildTaskHeadingRegex } from "#markdown/task-heading";
 function parseWithSchema(markdown, schema) {
     const { data: rawData, content } = matter(markdown);
     const data = schema.parse(rawData);
@@ -75,7 +76,7 @@ export function serializeBlueprint(blueprint) {
     }
     const { tasks: _tasks, task_statuses: _task_statuses, ...cleanedData } = data;
     const serialized = quoteGeneratedProgressScalar(matter.stringify(content, cleanedData), blueprint.progress);
-    return preserveOriginalFrontmatterScalars(serialized, blueprint.raw);
+    return preserveOriginalFrontmatterMultiline(preserveOriginalFrontmatterScalars(serialized, blueprint.raw), blueprint.raw);
 }
 // Frontmatter keys serializeBlueprint intentionally rewrites; every other
 // scalar must survive a write byte-for-byte.
@@ -99,8 +100,8 @@ function quoteGeneratedProgressScalar(serialized, progress) {
 // re-quote on a write silently invalidates a recorded review approval. Restore
 // the ORIGINAL single-line scalar verbatim for every field this serializer does
 // not own, so a status/progress write never disturbs `title`/`owner`/`created`
-// etc. Multi-line and array fields (no inline value) are left to js-yaml, which
-// dumps them deterministically. Generalizes the earlier progress-only patch.
+// etc. Multi-line/array fields are restored separately by
+// preserveOriginalFrontmatterMultiline. Generalizes the earlier progress-only patch.
 function preserveOriginalFrontmatterScalars(serialized, originalRaw) {
     const originalFrontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(originalRaw)?.[1] ?? "";
     const originalScalars = new Map();
@@ -124,6 +125,59 @@ function preserveOriginalFrontmatterScalars(serialized, originalRaw) {
         .join("\n");
     return `${serialized.slice(0, block.index)}${block[1]}${rebuilt}${block[3]}${serialized.slice(block.index + block[0].length)}`;
 }
+// Same residual as scalars, for multi-line blocks (YAML arrays/maps under a
+// key with no inline value). `matter.stringify` re-dumps arrays and drops
+// item quotes (`- "review"` -> `- review`). MCP put and the CLI disagree on
+// that quoting; restore the ORIGINAL multi-line block for every non-owned key.
+// Allow optional CR on the key line so CRLF checkouts still match.
+const FRONTMATTER_MULTILINE_KEY = /^([A-Za-z0-9_]+):[ \t]*\r?$/;
+function preserveOriginalFrontmatterMultiline(serialized, originalRaw) {
+    const originalFrontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(originalRaw)?.[1] ?? "";
+    const originalBlocks = new Map();
+    const lines = originalFrontmatter.split("\n");
+    for (let index = 0; index < lines.length;) {
+        const match = FRONTMATTER_MULTILINE_KEY.exec(lines[index]);
+        if (!match) {
+            index += 1;
+            continue;
+        }
+        const key = match[1];
+        if (SERIALIZE_OWNED_FRONTMATTER_KEYS.has(key)) {
+            index += 1;
+            continue;
+        }
+        // Strip a trailing CR so joined blocks stay LF-normalized like the rest of the pipeline.
+        const blockLines = [lines[index].replace(/\r$/, "")];
+        index += 1;
+        while (index < lines.length && /^[ \t]/.test(lines[index])) {
+            blockLines.push(lines[index].replace(/\r$/, ""));
+            index += 1;
+        }
+        if (blockLines.length > 1) {
+            originalBlocks.set(key, blockLines.join("\n"));
+        }
+    }
+    if (originalBlocks.size === 0)
+        return serialized;
+    const wrapper = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(serialized);
+    if (!wrapper)
+        return serialized;
+    let body = wrapper[2];
+    for (const [key, originalBlock] of originalBlocks) {
+        // Match the serialized multi-line block. A trailing newline is optional when
+        // the block is the last key in the frontmatter body (wrapper[2] does not
+        // include the newline before `---`).
+        const pattern = new RegExp(String.raw `^${key}:[ \t]*\n(?:[ \t][^\n]*\n?)*`, "mu");
+        if (!pattern.test(body))
+            continue;
+        // Replacer function: avoid `$` re-interpretation of originalBlock contents,
+        // and only re-append a trailing newline when the match consumed one — otherwise
+        // a last-key `tags:` block gains a blank line before `---` and the plan digest
+        // flips on the first lifecycle write after MCP put (B1).
+        body = body.replace(pattern, (matched) => matched.endsWith("\n") ? `${originalBlock}\n` : originalBlock);
+    }
+    return `${serialized.slice(0, wrapper.index)}${wrapper[1]}${body}${wrapper[3]}${serialized.slice(wrapper.index + wrapper[0].length)}`;
+}
 function extractCheckboxStatus(section) {
     const checkboxRegex = /^- \[([ x])\]/gm;
     const matches = Array.from(section.matchAll(checkboxRegex));
@@ -178,7 +232,10 @@ function validateTaskFormat(content) {
     }
 }
 function extractTasks(content) {
-    const taskRegex = /^####\s+(?:\[[^\]]+\]\s+)?Task\s+(\d+(?:\.\d+)+):\s*(.+)$/gm;
+    // Built from #markdown/task-heading's shared pattern (also consumed by
+    // #core/schema's taskIdSchema) so the reader and the MCP put-task writer
+    // cannot drift apart on what counts as a valid task ID.
+    const taskRegex = buildTaskHeadingRegex();
     const matches = Array.from(content.matchAll(taskRegex));
     validateTaskFormat(content);
     return matches.map((match, index) => {

package/dist/esm/blueprint/core/schema.d.ts

@@ -77,6 +77,7 @@ export declare const crossRepoDependencySchema: z.ZodObject<{
         planned: "planned";
     }>>;
 }, z.core.$strip>;
+export declare const taskIdSchema: z.ZodString;
 /**
  * Plan frontmatter schema.
  *

package/dist/esm/blueprint/core/schema.js

@@ -11,6 +11,7 @@ import { z } from "zod";
  */
 import { executionBackendSchema } from "#types/execution-backend.js";
 export { executionBackendSchema } from "#types/execution-backend.js";
+import { TASK_ID_PATTERN as TASK_HEADING_TASK_ID_PATTERN } from "#markdown/task-heading";
 /**
  * Valid plan status values.
  * Maps to plan lifecycle: draft/planned/parked → in-progress → completed/archived.
@@ -58,6 +59,31 @@ export const crossRepoDependencySchema = z.object({
     slug: z.string().min(1),
     require_status: planStatusSchema.optional(),
 });
+/**
+ * Task-ID validator for MCP writer boundaries (e.g. `wp_blueprint_put`).
+ *
+ * Built from `#markdown/task-heading`'s `TASK_ID_PATTERN` — the existing
+ * single source of truth for the numeric-dotted task-ID shape (e.g. "1.1",
+ * "2.3.1") already consumed by `#core/parser`'s `extractTasks()` (via
+ * `buildTaskHeadingRegex()`) and by `verification.ts` / `markdown/helpers.ts`.
+ * Validating writer-supplied IDs against the same pattern the reader uses
+ * means the writer (MCP `put`) and the reader (parser) cannot drift apart —
+ * a non-numeric-dotted ID like "task-1" is rejected before it ever reaches
+ * markdown, instead of being silently unparseable afterward.
+ */
+const TASK_ID_ANCHORED_PATTERN = new RegExp(`^${TASK_HEADING_TASK_ID_PATTERN}$`);
+export const taskIdSchema = z
+    .string()
+    .min(1)
+    .superRefine((value, ctx) => {
+    if (!TASK_ID_ANCHORED_PATTERN.test(value)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Task IDs must be numeric dotted (e.g. "1.1", "2.3.1") — the blueprint parser only ` +
+                `recognizes "#### Task <numeric-dotted-id>:" headers. Use "1.1", got "${value}".`,
+        });
+    }
+});
 /**
  * Plan frontmatter schema.
  *

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

@@ -12,7 +12,8 @@ import { scanBlueprintDirectory } from "#service/scanner";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { parseBlueprintDocumentRelativePath } from "#utils/document-paths.js";
 import { relativeBlueprintSlug } from "#lifecycle/local.js";
-import { collectV2ReviewProvenance, collectTrackedReviewProvenance, normalizeTrackedReviewApprovals, } from "#lifecycle/review-provenance.js";
+import { collectV2ReviewProvenance, collectTrackedReviewProvenance, normalizeTrackedReviewApprovals, stableSlugForBlueprintFile, } from "#lifecycle/review-provenance.js";
+import { isBlueprintExemptFromRollout, ROLLOUT_DATE } from "#lifecycle/rollout-anchor.js";
 import { MAINTAINER_OVERRIDE_REVIEWER } from "#review/events.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 function isBlueprintOverview(file) {
@@ -51,14 +52,25 @@ function readLifecycleAuditFrontmatter(raw) {
  * blueprints that predate those changed-state gates.
  */
 const APPROVAL_GATED_STATUSES = new Set(["planned"]);
-const COMPLETED_APPROVAL_GATE_ROLLOUT_DATE = "2026-07-12";
-function predatesCompletedApprovalGate(created) {
-    const date = created instanceof Date
-        ? created.toISOString().slice(0, 10)
-        : typeof created === "string" && /^\d{4}-\d{2}-\d{2}$/u.test(created)
-            ? created
-            : null;
-    return date !== null && date < COMPLETED_APPROVAL_GATE_ROLLOUT_DATE;
+/**
+ * True when this blueprint predates the completed-approval gate and is exempt.
+ *
+ * Inside this repository the rollout anchor commit decides and the
+ * author-supplied `created` is ignored, which closes a real bypass: `created`
+ * is written by the same author the gate constrains, so an old date used to
+ * disable the gate outright -- on the CI audit path and on the unconditional
+ * `assertCompletedApprovalGate` write path, letting a blueprint reach
+ * `completed` with no approval at all. Outside this repository the anchor
+ * cannot answer the question and the legacy date compare still applies. See
+ * `#lifecycle/rollout-anchor.js` for the full resolution order.
+ */
+function predatesCompletedApprovalGate(file, created) {
+    return isBlueprintExemptFromRollout({
+        repoRoot: findGitRoot(file),
+        slug: stableSlugForBlueprintFile(file),
+        created,
+        rolloutDate: ROLLOUT_DATE,
+    });
 }
 /**
  * Promotion gate: a blueprint past `draft` must carry either one provenance-backed
@@ -144,7 +156,7 @@ export function validateApprovalGate(file, frontmatter, options = {}) {
     const status = typeof frontmatter.status === "string" ? frontmatter.status : "";
     if (status === "completed" &&
         options.completedApprovalGate === true &&
-        predatesCompletedApprovalGate(frontmatter.created)) {
+        predatesCompletedApprovalGate(file, frontmatter.created)) {
         return [];
     }
     const gateApplies = APPROVAL_GATED_STATUSES.has(status) ||

package/dist/esm/blueprint/lifecycle/review-provenance.d.ts

@@ -36,6 +36,12 @@ export interface TrackedReviewProvenanceOptions {
     readonly targetHash?: string;
 }
 export declare function normalizeTrackedReviewApprovals(approvals: unknown): TrackedReviewApproval[];
+/**
+ * Slug for a blueprint file, invariant across lifecycle moves
+ * (`draft/ → planned/ → completed/`) and across both the folder
+ * (`<slug>/_overview.md`) and legacy flat (`<slug>.md`) shapes.
+ */
+export declare function stableSlugForBlueprintFile(file: string): string;
 /**
  * Read `_overview.md` for a blueprint at `ref`. Prefer the working-tree path;
  * if missing (lifecycle move draft→planned before the promote commit), resolve