@kuznai/inception-engine 0.18.0 → 0.20.0

package/dist/{schemas → src/schemas}/manifest.js

@@ -15,7 +15,7 @@ const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 // is valid, while "{home}/../.ssh/config" is rejected.
 // {repo} resolves to the manifest directory at deploy time, enabling repo-local
 // targets (e.g. Antigravity's .agents/rules/ surface).
-const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config|repo)\}(?:[\\/].*)?$/;
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config|repo|workspace)\}(?:[\\/].*)?$/;
 // Standalone schema used for type derivation and single-ID validation (e.g. index.ts).
 export const AgentIdSchema = z.enum(AGENT_IDS);
 // Used inside SkillEntrySchema.agents so that enum failures embed the received
@@ -83,16 +83,25 @@ export const McpServerEntrySchema = z.object({
     // Raw server descriptor passed verbatim to each agent adapter.
     // Adapters are responsible for validating the shape they need.
     config: z.record(z.string(), z.unknown()),
+    // Deployment scope: "global" (default) targets the agent's user-level MCP
+    // config file. "repo" and "workspace" target repo- or workspace-relative
+    // config files for agents that support them (e.g. GitHub Copilot's
+    // .vscode/mcp.json). For agents without scope-specific surfaces the
+    // adapter falls back to the global surface or emits a warning.
+    scope: z.enum(["global", "repo", "workspace"]).default("global"),
 });
 export const AgentRuleEntrySchema = z.object({
     name: nameField,
     agents: agentsField,
     // Relative path to the rules/instruction file within the source bundle.
+    // Must be a .md or .markdown file. Structural requirements (e.g. YAML
+    // frontmatter) are validated per agent requirements by the adapter.
     path: sourcePathField,
     // Deployment scope: "global" targets the agent's home-directory instruction
     // file (default), "repo" targets the project-root instruction file within the
-    // deployed repository (e.g. {repo}/CLAUDE.md for claude-code).
-    scope: z.enum(["global", "repo"]).default("global"),
+    // deployed repository (e.g. {repo}/CLAUDE.md for claude-code), and "workspace"
+    // targets the agent's workspace-local instruction surface.
+    scope: z.enum(["global", "repo", "workspace"]).default("global"),
 });
 export const PermissionsEntrySchema = z.object({
     name: nameField,
@@ -100,15 +109,20 @@ export const PermissionsEntrySchema = z.object({
     // Raw permission config payload validated per agent by the permissions adapter.
     // For claude-code: { permissions: { allow?: string[], deny?: string[] } }
     // For codex: { approval_policy?: "auto" | "manual" | "suggest" | "on-failure" }
+    // For opencode: { permissions: { allow?: string[], ask?: string[], deny?: string[] } }
     config: z.record(z.string(), z.unknown()),
 });
 export const AgentDefinitionEntrySchema = z.object({
     name: nameField,
     agents: agentsField,
     // Relative path to the agent definition Markdown file within the source bundle.
-    // Must be a .md or .markdown file. Content and frontmatter structure are not
-    // validated by inception-engine — format requirements are agent-specific.
+    // Must be a .md or .markdown file. Structural requirements (e.g. YAML
+    // frontmatter) are validated per agent requirements by the adapter.
     path: sourcePathField,
+    // Deployment scope: "global" targets the agent's home-directory definition
+    // directory (if supported), "repo" targets the project-root definition directory
+    // within the deployed repository (default).
+    scope: z.enum(["global", "repo", "workspace"]).default("repo"),
 });
 export const ManifestSchema = z.object({
     skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {

package/dist/{schemas → src/schemas}/registry.d.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 declare const SkillDirRegistryEntrySchema: z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
     kind: z.ZodLiteral<"skill-dir">;
     source: z.ZodString;
     skill: z.ZodString;
@@ -18,6 +20,8 @@ declare const SkillDirRegistryEntrySchema: z.ZodObject<{
     deployed: z.ZodString;
 }, z.core.$strip>;
 declare const FileWriteRegistryEntrySchema: z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
     kind: z.ZodLiteral<"file-write">;
     source: z.ZodString;
     skill: z.ZodString;
@@ -32,6 +36,8 @@ declare const FileWriteRegistryEntrySchema: z.ZodObject<{
     deployed: z.ZodString;
 }, z.core.$strip>;
 declare const ConfigPatchRegistryEntrySchema: z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
     kind: z.ZodLiteral<"config-patch">;
     patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     undoPatch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -46,7 +52,28 @@ declare const ConfigPatchRegistryEntrySchema: z.ZodObject<{
     }>;
     deployed: z.ZodString;
 }, z.core.$strip>;
+declare const FrontmatterEmitRegistryEntrySchema: z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"frontmatter-emit">;
+    patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    undoPatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    created: z.ZodOptional<z.ZodBoolean>;
+    hadFrontmatter: z.ZodOptional<z.ZodBoolean>;
+    skill: z.ZodString;
+    agent: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>;
+    deployed: z.ZodString;
+}, z.core.$strip>;
 export declare const RegistryEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
     kind: z.ZodLiteral<"skill-dir">;
     source: z.ZodString;
     skill: z.ZodString;
@@ -64,6 +91,8 @@ export declare const RegistryEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
     deployed: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
     kind: z.ZodLiteral<"file-write">;
     source: z.ZodString;
     skill: z.ZodString;
@@ -77,6 +106,8 @@ export declare const RegistryEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     deployed: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
     kind: z.ZodLiteral<"config-patch">;
     patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     undoPatch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -90,10 +121,30 @@ export declare const RegistryEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         "github-copilot": "github-copilot";
     }>;
     deployed: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    surfaceId: z.ZodOptional<z.ZodString>;
+    migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"frontmatter-emit">;
+    patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    undoPatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    created: z.ZodOptional<z.ZodBoolean>;
+    hadFrontmatter: z.ZodOptional<z.ZodBoolean>;
+    skill: z.ZodString;
+    agent: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>;
+    deployed: z.ZodString;
 }, z.core.$strip>], "kind">;
 export declare const RegistrySchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     deployments: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        surfaceId: z.ZodOptional<z.ZodString>;
