@webpresso/agent-kit 3.3.5 → 3.3.6

package/dist/esm/blueprint/verification.d.ts

@@ -110,6 +110,17 @@ export declare function readTaskVerification(markdown: string, taskId: string):
  */
 export declare function assertTaskHasCanonicalPassingEvidence(markdown: string, taskId: string): readonly Evidence[];
 /**
- * Assert that each supplied task id has task-local canonical passing evidence.
+ * Collect a failure message for every supplied task id that is missing
+ * task-local canonical passing evidence, instead of stopping at the first
+ * one. Callers that need to report every blocking condition in a single
+ * response (e.g. `wp_blueprint_finalize`) use this directly; callers that
+ * only need a single throw use {@link assertAllTasksHaveCanonicalPassingEvidence}.
+ */
+export declare function collectMissingCanonicalPassingEvidence(markdown: string, taskIds: readonly string[]): string[];
+/**
+ * Assert that each supplied task id has task-local canonical passing
+ * evidence. Throws once with every failing task's message joined, rather
+ * than stopping at the first failure — a caller fixing one issue at a time
+ * would otherwise need one failed round-trip per missing-evidence task.
  */
 export declare function assertAllTasksHaveCanonicalPassingEvidence(markdown: string, taskIds: readonly string[]): void;

package/dist/esm/blueprint/verification.js

@@ -173,11 +173,34 @@ export function assertTaskHasCanonicalPassingEvidence(markdown, taskId) {
     return evidence;
 }
 /**
- * Assert that each supplied task id has task-local canonical passing evidence.
+ * Collect a failure message for every supplied task id that is missing
+ * task-local canonical passing evidence, instead of stopping at the first
+ * one. Callers that need to report every blocking condition in a single
+ * response (e.g. `wp_blueprint_finalize`) use this directly; callers that
+ * only need a single throw use {@link assertAllTasksHaveCanonicalPassingEvidence}.
  */