+        migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
         kind: z.ZodLiteral<"skill-dir">;
         source: z.ZodString;
         skill: z.ZodString;
@@ -111,6 +162,8 @@ export declare const RegistrySchema: z.ZodObject<{
         }>>;
         deployed: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
+        surfaceId: z.ZodOptional<z.ZodString>;
+        migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
         kind: z.ZodLiteral<"file-write">;
         source: z.ZodString;
         skill: z.ZodString;
@@ -124,6 +177,8 @@ export declare const RegistrySchema: z.ZodObject<{
         }>;
         deployed: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
+        surfaceId: z.ZodOptional<z.ZodString>;
+        migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
         kind: z.ZodLiteral<"config-patch">;
         patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         undoPatch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -137,11 +192,30 @@ export declare const RegistrySchema: z.ZodObject<{
             "github-copilot": "github-copilot";
         }>;
         deployed: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        surfaceId: z.ZodOptional<z.ZodString>;
+        migratedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"frontmatter-emit">;
+        patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        undoPatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        created: z.ZodOptional<z.ZodBoolean>;
+        hadFrontmatter: z.ZodOptional<z.ZodBoolean>;
+        skill: z.ZodString;
+        agent: z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>;
+        deployed: z.ZodString;
     }, z.core.$strip>], "kind">>;
 }, z.core.$strip>;
 export type SkillDirRegistryEntry = z.infer<typeof SkillDirRegistryEntrySchema>;
 export type FileWriteRegistryEntry = z.infer<typeof FileWriteRegistryEntrySchema>;
 export type ConfigPatchRegistryEntry = z.infer<typeof ConfigPatchRegistryEntrySchema>;
+export type FrontmatterEmitRegistryEntry = z.infer<typeof FrontmatterEmitRegistryEntrySchema>;
 export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
 export type Registry = z.infer<typeof RegistrySchema>;
 export {};

package/dist/{schemas → src/schemas}/registry.js

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { AgentIdSchema } from "./manifest.js";
-const SkillDirRegistryEntrySchema = z.object({
+const RegistryOwnershipMetadataSchema = z.object({
+    surfaceId: z.string().optional(),
+    migratedFrom: z.array(z.string()).optional(),
+});
+const SkillDirRegistryEntrySchema = RegistryOwnershipMetadataSchema.extend({
     kind: z.literal("skill-dir"),
     source: z.string(),
     skill: z.string(),
@@ -8,14 +12,14 @@ const SkillDirRegistryEntrySchema = z.object({
     method: z.enum(["symlink", "copy"]).optional(),
     deployed: z.string(),
 });
-const FileWriteRegistryEntrySchema = z.object({
+const FileWriteRegistryEntrySchema = RegistryOwnershipMetadataSchema.extend({
     kind: z.literal("file-write"),
     source: z.string(),
     skill: z.string(),
     agent: AgentIdSchema,
     deployed: z.string(),
 });
-const ConfigPatchRegistryEntrySchema = z.object({
+const ConfigPatchRegistryEntrySchema = RegistryOwnershipMetadataSchema.extend({
     kind: z.literal("config-patch"),
     patch: z.record(z.string(), z.unknown()),
     undoPatch: z.record(z.string(), z.unknown()),
@@ -23,10 +27,21 @@ const ConfigPatchRegistryEntrySchema = z.object({
     agent: AgentIdSchema,
     deployed: z.string(),
 });
+const FrontmatterEmitRegistryEntrySchema = RegistryOwnershipMetadataSchema.extend({
+    kind: z.literal("frontmatter-emit"),
+    patch: z.record(z.string(), z.unknown()).optional(),
+    undoPatch: z.record(z.string(), z.unknown()).optional(),
+    created: z.boolean().optional(),
+    hadFrontmatter: z.boolean().optional(),
+    skill: z.string(),
+    agent: AgentIdSchema,
+    deployed: z.string(),
+});
 export const RegistryEntrySchema = z.discriminatedUnion("kind", [
     SkillDirRegistryEntrySchema,
     FileWriteRegistryEntrySchema,
     ConfigPatchRegistryEntrySchema,
+    FrontmatterEmitRegistryEntrySchema,
 ]);
 export const RegistrySchema = z.object({
     version: z.literal(1),

package/dist/{types.d.ts → src/types.d.ts}

@@ -5,8 +5,36 @@ export interface AgentPaths {
     windows: string[];
 }
 export type Confidence = "documented" | "implementation-only" | "provisional";
+export type CapabilityKind = "skills" | "mcpServers" | "agentRules" | "permissions" | "agentDefinitions";
 export interface SupportedAgentSurface {
     status: "supported";
+    /**
+     * Declares how this agent relates to the surface:
+     * - "agent-specific" (default when absent): the agent owns this surface
+     *   independently and deploy emits a normal action.
+     * - "native": the agent reads this surface autonomously without any deploy
+     *   action from inception-engine; no action is emitted.
+     * - "shared-via": this agent rides another agent's deployment. When the
+     *   primary agent (`via`) is also in the target list, deploy skips this
+     *   agent's action (the primary writes the shared file). When the primary
+     *   is absent, a guidance warning is emitted instead.
+     */
+    surfaceKind?: {
+        kind: "agent-specific";
+    } | {
+        kind: "native";
+    } | {
+        kind: "shared-via";
+        via: AgentId;
+        /**
+         * When true, this agent cannot deploy to the surface independently —
+         * the primary agent (`via`) must also be in the target list. If the
+         * primary is absent, a guidance warning is emitted and no action is
+         * generated. When false or absent, the agent can deploy to the surface
+         * on its own if the primary is not present.
+         */
+        requiresPrimary?: boolean;
+    };
     path: AgentPaths;
     schemaLabel: string;
     mcpPatchKey?: string;
@@ -50,15 +78,46 @@ export interface AgentConfig {
      * (e.g. GitHub Copilot reads `.claude/skills/` directly).
      */
     skills?: AgentPaths;
+    /**
+     * When `skills` is absent, this field explains why. Currently only
+     * "shared-via" is used — the agent reads skills from the `via` agent's
+     * deployment path natively and needs no separate skills deploy action.
+     */
+    skillsSurfaceKind?: {
+        kind: "shared-via";
+        via: AgentId;
+    };
     detectPaths: AgentPaths;
     detectBinary: string | null;
     provenance: AgentProvenance;
     mcpSupport?: AgentSurfaceSupport;
+    mcpRepoSupport?: AgentSurfaceSupport;
+    mcpWorkspaceSupport?: AgentSurfaceSupport;
     agentRulesSupport?: AgentSurfaceSupport;
     agentRulesRepoSupport?: AgentSurfaceSupport;
+    agentRulesWorkspaceSupport?: AgentSurfaceSupport;
     permissionsSupport?: AgentSurfaceSupport;
     agentDefinitionsSupport?: AgentSurfaceSupport;
+    agentDefinitionsRepoSupport?: AgentSurfaceSupport;
+    agentDefinitionsWorkspaceSupport?: AgentSurfaceSupport;
+    agentDefinitionsTomlSupport?: AgentSurfaceSupport;
+    agentDefinitionsTomlRepoSupport?: AgentSurfaceSupport;
     policyNote?: string;
+    /**
+     * A list of documented surfaces that are currently not safe to support directly.
+     * Preflight will emit warnings for these if the agent is targeted.
+     */
+    unsupportedSurfaces?: AgentSurfaceSupport[];
+    /**
+     * When true, instruction files deployed to this agent must include valid
+     * YAML frontmatter. Drives validateInstructionFileRequirements without
+     * hardcoded agent-ID checks.
+     */
+    instructionFrontmatterRequired?: boolean;
+    /**
+     * When true, preflight runs enterprise-policy detection for this agent.
+     */
+    enterprisePolicyDetection?: boolean;
 }
 export interface PlanWarning {
     kind: "confidence" | "collision" | "ambiguity";
@@ -80,6 +139,7 @@ export interface FileWriteDeployAction {
     source: string;
     target: string;
     confidence?: Confidence;
+    migratedFrom?: string[];
 }
 export interface ConfigPatchDeployAction {
     kind: "config-patch";

package/dist/test/helpers/fs.d.ts

@@ -0,0 +1,2 @@
+export declare function exists(p: string): Promise<boolean>;
+export declare function makeTmpDir(prefix?: string): Promise<string>;

package/dist/test/helpers/fs.js

@@ -0,0 +1,17 @@
+import { access, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function makeTmpDir(prefix = "ie-test-dir") {
+    const dir = path.join(os.tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}

package/dist/test/helpers/path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize path separators to forward slashes for cross-platform path assertions.
+ * Use this instead of hard-coding POSIX separators in expected strings.
+ */
+export declare function normalizeSlashes(value: string): string;
+/**
+ * Assert that a path ends with the given POSIX-style suffix, normalizing separators.
+ * Use instead of: assert.ok(normalizeSlashes(p).endsWith("some/suffix"))
+ */
+export declare function assertPathEndsWith(actual: string, suffix: string, msg?: string): void;

package/dist/test/helpers/path.js

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+/**
+ * Normalize path separators to forward slashes for cross-platform path assertions.
+ * Use this instead of hard-coding POSIX separators in expected strings.
+ */
+export function normalizeSlashes(value) {
+    return value.replaceAll("\\", "/");
+}
+/**
+ * Assert that a path ends with the given POSIX-style suffix, normalizing separators.
+ * Use instead of: assert.ok(normalizeSlashes(p).endsWith("some/suffix"))
+ */
+export function assertPathEndsWith(actual, suffix, msg) {
+    assert.ok(normalizeSlashes(actual).endsWith(suffix), msg ?? `Expected path "${actual}" to end with "${suffix}"`);
+}

package/dist/test/helpers/skill-dir-scenarios.d.ts

@@ -0,0 +1,7 @@
+interface SkillDirScenarioOptions {
+    method: "symlink" | "copy";
+    assertManagedTarget(target: string, source: string, expectedSkillMd: string): Promise<void>;
+}
+export declare function registerSharedSkillDirDeployScenarios(options: SkillDirScenarioOptions): void;
+export declare function registerSharedSkillDirRevertScenarios(options: SkillDirScenarioOptions): void;
+export {};

package/dist/test/helpers/skill-dir-scenarios.js

@@ -0,0 +1,206 @@
+import assert from "node:assert/strict";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { it } from "node:test";
+import { executeDeploy, planDeploy } from "../../src/core/deploy.js";
+import { lookupDeployment, registerDeployment, } from "../../src/core/ownership.js";
+import { executeRevert, planRevert } from "../../src/core/revert.js";
+import { exists, makeTmpDir } from "./fs.js";
+import { createFailingRegistryPersistence, createSkillSource, testSkillManifest, } from "./skill-dir.js";
+const FIRST_SKILL_MD = "---\nname: test\ndescription: First skill\n---\n# First";
+const SECOND_SKILL_MD = "---\nname: test\ndescription: Second skill\n---\n# Second";
+export function registerSharedSkillDirDeployScenarios(options) {
+    it("first deploy succeeds", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            const source = await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            await options.assertManagedTarget(actions[0]?.target, source, FIRST_SKILL_MD);
+            const entry = await lookupDeployment(home, actions[0]?.target);
+            assert.ok(entry);
+            assert.equal(entry.kind, "skill-dir");
+            assert.equal(entry.method, options.method);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("dry-run reports the planned skill-dir change only", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            const { succeeded, failed, planned } = await executeDeploy(actions, true, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            assert.equal(planned.length, 1);
+            assert.equal(planned[0]?.verb, options.method === "symlink" ? "create-symlink" : "copy-dir");
+            assert.ok(!(await exists(actions[0]?.target)));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("refuses to overwrite an unmanaged target", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            const target = actions[0]?.target;
+            await mkdir(target, { recursive: true });
+            await writeFile(path.join(target, "user.txt"), "user content");
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home);
+            assert.equal(succeeded, 0);
+            assert.equal(failed.length, 1);
+            assert.match(failed[0]?.error, /not managed by inception-engine/);
+            assert.equal(await readFile(path.join(target, "user.txt"), "utf-8"), "user content");
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("refuses to overwrite a target with a mismatched registry entry", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            const target = actions[0]?.target;
+            await mkdir(target, { recursive: true });
+            await writeFile(path.join(target, "SKILL.md"), "other");
+            await registerDeployment(home, target, {
+                kind: "skill-dir",
+                source: "/other/source",
+                skill: "other-skill",
+                agent: "codex",
+                method: options.method,
+            });
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home);
+            assert.equal(succeeded, 0);
+            assert.equal(failed.length, 1);
+            assert.match(failed[0]?.error, /not managed by inception-engine/);
+            assert.equal(await readFile(path.join(target, "SKILL.md"), "utf-8"), "other");
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("managed redeploy succeeds", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            const source = await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            await executeDeploy(actions, false, false, home);
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(failed.length, 0);
+            await options.assertManagedTarget(actions[0]?.target, source, FIRST_SKILL_MD);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("restores the prior managed target when registry persistence fails", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            const firstSource = await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            const firstAction = actions[0];
+            await executeDeploy([firstAction], false, false, home);
+            await writeFile(path.join(firstSource, "SKILL.md"), SECOND_SKILL_MD);
+            const failAction = {
+                ...firstAction,
+            };
+            const { succeeded, failed } = await executeDeploy([failAction], false, false, home, {
+                registry: createFailingRegistryPersistence(),
+            });
+            assert.equal(succeeded, 0);
+            assert.equal(failed.length, 1);
+            assert.match(failed[0]?.error, /simulated registry persistence failure/);
+            await options.assertManagedTarget(firstAction.target, firstSource, FIRST_SKILL_MD);
+            assert.ok(!(await exists(`${firstAction.target}.inception-backup`)));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+}
+export function registerSharedSkillDirRevertScenarios(options) {
+    it("reverts a managed skill-dir target", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const { actions } = await planDeploy(testSkillManifest, sourceDir, ["claude-code"], home);
+            await executeDeploy(actions, false, false, home);
+            const revertActions = planRevert(testSkillManifest, ["claude-code"], home);
+            const { succeeded, skipped, failed } = await executeRevert(revertActions, false, false, home);
+            assert.equal(succeeded, 1);
+            assert.equal(skipped, 0);
+            assert.equal(failed.length, 0);
+            assert.ok(!(await exists(actions[0]?.target)));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("skips an unmanaged skill-dir target", async () => {
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            const revertActions = planRevert(testSkillManifest, ["claude-code"], home);
+            const target = revertActions[0]?.target;
+            await mkdir(target, { recursive: true });
+            await writeFile(path.join(target, "SKILL.md"), FIRST_SKILL_MD);
+            const { succeeded, skipped, failed } = await executeRevert(revertActions, false, false, home);
+            assert.equal(succeeded, 0);
+            assert.equal(skipped, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(await exists(target));
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("skips a target whose registry entry belongs to a different skill", async () => {
+        const sourceDir = await makeTmpDir("ie-skill-dir-source");
+        const home = await makeTmpDir("ie-skill-dir-home");
+        try {
+            const source = await createSkillSource(sourceDir, "skills/test-skill", FIRST_SKILL_MD);
+            const revertActions = planRevert(testSkillManifest, ["claude-code"], home);
+            const target = revertActions[0]?.target;
+            await mkdir(target, { recursive: true });
+            await writeFile(path.join(target, "SKILL.md"), FIRST_SKILL_MD);
+            await registerDeployment(home, target, {
+                kind: "skill-dir",
+                source,
+                skill: "different-skill",
+                agent: "codex",
+                method: options.method,
+            });
+            const { succeeded, skipped, failed } = await executeRevert(revertActions, false, false, home);
+            assert.equal(succeeded, 0);
+            assert.equal(skipped, 1);
+            assert.equal(failed.length, 0);
+            assert.ok(await exists(target));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true, force: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+}

package/dist/test/helpers/skill-dir.d.ts

@@ -0,0 +1,7 @@
+import type { RegistryPersistence } from "../../src/core/ownership.ts";
+import type { Manifest } from "../../src/types.ts";
+export declare function createSkillSource(baseDir: string, skillPath?: string, skillBody?: string): Promise<string>;
+export declare const testSkillManifest: Manifest;
+export declare function createFailingRegistryPersistence(error?: Error): RegistryPersistence;
+export declare function assertSymlinkTarget(target: string, source: string): Promise<void>;
+export declare function assertCopyTarget(target: string, expectedSkillMd: string): Promise<void>;