-export function assertAllTasksHaveCanonicalPassingEvidence(markdown, taskIds) {
+export function collectMissingCanonicalPassingEvidence(markdown, taskIds) {
+    const failures = [];
     for (const taskId of taskIds) {
-        assertTaskHasCanonicalPassingEvidence(markdown, taskId);
+        try {
+            assertTaskHasCanonicalPassingEvidence(markdown, taskId);
+        }
+        catch (error) {
+            failures.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return failures;
+}
+/**
+ * Assert that each supplied task id has task-local canonical passing
+ * evidence. Throws once with every failing task's message joined, rather
+ * than stopping at the first failure — a caller fixing one issue at a time
+ * would otherwise need one failed round-trip per missing-evidence task.
+ */
+export function assertAllTasksHaveCanonicalPassingEvidence(markdown, taskIds) {
+    const failures = collectMissingCanonicalPassingEvidence(markdown, taskIds);
+    if (failures.length > 0) {
+        throw new Error(failures.join("; "));
     }
 }
 // ---------------------------------------------------------------------------

package/dist/esm/cli/commands/init/scaffold-base-kit.js

@@ -209,7 +209,11 @@ export function ensureGuardrailsCiStep(content, repoAlreadyWired = false) {
     // Safe: anchorStepStart is an index returned by findLiveTestRunAnchor over
     // this same content.split("\n"), so it is always within lines' bounds here.
     const indent = lines[anchorStepStart].match(/^(\s*)/u)?.[1] ?? "";
-    lines.splice(anchorStepStart, 0, `${indent}- name: Run wp audit guardrails`, `${indent}  run: wp audit guardrails`);
+    // continue-on-error: true matches framework quality.yml and keeps
+    // ci-guardrails-wiring green without hard-failing thin consumers on
+    // agent-kit dogfood audits (command-surface, etc.) or known suite debt.
+    // Explicit hard-fail audits remain separate workflow steps.
+    lines.splice(anchorStepStart, 0, `${indent}- name: Run wp audit guardrails`, `${indent}  continue-on-error: true`, `${indent}  run: wp audit guardrails`);
     return lines.join("\n");
 }
 function migrateConsumerWorkflows(repoRoot, actionRef, version, options) {

package/dist/esm/cli/commands/mcp.js

@@ -6,6 +6,8 @@ export const MCP_COMMAND_HELP = [
     "by a Claude Code plugin manifest entry (`mcpServers.webpresso`) or any MCP",
     "client. Tools are auto-discovered from `dist/esm/mcp/tools/*.js`.",
     "",
+    "No subcommands are supported; use `wp review gate` for review workflows.",
+    "",
     "Examples:",
     "  wp mcp",
 ].join("\n");

package/dist/esm/cli/commands/sync.js

@@ -142,6 +142,14 @@ export function registerSyncCommand(cli) {
             }
             throw error;
         }
+        // Operator-owned paths agent-kit refused to replace. A warning, never
+        // drift: treating it as a mismatch would red `wp sync --check` on every
+        // run for someone who legitimately customized a subagent.
+        for (const entry of result.preserved) {
+            console.warn(`wp sync: preserved ${entry.targetPath} — it is not an agent-kit projection, ` +
+                `so the catalog '${entry.slug}' agent was not written there. ` +
+                `Rename yours, or move it to agent-agents/ to have it managed.`);
+        }
         const retiredMcp = cleanupRetiredMcpFanouts(repoRoot, { check });
         for (const targetPath of retiredMcp.preserved) {
             console.warn(`wp sync: preserved divergent retired MCP target ${targetPath}; remove it manually if it is no longer needed.`);

package/dist/esm/hooks/doctor.js

@@ -28,7 +28,7 @@ import { findAgentKitPackageRoot, resolveAgentKitPackageRoot, } from "#cli/comma
 import { readInstalledHooksMap } from "#hooks/shared/installed-hooks.js";
 import { auditCodexConfigPaths, checkCodexConfigPathIntegrity } from "#hooks/codex-config-paths.js";
 import { findInstalledCodexPluginMcpManifests, pruneOwnedMcpServerBlock, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
-import { isAgentKitOwnedWpCommand, WEBPRESSO_MCP_SERVER_NAME, } from "#cli/commands/init/mcp-spec.js";
+import { resolveExecutableOnPath, WEBPRESSO_MCP_SPEC, isAgentKitOwnedWpCommand, WEBPRESSO_MCP_SERVER_NAME, } from "#cli/commands/init/mcp-spec.js";
 import { parseProjectMcpServers, scanCodexConfigDrift } from "#hooks/host-config-contract.js";
 import { defaultCodexConfigFilePath } from "#cli/commands/init/scaffolders/agent-hooks/codex-trust-sync.js";
 import { expectedRootWpBinRelativePath, formatRootLauncherContractFailure, rootContractMode, validateRootLauncherContract, } from "#launcher/root-contract.js";
@@ -1201,31 +1201,135 @@ function runCommand(command, args, cwd = process.cwd(), timeoutMs = DEFAULT_HOOK
         });
     });
 }
-async function checkCodexHost() {
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function unsupportedCodexJsonFlag(result) {
+    const text = `${result.stderr}\n${result.stdout}`;
+    return (/--json/u.test(text) && /(unexpected|unknown|unrecognized|invalid|found argument)/iu.test(text));
+}
+function classifyCodexMcpListJson(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        return {
+            kind: "malformed",
+            reason: error instanceof Error ? error.message : "invalid JSON",
+        };
+    }
+    if (!Array.isArray(parsed)) {
+        return { kind: "malformed", reason: "expected a top-level array" };
+    }
+    const webpressoEntry = parsed
+        .map((entry) => asRecord(entry))
+        .find((entry) => entry?.name === WEBPRESSO_MCP_SERVER_NAME);
+    if (!webpressoEntry)
+        return { kind: "missing" };
+    if (webpressoEntry.enabled !== true) {
+        const reason = typeof webpressoEntry.disabled_reason === "string" &&
+            webpressoEntry.disabled_reason.length > 0
+            ? webpressoEntry.disabled_reason
+            : "enabled=false";
+        return { kind: "disabled", reason };
+    }
+    const transport = asRecord(webpressoEntry.transport);
+    if (!transport || transport.type !== "stdio" || typeof transport.command !== "string") {
+        return { kind: "nonstdio" };
+    }
+    if (transport.command === "wp" && stringArrayEquals(transport.args, WEBPRESSO_MCP_SPEC.args)) {
+        return { kind: "canonical", command: "wp", args: ["mcp"] };
+    }
+    const args = Array.isArray(transport.args)
+        ? transport.args.map((arg) => String(arg)).join(" ")
+        : "";
+    return { kind: "noncanonical", command: `${transport.command}${args ? ` ${args}` : ""}` };
+}
+function classifyCodexMcpLaunchability(stdout, env) {
+    const classification = classifyCodexMcpListJson(stdout);
+    switch (classification.kind) {
+        case "canonical": {
+            const resolved = resolveExecutableOnPath(classification.command, env);
+            if (resolved) {
+                return null;
+            }
+            const pathValue = env.PATH && env.PATH.length > 0 ? env.PATH : "(empty)";
+            return {
+                kind: "failure",
+                detail: `@webpresso/codex-plugin/.mcp.json configures webpresso MCP as \`wp mcp\`, but \`wp\` is not resolvable on this doctor's PATH (${pathValue}); fix is not automatic: restore global \`wp\` in the Codex launch environment or run \`wp install codex\` after PATH is fixed`,
+            };
+        }
+        case "disabled":
+            return {
+                kind: "failure",
+                detail: `webpresso MCP entry is configured but disabled by \`codex mcp list --json\` (${classification.reason}); fix is not automatic: inspect Codex MCP configuration and run \`wp install codex\` if the bundled plugin is stale`,
+            };
+        case "malformed":
+            return {
+                kind: "failure",
+                detail: `codex mcp list --json returned malformed output (${classification.reason}); cannot verify webpresso MCP launchability; fix is not automatic: run \`wp install codex\` if the Codex CLI is stale`,
+            };
+        case "missing":
+            return {
+                kind: "failure",
+                detail: "missing MCP entry (webpresso=false); run `wp install codex` to install the bundled plugin",
+            };
+        case "nonstdio":
+            return {
+                kind: "advisory",
+                detail: "webpresso MCP configured with a non-stdio transport; launchability was not verified for user-owned transports",
+            };
+        case "noncanonical":
+            return {
+                kind: "advisory",
+                detail: `webpresso MCP configured with non-canonical command \`${classification.command}\`; launchability was not verified for user-owned commands`,
+            };
+    }
+}
+async function checkCodexHost(env = process.env) {
     const available = await runCommand("codex", ["--version"]);
     if (!available.ok) {
         return { name: "Codex host integration", ok: true, detail: "skipped (codex not on PATH)" };
     }
-    const result = await runCommand("codex", ["mcp", "list"]);
+    const result = await runCommand("codex", ["mcp", "list", "--json"]);
     if (!result.ok) {
+        if (unsupportedCodexJsonFlag(result)) {
+            return {
+                name: "Codex host integration",
+                ok: false,
+                detail: "codex mcp list --json is unsupported by the installed Codex CLI; fix is not automatic: run `wp install codex` to refresh the Codex integration",
+            };
+        }
         return {
             name: "Codex host integration",
             ok: false,
             detail: result.stderr.trim() || `exit ${result.code}`,
         };
     }
-    const hasAgentKit = result.stdout.includes("webpresso");
-    if (!hasAgentKit) {
+    const launchability = classifyCodexMcpLaunchability(result.stdout, env);
+    const findings = launchability?.kind === "failure" ? [launchability.detail] : [];
+    const advisories = launchability?.kind === "advisory" ? [launchability.detail] : [];
+    const legacy = classifyLegacyCodexWebpressoChannel();
+    if (legacy)
+        findings.push(legacy);
+    if (findings.length > 0) {
         return {
             name: "Codex host integration",
             ok: false,
-            detail: `missing MCP entry (webpresso=${hasAgentKit})`,
+            detail: [...findings, ...advisories].join("; "),
         };
     }
-    const legacy = classifyLegacyCodexWebpressoChannel();
-    if (legacy)
-        return { name: "Codex host integration", ok: false, detail: legacy };
-    return { name: "Codex host integration", ok: true, detail: "webpresso MCP visible" };
+    if (advisories.length > 0) {
+        return { name: "Codex host integration", ok: true, detail: advisories.join("; ") };
+    }
+    return {
+        name: "Codex host integration",
+        ok: true,
+        detail: "webpresso MCP visible (wp mcp launch command resolves on PATH)",
+    };
 }
 /**
  * Codex must receive `webpresso` over exactly one channel — the bundled Codex

package/dist/esm/mcp/blueprint/_shared/lifecycle.d.ts

@@ -1,5 +1,18 @@
 export declare const ALL_BLUEPRINT_STATES: readonly ["draft", "planned", "in-progress", "parked", "archived", "completed"];
 export declare const NON_COMPLETED_BLUEPRINT_STATES: readonly ["draft", "planned", "in-progress", "parked", "archived"];
+/**
+ * Collect every reason "${slug}" cannot move to `completed`, without
+ * stopping at the first one: zero-task / unfinished-task blockers, missing
+ * task-local evidence per done task, `runValidate` document gaps, and the
+ * completed approval/digest gate. Callers that need to report every
+ * blocking condition in a single response (e.g. `wp_blueprint_finalize`)
+ * use this directly, before attempting any external side effect (platform
+ * sync) or local move — so a refusal never fires mid-move and a caller
+ * fixing issues one at a time never needs one failed round-trip per
+ * condition. {@link assertBlueprintCanComplete} throws the same combined
+ * message for callers that only need a single throw.
+ */
+export declare function collectBlueprintCompletionBlockers(overviewPath: string, slug: string): string[];
 export declare function assertBlueprintCanComplete(overviewPath: string, slug: string): void;
 export declare function applyLocalBlueprintTransition(input: {
     projectCwd: string;

package/dist/esm/mcp/blueprint/_shared/lifecycle.js

@@ -6,7 +6,7 @@ import { setBlueprintFrontmatterFields } from "#lifecycle/engine";
 import { assertCompletedApprovalGate, evaluateApprovalGate, formatApprovalGateRequirement, } from "#lifecycle/audit";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
-import { assertAllTasksHaveCanonicalPassingEvidence } from "#verification.js";
+import { collectMissingCanonicalPassingEvidence } from "#verification.js";
 import { writeFileAtomic } from "#shared-utils/write-json-file.js";
 import { applyPromotionTrustGate } from "#trust/promotion.js";
 import { reIngest } from "#mcp/blueprint/_shared/db";
@@ -34,18 +34,50 @@ function formatBlueprintProgress(totalTasks, doneTasks, blockedTasks) {
     const percent = totalTasks === 0 ? 0 : Math.round((doneTasks / totalTasks) * 100);
     return `${percent}% (${doneTasks}/${totalTasks} tasks done, ${blockedTasks} blocked, updated ${todayIsoDate()})`;
 }
-export function assertBlueprintCanComplete(overviewPath, slug) {
+/**
+ * Collect every reason "${slug}" cannot move to `completed`, without
+ * stopping at the first one: zero-task / unfinished-task blockers, missing
+ * task-local evidence per done task, `runValidate` document gaps, and the
+ * completed approval/digest gate. Callers that need to report every
+ * blocking condition in a single response (e.g. `wp_blueprint_finalize`)
+ * use this directly, before attempting any external side effect (platform
+ * sync) or local move — so a refusal never fires mid-move and a caller
+ * fixing issues one at a time never needs one failed round-trip per
+ * condition. {@link assertBlueprintCanComplete} throws the same combined
+ * message for callers that only need a single throw.
+ */
+export function collectBlueprintCompletionBlockers(overviewPath, slug) {
+    const blockers = [];
     const markdown = readFileSync(overviewPath, "utf8");
     const blueprint = parseBlueprint(markdown, slug);
     if (blueprint.tasks.length === 0) {
-        throw new Error(`Cannot complete "${slug}": zero-task blueprints cannot move to completed through the public lifecycle surface`);
+        blockers.push(`Cannot complete "${slug}": zero-task blueprints cannot move to completed through the public lifecycle surface`);
+    }
+    else {
+        const unfinished = blueprint.tasks.filter((task) => task.status !== "done" && task.status !== "dropped");
+        if (unfinished.length > 0) {
+            const list = unfinished.map((task) => `${task.id} (${task.status})`).join(", ");
+            blockers.push(`Cannot complete "${slug}": the following tasks are not done: ${list}`);
+        }
+        blockers.push(...collectMissingCanonicalPassingEvidence(markdown, blueprint.tasks.filter((task) => task.status !== "dropped").map((task) => task.id)));
+    }
+    const validated = runValidate(overviewPath);
+    if (!validated.valid) {
+        blockers.push(...validated.gaps.map((gap) => `Cannot complete "${slug}": ${gap}`));
+    }
+    try {
+        assertCompletedApprovalGate(overviewPath, markdown);
+    }
+    catch (error) {
+        blockers.push(`Cannot complete "${slug}": ${error instanceof Error ? error.message : String(error)}`);
     }
-    const unfinished = blueprint.tasks.filter((task) => task.status !== "done" && task.status !== "dropped");
-    if (unfinished.length > 0) {
-        const list = unfinished.map((task) => `${task.id} (${task.status})`).join(", ");
-        throw new Error(`Cannot complete "${slug}": the following tasks are not done: ${list}`);
+    return blockers;
+}
+export function assertBlueprintCanComplete(overviewPath, slug) {
+    const blockers = collectBlueprintCompletionBlockers(overviewPath, slug);
+    if (blockers.length > 0) {
+        throw new Error(blockers.join("; "));
     }
-    assertAllTasksHaveCanonicalPassingEvidence(markdown, blueprint.tasks.filter((task) => task.status !== "dropped").map((task) => task.id));
 }
 export async function applyLocalBlueprintTransition(input) {
     const { projectCwd, slug, to_state, found, trustedMarkdown: preflightTrustedMarkdown } = input;

package/dist/esm/mcp/blueprint/handlers/document-mutations.d.ts

@@ -1,5 +1,80 @@
+import { z } from "zod";
 import type { ProjectResolver } from "#project-resolver.js";
 import type { ToolHandlerResult } from "#mcp/auto-discover.js";
+declare const putDocumentSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"blueprint">>;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        archived: "archived";
+        completed: "completed";
+        draft: "draft";
+        "in-progress": "in-progress";
+        parked: "parked";
+        planned: "planned";
+    }>;
+    complexity: z.ZodEnum<{
+        L: "L";
+        M: "M";
+        S: "S";
+        XL: "XL";
+        XS: "XS";
+    }>;
+    owner: z.ZodString;
+    created: z.ZodString;
+    last_updated: z.ZodString;
+    progress: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    product_wedge_anchor: z.ZodObject<{
+        stage_outcome: z.ZodString;
+        consuming_surface: z.ZodString;
+        new_user_visible_capability: z.ZodString;
+    }, z.core.$strip>;
+    summary: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            blocked: "blocked";
+            done: "done";
+            dropped: "dropped";
+            "in-progress": "in-progress";
+            todo: "todo";
+        }>>;
+        wave: z.ZodOptional<z.ZodString>;
+        lane: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        acceptance: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    trust_dossier: z.ZodOptional<z.ZodObject<{
+        readiness: z.ZodObject<{
+            promotion_ready: z.ZodBoolean;
+            unresolved_count: z.ZodNumber;
+            verified_at: z.ZodString;
+            verified_head: z.ZodString;
+            trust_gate_version: z.ZodString;
+        }, z.core.$strip>;
+        material_claims: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            claim: z.ZodString;
+            evidence: z.ZodString;
+        }, z.core.$strip>>;
+        material_decisions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            decision: z.ZodString;
+            chosen_option: z.ZodString;
+            rejected_alternatives: z.ZodString;
+            rationale: z.ZodString;
+        }, z.core.$strip>>;
+        promotion_gates: z.ZodArray<z.ZodObject<{
+            gate: z.ZodString;
+            command: z.ZodString;
+            expected_outcome: z.ZodString;
+            last_result: z.ZodString;
+            defer: z.ZodOptional<z.ZodLiteral<"pre-implementation">>;
+        }, z.core.$strip>>;
+        residual_unknowns: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const putInputJsonSchema: {
     type: string;
     properties: {
@@ -233,6 +308,28 @@ export declare const putInputJsonSchema: {
     };
     required: string[];
 };
+/**
+ * Promotion-grade dossier completeness (promotion-ready: true,
+ * unresolved-count: 0, Residual Unknowns exactly `None.`, non-empty material
+ * claims/decisions/gates, passing gate results) is a PROMOTION-time
+ * requirement, not a draft-authoring one. `wp_blueprint_put` only ever writes
+ * `status: draft` documents (see the refusal in `handleBlueprintPut` above);
+ * gating every intermediate draft save on full promotion readiness forced
+ * authors to either fabricate readiness fields or keep genuinely-finished
+ * tasks marked `todo` to dodge the "checked box implies unreviewed
+ * completion" ambiguity scan -- inverting the draft -> planned lifecycle.
+ *
+ * `promotionCandidate` is therefore derived from the document's OWN target
+ * `status`, not hardcoded: a `draft` target skips promotion-grade dossier
+ * completeness entirely (an incomplete/in-progress dossier round-trips
+ * as-is), while any non-draft target keeps today's full strictness
+ * unchanged. Real promotion strictness is enforced separately and
+ * unconditionally at `wp_blueprint_transition`'s `crossesDraftApprovalBoundary`
+ * gate (`applyPromotionTrustGate` in `#trust/promotion.ts`), which still
+ * hardcodes `promotionCandidate: true` and is untouched by this function.
+ */
+export declare function validatePutTrustDossier(repoRoot: string, file: string, markdown: string, targetStatus: z.infer<typeof putDocumentSchema>["status"]): string | null;
 export declare function handleBlueprintPut(projectResolver: ProjectResolver, cwd: string, raw: unknown): Promise<ToolHandlerResult>;
 export declare function handleBlueprintTransition(projectResolver: ProjectResolver, cwd: string, raw: unknown): Promise<ToolHandlerResult>;
 export declare function handleBlueprintCreate(projectResolver: ProjectResolver, cwd: string, raw: unknown): Promise<ToolHandlerResult>;
+export {};

package/dist/esm/mcp/blueprint/handlers/document-mutations.js

@@ -427,13 +427,33 @@ function describeEvidenceLossRefusal(taskId, submittedStatus) {
         `that evidence. Keep task ${taskId} present with status "done" in the payload; put will carry ` +
         `the recorded evidence forward automatically.`);
 }
-function validatePutTrustDossier(repoRoot, file, markdown) {
+/**
+ * Promotion-grade dossier completeness (promotion-ready: true,
+ * unresolved-count: 0, Residual Unknowns exactly `None.`, non-empty material
+ * claims/decisions/gates, passing gate results) is a PROMOTION-time
+ * requirement, not a draft-authoring one. `wp_blueprint_put` only ever writes
+ * `status: draft` documents (see the refusal in `handleBlueprintPut` above);
+ * gating every intermediate draft save on full promotion readiness forced
+ * authors to either fabricate readiness fields or keep genuinely-finished
+ * tasks marked `todo` to dodge the "checked box implies unreviewed
+ * completion" ambiguity scan -- inverting the draft -> planned lifecycle.
+ *
+ * `promotionCandidate` is therefore derived from the document's OWN target
+ * `status`, not hardcoded: a `draft` target skips promotion-grade dossier
+ * completeness entirely (an incomplete/in-progress dossier round-trips
+ * as-is), while any non-draft target keeps today's full strictness
+ * unchanged. Real promotion strictness is enforced separately and
+ * unconditionally at `wp_blueprint_transition`'s `crossesDraftApprovalBoundary`
+ * gate (`applyPromotionTrustGate` in `#trust/promotion.ts`), which still
+ * hardcodes `promotionCandidate: true` and is untouched by this function.
+ */
+export function validatePutTrustDossier(repoRoot, file, markdown, targetStatus) {
     const validated = validateBlueprintTrust({
         repoRoot,
         file,
         status: "draft",
         markdown,
-        promotionCandidate: true,
+        promotionCandidate: targetStatus !== "draft",
         requirePassingGates: false,
         scanTaskAmbiguity: true,
     });
@@ -509,7 +529,7 @@ export async function handleBlueprintPut(projectResolver, cwd, raw) {
             markdown = preserved.markdown;
         }
         if (document.trust_dossier) {
-            const trustDossierFailure = validatePutTrustDossier(writeCwd, overviewPath, markdown);
+            const trustDossierFailure = validatePutTrustDossier(writeCwd, overviewPath, markdown, document.status);
             if (trustDossierFailure) {
                 return err("wp_blueprint_put validation error", trustDossierFailure);
             }

package/dist/esm/mcp/blueprint/handlers/finalize.js

@@ -7,7 +7,7 @@ import { ensureProjectionReady } from "#projection-ready.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { dbPath } from "#mcp/blueprint/_shared/db";
 import { err, finishPayload, jsonContent } from "#mcp/blueprint/_shared/errors";
-import { applyLocalBlueprintTransition, assertBlueprintCanComplete, NON_COMPLETED_BLUEPRINT_STATES, } from "#mcp/blueprint/_shared/lifecycle";
+import { applyLocalBlueprintTransition, collectBlueprintCompletionBlockers, NON_COMPLETED_BLUEPRINT_STATES, } from "#mcp/blueprint/_shared/lifecycle";
 import { toStr } from "#mcp/blueprint/_shared/payload";
 import { findBlueprintDir, resolveToolProject } from "#mcp/blueprint/_shared/project";
 import { resolveSyncAdapter, runPlatformMutationSync } from "#mcp/blueprint/_shared/sync";
@@ -53,8 +53,6 @@ export async function handleFinalize(projectResolver, cwd, raw) {
     finally {
         conn.close();
     }
-    if (openTasks.length > 0)
-        return err("wp_blueprint_finalize refused", `Blueprint "${slug}" has open tasks: ${openTasks.map((t) => `${t.task_id} (${t.status})`).join(", ")}`);
     const root = resolveBlueprintRoot(projectCwd);
     const found = findBlueprintDir(root, slug, NON_COMPLETED_BLUEPRINT_STATES);
     if (!found) {
@@ -69,11 +67,24 @@ export async function handleFinalize(projectResolver, cwd, raw) {
             });
         return err("wp_blueprint_finalize failed", `Blueprint "${slug}" not found`);
     }
-    try {
-        assertBlueprintCanComplete(found.path, slug);
+    // Gather EVERY blocking condition up front, from every check this handler
+    // (and applyLocalBlueprintTransition, invoked later) is capable of raising
+    // — open tasks per the DB projection, zero-task/unfinished-task/missing-
+    // evidence per the raw markdown, doc-validate gaps, and the completed
+    // approval/digest gate. Refusing once per condition costs one failed
+    // round-trip per fix; a single combined refusal costs one. This also
+    // fixes atomicity at the handler level: neither the platform-sync side
+    // effect below nor the local move in applyLocalBlueprintTransition is
+    // ever attempted while any blocker remains, so a failed finalize call
+    // can never partially move — or platform-sync without locally moving —
+    // the blueprint.
+    const blockers = [];
+    if (openTasks.length > 0) {
+        blockers.push(`Blueprint "${slug}" has open tasks: ${openTasks.map((t) => `${t.task_id} (${t.status})`).join(", ")}`);
     }
-    catch (error) {
-        return err("wp_blueprint_finalize refused", toStr(error));
+    blockers.push(...collectBlueprintCompletionBlockers(found.path, slug));
+    if (blockers.length > 0) {
+        return err("wp_blueprint_finalize refused", blockers.join("; "));
     }
     // Platform-first path: push event + pull fresh replica before local move.
     // Iron rule: resolveSyncAdapter() returns null when WP_BLUEPRINT_PLATFORM_DISABLED=1.

package/dist/esm/mcp/blueprint/registration.js

@@ -255,7 +255,7 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
             "next_action",
         ],
     }, (r) => handleBlueprintCreate(projectResolver, cwd, r), { title: "Blueprint Create", destructiveHint: false, openWorldHint: false });
-    registrar.registerTool("wp_blueprint_task_verify", "Mark a task done with an Evidence Contract. Requires at least one pass evidence item. Accepts optional request_id for idempotent retries, optional head_at_ingest from wp_blueprint_get/wp_blueprint_context to reject stale writes, and re-ingests DB on success. Returns { status, idempotent, next_action? }.", {
+    registrar.registerTool("wp_blueprint_task_verify", "Mark a task done with an Evidence Contract. Requires at least one pass evidence item. Accepts optional request_id for idempotent retries, optional head_at_ingest from wp_blueprint_get/wp_blueprint_context to reject stale writes, and re-ingests DB on success. Returns { status, idempotent, next_action? }. Each evidence item's required fields depend on its `kind`: 'test' requires `command` + `exit_code` (must be 0 when result='pass'); 'integration' additionally requires a non-empty `target_files`; 'audit' requires `audit_kind` + `passed:true` when result='pass'; 'manual' requires `actor`, `description`, the literal `allow_manual:true` (an explicit anti-shortcut opt-in), and a non-empty `log_excerpt` (<=4096 bytes) — it does NOT accept a `note` field.", {
         type: "object",
         properties: {
             project_id: { type: "string" },
@@ -271,7 +271,36 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
                     properties: {
                         kind: { type: "string", enum: ["test", "integration", "audit", "manual"] },
                         result: { type: "string", enum: ["pass", "fail"] },
-                        ts: { type: "string" },
+                        ts: { type: "string", description: "ISO 8601 date-time string" },
+                        agent: { type: "string" },
+                        command: {
+                            type: "string",
+                            description: "Required for kind='test'/'integration'",
+                        },
+                        exit_code: {
+                            type: "number",
+                            description: "Required for kind='test'/'integration'; must be 0 when result='pass'",
+                        },
+                        target_files: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Required non-empty array for kind='integration'",
+                        },
+                        audit_kind: { type: "string", description: "Required for kind='audit'" },
+                        passed: {
+                            type: "boolean",
+                            description: "Required for kind='audit'; must be true when result='pass'",
+                        },
+                        actor: { type: "string", description: "Required for kind='manual'" },
+                        description: { type: "string", description: "Required for kind='manual'" },
+                        allow_manual: {
+                            type: "boolean",
+                            description: "Required for kind='manual'; must be the literal boolean true (anti-shortcut opt-in)",
+                        },
+                        log_excerpt: {
+                            type: "string",
+                            description: "Required for kind='manual'; <=4096 bytes",
+                        },
                     },
                     required: ["kind", "result", "ts"],
                 },

package/dist/esm/symlinker/consumers.d.ts

@@ -78,6 +78,23 @@ export interface UnifiedConsumerConfig {
      * always project.
      */
     readonly host?: AgentHostName;
+    /**
+     * Who owns the target directory, and therefore what agent-kit may destroy in
+     * it. Defaults to `"exclusive"`, preserving the historical sweep behavior.
+     *
+     * - `"exclusive"` — agent-kit owns the directory. It is generated and
+     *   gitignored, has no hand-authoring workflow, and unexpected entries
+     *   matching the managed shape are stale projections, safe to remove.
+     * - `"shared"` — a host-native authoring surface co-owned with the user
+     *   (`.claude/agents` is Claude Code's own subagent authoring location).
+     *   agent-kit may destroy only paths it can prove it created; anything else
+     *   is preserved, because the surface is gitignored and loss is permanent.
+     *
+     * Declared rather than inferred on purpose: the stance used to be derived
+     * from `acceptsKind === "agent"` at each use site, which meant one code path
+     * had the guard and another silently did not.
+     */
+    readonly ownership?: "exclusive" | "shared";
     /**
      * Legacy flag retained for shape compatibility. Plugin hosts no longer
      * reactivate project-local skill projections under skip envs.

package/dist/esm/symlinker/consumers.js

@@ -74,7 +74,15 @@ export const DEFAULT_UNIFIED_CONSUMERS = [
     // Claude: canonical subagents are scaffolded to .claude/agents. Host-agnostic
     // (unconditional) because subagents were previously scaffolded unconditionally
     // by the now-retired standalone scaffoldSubagents scaffolder.
-    { id: "claude-agents", dir: ".claude/agents", acceptsKind: "agent", strategy: "symlink" },
+    {
+        id: "claude-agents",
+        dir: ".claude/agents",
+        acceptsKind: "agent",
+        strategy: "symlink",
+        // Claude Code's own subagent authoring location: the user may hand-author
+        // here, and agent-kit gitignores it, so a wrong deletion is unrecoverable.
+        ownership: "shared",
+    },
 ];
 /**
  * Projection surfaces retired by a newer agent-kit release.

package/dist/esm/symlinker/ownership.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Who may destroy a path under a consumer directory.
+ *
+ * This is the single owner of that question. It exists because the answer was
+ * previously implemented twice — conservatively in `pruneStale`, not at all in
+ * `applyTarget` — and the two drifted, which is how a consumer-authored file
+ * whose name collided with a catalog slug came to be deleted silently.
+ *
+ * The predicate is deliberately narrow: agent-kit may destroy a path only when
+ * it can PROVE it created that path, i.e. the path is a symlink resolving into
+ * a directory agent-kit projects from. A real file, a real directory, or a
+ * symlink pointing anywhere else is somebody else's and is never destroyed on a
+ * `shared` surface.
+ */
+export interface ManagedSourceDirsInput {
+    /** Catalog root passed to `runUnifiedSync` (may itself be a symlink alias). */
+    readonly catalogDir: string;
+    /** Consumer repo root, already realpath-resolved by the caller. */
+    readonly consumerRoot: string;
+}
+/**
+ * Directories agent-kit projects agent records from.
+ *
+ * Derived from CONFIGURATION, never from the planned record set, so the result
+ * is non-empty even when the catalog agents directory is empty or entirely
+ * absent. That matters: with a plans-derived set, a broken or partial install
+ * produces zero plans, an empty managed set, and a sweep that can no longer
+ * tell agent-kit's own relics from the operator's files.
+ *
+ * The catalog child is derived from `realpathSync(catalogDir)` rather than by
+ * realpathing the child itself. `loadContent` throws when `catalogDir` is
+ * missing, so the parent always resolves — whereas the child may not exist yet
+ * (or any more), and a non-existent child silently contributes only its
+ * unresolved alias form, which then fails to match a symlink recorded against
+ * the real path.
+ */
+export declare function resolveManagedSourceDirs(input: ManagedSourceDirsInput): ReadonlySet<string>;
+/**
+ * True when `targetPath` is a symlink agent-kit projected — the only shape it
+ * is allowed to destroy on a `shared` surface.
+ *
+ * The resolved target need not still exist: a dangling link left behind by a
+ * removed catalog record is agent-kit's own relic and must stay prunable.
+ * Containment is delegated to `isPathContained`, which canonicalizes both sides
+ * and rejects `..` escapes, so a sibling directory such as `<managed>-evil`
+ * cannot masquerade as managed.
+ */
+export declare function isAgentKitOwned(targetPath: string, managedSourceDirs: ReadonlySet<string>): boolean;

package/dist/esm/symlinker/ownership.js

@@ -0,0 +1,83 @@
+/**
+ * Who may destroy a path under a consumer directory.
+ *
+ * This is the single owner of that question. It exists because the answer was
+ * previously implemented twice — conservatively in `pruneStale`, not at all in
+ * `applyTarget` — and the two drifted, which is how a consumer-authored file
+ * whose name collided with a catalog slug came to be deleted silently.
+ *
+ * The predicate is deliberately narrow: agent-kit may destroy a path only when
+ * it can PROVE it created that path, i.e. the path is a symlink resolving into
+ * a directory agent-kit projects from. A real file, a real directory, or a
+ * symlink pointing anywhere else is somebody else's and is never destroyed on a
+ * `shared` surface.
+ */
+import { existsSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { isPathContained } from "#worktrees/identity.js";
+/**
+ * Directories agent-kit projects agent records from.
+ *
+ * Derived from CONFIGURATION, never from the planned record set, so the result
+ * is non-empty even when the catalog agents directory is empty or entirely
+ * absent. That matters: with a plans-derived set, a broken or partial install
+ * produces zero plans, an empty managed set, and a sweep that can no longer
+ * tell agent-kit's own relics from the operator's files.
+ *
+ * The catalog child is derived from `realpathSync(catalogDir)` rather than by
+ * realpathing the child itself. `loadContent` throws when `catalogDir` is
+ * missing, so the parent always resolves — whereas the child may not exist yet
+ * (or any more), and a non-existent child silently contributes only its
+ * unresolved alias form, which then fails to match a symlink recorded against
+ * the real path.
+ */
+export function resolveManagedSourceDirs(input) {
+    const dirs = new Set();
+    const catalogRoots = new Set([resolve(input.catalogDir)]);
+    if (existsSync(input.catalogDir))
+        catalogRoots.add(realpathSync(input.catalogDir));
+    for (const catalogRoot of catalogRoots)
+        dirs.add(join(catalogRoot, "agents"));
+    // Consumer-side override dir. It is frequently absent (no scaffolder creates
+    // it), so it gets the same parent-anchored treatment.
+    const consumerRoots = new Set([resolve(input.consumerRoot)]);
+    if (existsSync(input.consumerRoot))
+        consumerRoots.add(realpathSync(input.consumerRoot));
+    for (const consumerRootForm of consumerRoots)
+        dirs.add(join(consumerRootForm, "agent-agents"));
+    return dirs;
+}
+/**
+ * True when `targetPath` is a symlink agent-kit projected — the only shape it
+ * is allowed to destroy on a `shared` surface.
+ *
+ * The resolved target need not still exist: a dangling link left behind by a
+ * removed catalog record is agent-kit's own relic and must stay prunable.
+ * Containment is delegated to `isPathContained`, which canonicalizes both sides
+ * and rejects `..` escapes, so a sibling directory such as `<managed>-evil`
+ * cannot masquerade as managed.
+ */
+export function isAgentKitOwned(targetPath, managedSourceDirs) {
+    let stat;
+    try {
+        stat = lstatSync(targetPath);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isSymbolicLink())
+        return false;
+    let resolved;
+    try {
+        resolved = resolve(dirname(targetPath), readlinkSync(targetPath));
+    }
+    catch {
+        return false;
+    }
+    const linkParent = dirname(resolved);
+    for (const managedDir of managedSourceDirs) {
+        if (isPathContained(managedDir, linkParent))
+            return true;
+    }
+    return false;
+}

package/dist/esm/symlinker/unified-sync.d.ts

@@ -16,6 +16,22 @@
  * filename pattern but is not in the expected set is removed. This propagates
  * deletions in `agent-rules/` and `agent-skills/` to per-IDE cleanup.
  *
+ * Ownership: a consumer declares `ownership` (see `UnifiedConsumerConfig`).
+ * On a `shared` surface agent-kit destroys only what it can prove it created,
+ * via the single predicate in `ownership.ts`. Both write paths consult that one
+ * predicate but take DIFFERENT actions, and the asymmetry is deliberate:
+ *
+ *   | path        | situation                          | action                  |
+ *   |-------------|------------------------------------|-------------------------|
+ *   | pruneStale  | nothing in the catalog claims this | leave untouched         |
+ *   |             | name                               |                         |
+ *   | applyTarget | a catalog record DOES claim it     | preserve + skip + warn  |
+ *
+ * Quarantining or deleting an unclaimed file would be gratuitous — it is in
+ * nobody's way. Silently replacing a claimed one is the data-loss bug this
+ * guard exists to prevent, because `.claude/agents` is gitignored and the loss
+ * is unrecoverable.
+ *
  * `--check` mode (dry-run): produce a list of (target, status) pairs and
  * return the count of mismatches; perform no writes.
  */
@@ -68,6 +84,22 @@ export interface UnifiedSyncResult {
     readonly fixCount: number;
     /** Mismatches surfaced in check mode. Empty in non-check mode. */
     readonly mismatches: readonly UnifiedSyncMismatch[];
+    /**
+     * Paths on a `shared` surface that agent-kit refused to replace because it
+     * could not prove it created them.
+     *
+     * Deliberately NOT mismatches: a mismatch means drift the tool should fix,
+     * and `wp sync --check` exits non-zero on drift. A user who legitimately
+     * customized a subagent would then red every CI run forever, which is the
+     * pressure that makes people delete their own file. These are warnings.
+     */
+    readonly preserved: readonly UnifiedSyncPreserved[];
+}
+export interface UnifiedSyncPreserved {
+    readonly consumerId: string;
+    readonly targetPath: string;
+    /** Slug the catalog wanted to project there. */
+    readonly slug: string;
 }
 export declare function isSymlinkPointingTo(linkPath: string, expectedAbs: string): boolean;
 /**

package/dist/esm/symlinker/unified-sync.js

@@ -16,6 +16,22 @@
  * filename pattern but is not in the expected set is removed. This propagates
  * deletions in `agent-rules/` and `agent-skills/` to per-IDE cleanup.
  *
+ * Ownership: a consumer declares `ownership` (see `UnifiedConsumerConfig`).
+ * On a `shared` surface agent-kit destroys only what it can prove it created,
+ * via the single predicate in `ownership.ts`. Both write paths consult that one
+ * predicate but take DIFFERENT actions, and the asymmetry is deliberate:
+ *
+ *   | path        | situation                          | action                  |
+ *   |-------------|------------------------------------|-------------------------|
+ *   | pruneStale  | nothing in the catalog claims this | leave untouched         |
+ *   |             | name                               |                         |
+ *   | applyTarget | a catalog record DOES claim it     | preserve + skip + warn  |
+ *
+ * Quarantining or deleting an unclaimed file would be gratuitous — it is in
+ * nobody's way. Silently replacing a claimed one is the data-loss bug this
+ * guard exists to prevent, because `.claude/agents` is gitignored and the loss
+ * is unrecoverable.
+ *
  * `--check` mode (dry-run): produce a list of (target, status) pairs and
  * return the count of mismatches; perform no writes.
  */
@@ -24,6 +40,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { loadContent } from "#content/loader";
 import { DEFAULT_PACKAGED_SKILL_SLUG_SET } from "#content/skill-policy";
 import { RETIRED_UNIFIED_CONSUMERS, selectUnifiedConsumers, unifiedRuleFilename, } from "./consumers.js";
+import { isAgentKitOwned, resolveManagedSourceDirs } from "./ownership.js";
 import { pathHasSymlinkComponent } from "./retired-surfaces.js";
 /**
  * Create a symlink with explicit Windows type hint. POSIX ignores the type;
@@ -170,12 +187,49 @@ function dirsEqual(srcDir, destDir) {
     }
     return true;
 }
+/**
+ * True when applying `plan` would destroy something agent-kit cannot prove it
+ * created, on a surface the user co-owns.
+ *
+ * This is the apply-side half of the ownership question. The prune side asks
+ * the same question via the same predicate but takes a different action, and
+ * the asymmetry is deliberate — see the module docstring.
+ *
+ * An `exclusive` consumer is unaffected: its directory is generated and
+ * gitignored, so replacing an unexpected entry is the intended behavior.
+ */
+function wouldDestroyForeignPath(plan, managedSourceDirs) {
+    if ((plan.consumer.ownership ?? "exclusive") !== "shared")
+        return false;
+    if (!existsSync(plan.targetPath) && !isSymlinkLike(plan.targetPath))
+        return false;
+    return !isAgentKitOwned(plan.targetPath, managedSourceDirs);
+}
+/** `existsSync` follows symlinks, so a dangling link needs its own probe. */
+function isSymlinkLike(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Apply a single planned target. Returns 1 on write, 0 if already correct.
+ *
+ * `preserved` is a third outcome, distinct from both: the projection was
+ * skipped because the target belongs to the operator. It is reported as a
+ * warning, never as drift — see `UnifiedSyncResult`.
  */
-function applyTarget(plan, check) {
+function applyTarget(plan, check, managedSourceDirs) {
     const { consumer, record, targetPath } = plan;
     const sourcePath = record.kind === "skill" ? dirname(record.filePath) : record.filePath;
+    // Gate EVERY strategy, not just the symlink branch: each one below uses its
+    // "is it already what we'd write?" check as the destruction gate, and none of
+    // those checks can distinguish "stale projection" from "operator's file".
+    if (wouldDestroyForeignPath(plan, managedSourceDirs)) {
+        return { wrote: 0, preserved: targetPath };
+    }
     switch (consumer.strategy) {
         case "symlink": {
             // Use the resolved (real) source path so links survive pnpm version churn.
@@ -250,33 +304,6 @@ function applyTarget(plan, check) {
         }
     }
 }
-/**
- * True when `fullPath` is a symlink whose resolved target's directory is one
- * of `managedSourceDirs`. Used to distinguish an agent-kit-managed symlink
- * (safe to prune when stale/renamed) from a real file or a foreign symlink
- * (never agent-kit-managed, must survive `wp sync`). The resolved target
- * itself need not currently exist — a dangling symlink to a since-removed
- * catalog agent still resolves into the managed source dir and is prunable.
- */
-function isManagedAgentSymlink(fullPath, managedSourceDirs) {
-    let stat;
-    try {
-        stat = lstatSync(fullPath);
-    }
-    catch {
-        return false;
-    }
-    if (!stat.isSymbolicLink())
-        return false;
-    try {
-        const linkTarget = readlinkSync(fullPath);
-        const resolved = resolve(dirname(fullPath), linkTarget);
-        return managedSourceDirs.has(dirname(resolved));
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Remove entries under each consumer dir that no longer correspond to any
  * planned record. Only removes entries whose shape matches the consumer's
@@ -294,19 +321,10 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs, c
         }
         set.add(plan.entryName);
     }
-    // Directories that agent-kind sources resolve from (the catalog `agents/`
-    // dir, and a consumer `agent-agents/` override dir if present). Unlike
-    // `.claude/rules` and `.claude/skills` — surfaces with no legitimate
-    // hand-authoring workflow — `.claude/agents` is Claude Code's own native
-    // subagent authoring location. A consumer-authored `.claude/agents/foo.md`
-    // that was never agent-kit-managed must survive `wp sync`; only symlinks
-    // that resolve into a known managed source dir are eligible for pruning.
-    //
-    // The set unions plan-derived dirs with the CONFIGURED source dirs so it is
-    // never empty: with an empty or missing catalog agents dir there are no
-    // plans, and a plans-only set would leave nothing provably managed — the
-    // sweep must then delete nothing, not everything. Dangling managed symlinks
-    // (pointing into a configured dir whose file is gone) stay prunable.
+    // Plan-derived source dirs are folded in alongside the configuration-derived
+    // set. The configured set already guarantees non-emptiness (see
+    // `resolveManagedSourceDirs`); the plan-derived entries additionally cover a
+    // consumer override dir the configuration cannot know about.
     const agentSourceDirs = new Set([
         ...configuredAgentSourceDirs,
         ...plans
@@ -350,16 +368,18 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs, c
             if (!matchesRulePattern && !matchesSkillPattern && !isLink)
                 continue;
             const fullPath = join(dirAbs, name);
-            // Conservative prune for agent-only dirs: skip real files and foreign
-            // symlinks (anything not resolving into a known agent-kit managed
-            // source dir). This guard is unconditional — the source-dir set is
-            // configuration-derived and never empty, so a broken install (empty or
-            // missing catalog agents dir) cannot degrade the sweep into deleting
-            // hand-authored files. Rules/skills dirs have no legitimate
-            // hand-authoring workflow, so their existing
-            // sweep-everything-unexpected behavior is unchanged.
-            const isAgentOnlyDir = consumersForDir.every((c) => c.acceptsKind === "agent");
-            if (isAgentOnlyDir && !isManagedAgentSymlink(fullPath, agentSourceDirs)) {
+            // Conservative prune on a shared surface: skip real files, real dirs, and
+            // foreign symlinks (anything agent-kit cannot prove it created). The
+            // stance is read from the consumer's DECLARED ownership rather than
+            // inferred from its kind — inference by `.every(c => acceptsKind ===
+            // "agent")` would silently switch the guard off for the whole directory
+            // the moment any non-agent consumer was registered on it.
+            //
+            // Exclusive dirs (rules, skills) are generated and gitignored with no
+            // hand-authoring workflow, so their sweep-everything behavior is
+            // deliberately unchanged.
+            const isSharedDir = consumersForDir.some((c) => (c.ownership ?? "exclusive") === "shared");
+            if (isSharedDir && !isAgentKitOwned(fullPath, agentSourceDirs)) {
                 continue;
             }
             if (check) {
@@ -440,10 +460,27 @@ export function runUnifiedSync(options) {
         throw new Error(`wp sync: slug collisions between catalog and consumer (rename consumer copy):\n${lines.join("\n")}`);
     }
     const plans = planTargets(filteredRecords, consumers, consumerRoot);
+    // The directories agent-kit projects agent records from. Configuration-
+    // derived and therefore never empty, so a broken install cannot collapse
+    // ownership into "everything is ours". Owned by ownership.ts, shared by the
+    // apply and prune paths so they cannot answer the question differently.
+    const configuredAgentSourceDirs = resolveManagedSourceDirs({
+        catalogDir: options.catalogDir,
+        consumerRoot,
+    });
     let fixCount = 0;
     const mismatches = [];
+    const preserved = [];
     for (const plan of plans) {
-        const result = applyTarget(plan, options.check === true);
+        const result = applyTarget(plan, options.check === true, configuredAgentSourceDirs);
+        if (result.preserved !== undefined) {
+            preserved.push({
+                consumerId: plan.consumer.id,
+                targetPath: result.preserved,
+                slug: plan.record.slug,
+            });
+            continue;
+        }
         if (result.wrote > 0) {
             fixCount += result.wrote;
             if (options.check === true && result.mismatch !== undefined) {
@@ -455,22 +492,6 @@ export function runUnifiedSync(options) {
             }
         }
     }
-    // Configuration-derived agent source dirs (catalog `agents/` plus the
-    // consumer `agent-agents/` override). Added in both raw-resolved and
-    // realpath forms so set membership survives the /var → /private/var realm
-    // split on macOS. Present even when the dirs are empty or absent — that is
-    // the point: prune eligibility must not collapse to "everything" when a
-    // broken install yields zero planned agent records.
-    const configuredAgentSourceDirs = new Set();
-    for (const candidate of [
-        join(options.catalogDir, "agents"),
-        join(consumerRoot, "agent-agents"),
-    ]) {
-        configuredAgentSourceDirs.add(resolve(candidate));
-        if (existsSync(candidate)) {
-            configuredAgentSourceDirs.add(realpathSync(candidate));
-        }
-    }
     const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs, configuredAgentSourceDirs);
     fixCount += prune.removed;
     mismatches.push(...prune.mismatches);
@@ -480,5 +501,5 @@ export function runUnifiedSync(options) {
     const retiredDirectories = pruneEmptyRetiredConsumerDirs(retiredConsumers, consumerRoot, options.check === true);
     fixCount += retiredDirectories.removed;
     mismatches.push(...retiredDirectories.mismatches);
-    return { fixCount, mismatches };
+    return { fixCount, mismatches, preserved };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/agent-kit",
-  "version": "3.3.5",
+  "version": "3.3.6",
   "private": false,
   "description": "TypeScript-first agent harness for guarded develop/deploy workflows: wp CLI gates, MCP tools, hooks, memory, worktrees, secrets, audits, and evidence checks.",
   "keywords": [
@@ -514,16 +514,16 @@
     "setupWpActionRef": "c2c71a7a4be446fc6858e6b57bf55a11ccfa2d88"
   },
   "optionalDependencies": {
-    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.5",
-    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.5",
-    "@webpresso/agent-kit-runtime-linux-x64": "3.3.5",
-    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.5",
-    "@webpresso/agent-kit-runtime-windows-x64": "3.3.5",
-    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.5",
-    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.5",
-    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.5",
-    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.5",
-    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.5",
-    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.5"
+    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.6",
+    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.6",
+    "@webpresso/agent-kit-runtime-linux-x64": "3.3.6",
+    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.6",
+    "@webpresso/agent-kit-runtime-windows-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.6",
+    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.6"
   }
 }