@danieljvdm/dev-kit 0.11.3 → 0.13.0

package/src/sync.ts

@@ -1,4 +1,4 @@
-import { Cause, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { Cause, Effect, FileSystem, Path, Schema, SchemaGetter, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 import { parse as parseJsonc, printParseErrorCode, type ParseError } from "jsonc-parser";
 
@@ -31,6 +31,9 @@ import { acquireProjectProcessLock, PROJECT_PROCESS_LOCK_PATH } from "./project-
 import {
   AppliedStateSchema,
   DevKitLockSchema,
+  EffectSourceLockSchema,
+  EffectTsgoLockSchema,
+  ManagedOutputSchema,
   type AppliedState,
   type DevKitLock,
   type ManagedAgentInstructionsOutput,
@@ -48,11 +51,8 @@ import {
   type VitePlusHooksPlan,
 } from "./vite-plus-hooks.ts";
 import {
-  renderVitePlusConfigTemplate,
   renderVitePlusWorkflowTemplate,
   validateVitePlusQualitySupport,
-  VITE_PLUS_CONFIG_PATH,
-  VITE_PLUS_CONFIG_TEMPLATE,
   VITE_PLUS_GITHUB_ACTIONS_PATH,
   VITE_PLUS_GITHUB_ACTIONS_TEMPLATE,
 } from "./vite-plus-quality.ts";
@@ -149,7 +149,7 @@ export type SkillPlan = {
   readonly metadataChanged: boolean;
 };
 
-class ManifestNotFoundError extends Schema.TaggedErrorClass<ManifestNotFoundError>()(
+class ManifestNotFoundError extends Schema.TaggedError<ManifestNotFoundError>()(
   "ManifestNotFoundError",
   { path: Schema.String },
 ) {
@@ -158,12 +158,12 @@ class ManifestNotFoundError extends Schema.TaggedErrorClass<ManifestNotFoundErro
   }
 }
 
-class StructuredFileError extends Schema.TaggedErrorClass<StructuredFileError>()(
-  "StructuredFileError",
-  { path: Schema.String, message: Schema.String },
-) {}
+class StructuredFileError extends Schema.TaggedError<StructuredFileError>()("StructuredFileError", {
+  path: Schema.String,
+  message: Schema.String,
+}) {}
 
-class UnknownSkillOrFamilyError extends Schema.TaggedErrorClass<UnknownSkillOrFamilyError>()(
+class UnknownSkillOrFamilyError extends Schema.TaggedError<UnknownSkillOrFamilyError>()(
   "UnknownSkillOrFamilyError",
   { name: Schema.String, known: Schema.Array(Schema.String) },
 ) {
@@ -172,12 +172,12 @@ class UnknownSkillOrFamilyError extends Schema.TaggedErrorClass<UnknownSkillOrFa
   }
 }
 
-class InvalidSkillCatalogError extends Schema.TaggedErrorClass<InvalidSkillCatalogError>()(
+class InvalidSkillCatalogError extends Schema.TaggedError<InvalidSkillCatalogError>()(
   "InvalidSkillCatalogError",
   { family: Schema.String, message: Schema.String },
 ) {}
 
-class CommandError extends Schema.TaggedErrorClass<CommandError>()("CommandError", {
+class CommandError extends Schema.TaggedError<CommandError>()("CommandError", {
   command: Schema.String,
   exitCode: Schema.Int,
   output: Schema.String,
@@ -189,7 +189,7 @@ class CommandError extends Schema.TaggedErrorClass<CommandError>()("CommandError
   }
 }
 
-class UnsafeManagedPathError extends Schema.TaggedErrorClass<UnsafeManagedPathError>()(
+class UnsafeManagedPathError extends Schema.TaggedError<UnsafeManagedPathError>()(
   "UnsafeManagedPathError",
   { path: Schema.String, reason: Schema.String },
 ) {
@@ -198,17 +198,17 @@ class UnsafeManagedPathError extends Schema.TaggedErrorClass<UnsafeManagedPathEr
   }
 }
 
-class InvalidProjectStateError extends Schema.TaggedErrorClass<InvalidProjectStateError>()(
+class InvalidProjectStateError extends Schema.TaggedError<InvalidProjectStateError>()(
   "InvalidProjectStateError",
   { message: Schema.String },
 ) {}
 
-class LockedPlanMismatchError extends Schema.TaggedErrorClass<LockedPlanMismatchError>()(
+class LockedPlanMismatchError extends Schema.TaggedError<LockedPlanMismatchError>()(
   "LockedPlanMismatchError",
   { message: Schema.String },
 ) {}
 
-class PlanConflictError extends Schema.TaggedErrorClass<PlanConflictError>()("PlanConflictError", {
+class PlanConflictError extends Schema.TaggedError<PlanConflictError>()("PlanConflictError", {
   conflicts: Schema.Array(Schema.String),
 }) {
   override get message() {
@@ -218,7 +218,7 @@ class PlanConflictError extends Schema.TaggedErrorClass<PlanConflictError>()("Pl
   }
 }
 
-class ApplyRaceError extends Schema.TaggedErrorClass<ApplyRaceError>()("ApplyRaceError", {
+class ApplyRaceError extends Schema.TaggedError<ApplyRaceError>()("ApplyRaceError", {
   path: Schema.String,
 }) {
   override get message() {
@@ -226,9 +226,51 @@ class ApplyRaceError extends Schema.TaggedErrorClass<ApplyRaceError>()("ApplyRac
   }
 }
 
+const fromJsonString = <S extends Schema.Constraint>(schema: S, space?: number) =>
+  space === undefined
+    ? Schema.fromJsonString(schema)
+    : Schema.String.pipe(
+        Schema.decodeTo(Schema.toCodecJson(schema), {
+          decode: SchemaGetter.parseJson(),
+          encode: SchemaGetter.stringifyJson({ space }),
+        }),
+      );
+
+const DevKitSetupSchema = Schema.Struct({
+  effectSource: Schema.optional(EffectSourceLockSchema),
+  effectTsgo: Schema.optional(EffectTsgoLockSchema),
+});
+const OutputOwnershipIdentitySchema = Schema.Union([
+  Schema.Struct({
+    resourceId: Schema.String,
+    path: Schema.String,
+    mode: Schema.Literals(["copy", "symlink"]),
+    kind: Schema.Literals(["directory", "symlink"]),
+    skill: Schema.String,
+    target: Schema.Literals(["agents", "claude", "opencode"]),
+  }),
+  Schema.Struct({
+    resourceId: Schema.String,
+    path: Schema.String,
+    mode: Schema.Literals(["copy", "symlink"]),
+    kind: Schema.Literals(["file", "symlink"]),
+    sourcePath: Schema.String,
+  }),
+]);
+const encodeAppliedStateJson = Schema.encodeSync(fromJsonString(AppliedStateSchema));
+const encodeDevKitLockJson = Schema.encodeSync(fromJsonString(DevKitLockSchema));
+const encodeDevKitLockPrettyJson = Schema.encodeSync(fromJsonString(DevKitLockSchema, 2));
+const encodeDevKitSetupJson = Schema.encodeSync(fromJsonString(DevKitSetupSchema));
+const encodeManifestJson = Schema.encodeSync(fromJsonString(DevKitManifestSchema));
+const encodeManagedOutputJson = Schema.encodeSync(fromJsonString(ManagedOutputSchema));
+const encodeOutputOwnershipIdentityJson = Schema.encodeSync(
+  fromJsonString(OutputOwnershipIdentitySchema),
+);
+const encodePlanSnapshotJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+const encodeAppliedStatePrettyJson = Schema.encodeSync(fromJsonString(AppliedStateSchema, 2));
+
 const SKILL_FAMILIES: SkillCatalog = {
-  effect: ["effect-ts"],
-  "effect-atom-data-fetching": ["effect-ts"],
+  effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis", "build-effect-clis"],
 };
 
 export const DEFAULT_MANIFEST = "dev-kit.jsonc";
@@ -236,6 +278,7 @@ const DEFAULT_LOCKFILE = "dev-kit.lock.json";
 const DEFAULT_STATE = ".dev-kit/state.json";
 const AGENT_INSTRUCTIONS_TEMPLATE = "templates/AGENTS.md";
 const DEV_KIT_SKILL_PATH_PLACEHOLDER = "{{DEV_KIT_SKILL_PATH}}";
+const EFFECT_INSTRUCTIONS_PLACEHOLDER = "{{EFFECT_INSTRUCTIONS}}";
 const PROJECT_COMMAND_POLICY_PLACEHOLDER = "{{PROJECT_COMMAND_POLICY}}";
 const AGENT_INSTRUCTION_MARKERS = [
   { start: "<!-- DEV KIT START -->", end: "<!-- DEV KIT END -->" },
@@ -507,7 +550,7 @@ const runCommand = Effect.fn("runCommand")(function* (
   const trimmed = output.trim();
 
   if (exitCode !== 0) {
-    return yield* new CommandError({ command: formatted, exitCode, output: trimmed });
+    return yield* CommandError.make({ command: formatted, exitCode, output: trimmed });
   }
 
   return trimmed;
@@ -521,20 +564,26 @@ const parseStructuredFile = Effect.fn("parseStructuredFile")(function* <A>(
   filePath: string,
   raw: string,
   schema: Schema.ConstraintDecoder<A>,
+  options: { readonly rejectExcessProperties?: boolean } = {},
 ) {
   const errors: Array<ParseError> = [];
   const parsed = parseJsonc(raw, errors, { allowTrailingComma: true });
   const first = errors[0];
 
   if (first !== undefined) {
-    return yield* new StructuredFileError({
+    return yield* StructuredFileError.make({
       path: filePath,
       message: `${printParseErrorCode(first.error)} at offset ${first.offset}`,
     });
   }
 
-  return yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(
-    Effect.mapError((cause) => new StructuredFileError({ path: filePath, message: cause.message })),
+  return yield* Schema.decodeUnknownEffect(
+    schema,
+    options.rejectExcessProperties ? { onExcessProperty: "error" } : undefined,
+  )(parsed).pipe(
+    Effect.mapError((cause) =>
+      StructuredFileError.make({ path: filePath, message: cause.message }),
+    ),
   );
 });
 
@@ -542,11 +591,13 @@ const readManifest = Effect.fn("readManifest")(function* (manifestPath: string)
   const fs = yield* FileSystem.FileSystem;
 
   if (!(yield* fs.exists(manifestPath))) {
-    return yield* new ManifestNotFoundError({ path: manifestPath });
+    return yield* ManifestNotFoundError.make({ path: manifestPath });
   }
   const raw = yield* fs.readFileString(manifestPath);
 
-  return yield* parseStructuredFile(manifestPath, raw, DevKitManifestSchema);
+  return yield* parseStructuredFile(manifestPath, raw, DevKitManifestSchema, {
+    rejectExcessProperties: true,
+  });
 });
 
 const readOptionalStructuredFile = Effect.fn("readOptionalStructuredFile")(function* <A>(
@@ -577,7 +628,7 @@ const expandSelection = (
     } else if (availableSkills.includes(name) || parseSkillSelector(name)?.type === "package") {
       selected.add(name);
     } else {
-      return Effect.fail(new UnknownSkillOrFamilyError({ name, known }));
+      return Effect.fail(UnknownSkillOrFamilyError.make({ name, known }));
     }
   }
   for (const name of exclude) {
@@ -600,7 +651,7 @@ const resolveManagedPath = Effect.fn("resolveManagedPath")(function* (
   const path = yield* Path.Path;
 
   if (candidate.length === 0 || path.isAbsolute(candidate)) {
-    return yield* new UnsafeManagedPathError({
+    return yield* UnsafeManagedPathError.make({
       path: candidate,
       reason: "must be a non-empty project-relative path",
     });
@@ -614,7 +665,7 @@ const resolveManagedPath = Effect.fn("resolveManagedPath")(function* (
     relative.startsWith(`..${path.sep}`) ||
     path.isAbsolute(relative)
   ) {
-    return yield* new UnsafeManagedPathError({
+    return yield* UnsafeManagedPathError.make({
       path: candidate,
       reason: "resolves outside the project",
     });
@@ -628,7 +679,7 @@ const resolveManagedPath = Effect.fn("resolveManagedPath")(function* (
     const target = yield* observeSymbolicLink(ancestor);
 
     if (target.kind === "symlink") {
-      return yield* new UnsafeManagedPathError({
+      return yield* UnsafeManagedPathError.make({
         path: candidate,
         reason: `ancestor is a symlink: ${portablePath(path, path.relative(projectDir, ancestor))}`,
       });
@@ -658,14 +709,14 @@ const validateReservedPaths = Effect.fn("validateReservedPaths")(function* (
     if (current === undefined) continue;
     for (const other of reserved.slice(index + 1)) {
       if (pathsOverlap(current.path, other.path)) {
-        return yield* new InvalidProjectStateError({
+        return yield* InvalidProjectStateError.make({
           message: `${current.label} path ${current.path} overlaps ${other.label} path ${other.path}`,
         });
       }
     }
     for (const outputPath of outputPaths) {
       if (pathsOverlap(current.path, outputPath)) {
-        return yield* new InvalidProjectStateError({
+        return yield* InvalidProjectStateError.make({
           message: `${current.label} path ${current.path} overlaps managed output ${outputPath}`,
         });
       }
@@ -673,28 +724,27 @@ const validateReservedPaths = Effect.fn("validateReservedPaths")(function* (
   }
 });
 
-const outputIdentity = (output: ManagedOutput) =>
-  JSON.stringify({
-    resourceId: output.resourceId,
-    path: output.path,
-    mode: output.mode,
-    kind: output.kind,
-    digest: output.digest,
-    ...("skill" in output
-      ? { skill: output.skill, target: output.target, catalog: output.catalog }
-      : { sourcePath: output.sourcePath }),
-  });
+const outputIdentity = (output: ManagedOutput) => encodeManagedOutputJson(output);
 
 const outputOwnershipIdentity = (output: ManagedOutput) =>
-  JSON.stringify({
-    resourceId: output.resourceId,
-    path: output.path,
-    mode: output.mode,
-    kind: output.kind,
-    ...("skill" in output
-      ? { skill: output.skill, target: output.target }
-      : { sourcePath: output.sourcePath }),
-  });
+  encodeOutputOwnershipIdentityJson(
+    "skill" in output
+      ? {
+          resourceId: output.resourceId,
+          path: output.path,
+          mode: output.mode,
+          kind: output.kind,
+          skill: output.skill,
+          target: output.target,
+        }
+      : {
+          resourceId: output.resourceId,
+          path: output.path,
+          mode: output.mode,
+          kind: output.kind,
+          sourcePath: output.sourcePath,
+        },
+  );
 
 const usesRawFileModeDigests = (toolVersion: string): boolean => {
   const match = /^(\d+)\.(\d+)\./.exec(toolVersion);
@@ -717,12 +767,12 @@ const validateInventory = Effect.fn("validateManagedInventory")(function* (
 
   for (const output of outputs) {
     if (ids.has(output.resourceId)) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `${label} contains duplicate resource id ${output.resourceId}`,
       });
     }
     if (paths.has(output.path)) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `${label} contains duplicate path ${output.path}`,
       });
     }
@@ -737,7 +787,7 @@ const validateInventory = Effect.fn("validateManagedInventory")(function* (
 
     if (previous === undefined || current === undefined) continue;
     if (current.startsWith(`${previous}/`)) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `${label} contains overlapping paths ${previous} and ${current}`,
       });
     }
@@ -761,7 +811,7 @@ const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(fun
 
     if (previous === undefined || current === undefined) continue;
     if (current.startsWith(`${previous}/`)) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `desired and previously owned paths overlap: ${previous} and ${current}`,
       });
     }
@@ -772,7 +822,7 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
   packageRoot: string,
   projectDir: string,
   sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
-  managesVitePlusQuality: boolean,
+  usesRecommendedVitePlusTasks: boolean,
   targets: ReturnType<typeof normalizeManifest>["targets"],
 ) {
   const fs = yield* FileSystem.FileSystem;
@@ -780,19 +830,24 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
   const templatePath = path.join(packageRoot, AGENT_INSTRUCTIONS_TEMPLATE);
 
   if ((yield* observePath(templatePath)).kind !== "file") {
-    return yield* new InvalidProjectStateError({
+    return yield* InvalidProjectStateError.make({
       message: `dev-kit agent instructions template is not a regular file: ${AGENT_INSTRUCTIONS_TEMPLATE}`,
     });
   }
   const template = yield* fs.readFileString(templatePath);
 
   if (!template.includes(DEV_KIT_SKILL_PATH_PLACEHOLDER)) {
-    return yield* new InvalidProjectStateError({
+    return yield* InvalidProjectStateError.make({
       message: `dev-kit agent instructions template is missing ${DEV_KIT_SKILL_PATH_PLACEHOLDER}`,
     });
   }
+  if (!template.includes(EFFECT_INSTRUCTIONS_PLACEHOLDER)) {
+    return yield* InvalidProjectStateError.make({
+      message: `dev-kit agent instructions template is missing ${EFFECT_INSTRUCTIONS_PLACEHOLDER}`,
+    });
+  }
   if (!template.includes(PROJECT_COMMAND_POLICY_PLACEHOLDER)) {
-    return yield* new InvalidProjectStateError({
+    return yield* InvalidProjectStateError.make({
       message: `dev-kit agent instructions template is missing ${PROJECT_COMMAND_POLICY_PLACEHOLDER}`,
     });
   }
@@ -813,7 +868,24 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
               path.join(devKitSkill.linkPath ?? devKitSkill.path, "SKILL.md"),
             ),
           );
-  const usesVitePlus = (yield* readDirectDependencyNames(projectDir)).includes("vite-plus");
+  const directDependencyNames = yield* readDirectDependencyNames(projectDir);
+  const usesVitePlus = directDependencyNames.includes("vite-plus");
+  const effectInstructions =
+    directDependencyNames.includes("effect") &&
+    (yield* observePath(path.join(projectDir, "node_modules", "effect", "AGENTS.md"))).kind ===
+      "file"
+      ? `# Learning more about the Effect
+
+This repository uses the Effect Typescript library.
+
+Before writing any Effect code, first read \`node_modules/effect/AGENTS.md\`
+**completely**, and follow the links in the file when required.
+
+If you need to learn more about particular Effect apis and concepts that the
+guide doesn't cover, search through the source code in \`node_modules/effect/src\`.
+
+`
+      : "";
   const projectPackage = yield* readProjectPackage(projectDir).pipe(
     Effect.catchTag("ProjectPackageError", (error) =>
       error.message.startsWith("package.json not found:") ? Effect.void : Effect.fail(error),
@@ -821,10 +893,11 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
   );
   const manager = yield* detectPackageManager(projectDir, projectPackage?.packageManager);
   const commandPolicy = usesVitePlus
-    ? renderVitePlusCommandPolicy(projectPackage?.scripts ?? {}, managesVitePlusQuality)
+    ? renderVitePlusCommandPolicy(projectPackage?.scripts ?? {}, usesRecommendedVitePlusTasks)
     : renderPackageScriptCommandPolicy(manager, projectPackage?.scripts ?? {});
   const devKitInstructions = template
     .replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath)
+    .replaceAll(EFFECT_INSTRUCTIONS_PLACEHOLDER, effectInstructions)
     .replaceAll(PROJECT_COMMAND_POLICY_PLACEHOLDER, commandPolicy)
     .trimEnd();
 
@@ -840,7 +913,7 @@ const readGeneratedFileTemplate = Effect.fn("readGeneratedFileTemplate")(functio
   const templatePath = path.join(packageRoot, sourcePath);
 
   if ((yield* observePath(templatePath)).kind !== "file") {
-    return yield* new InvalidProjectStateError({
+    return yield* InvalidProjectStateError.make({
       message: `dev-kit generated file template is not a regular file: ${sourcePath}`,
     });
   }
@@ -865,7 +938,9 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       packageRoot,
       projectDir,
       sourceBySkill,
-      setup.vitePlus.quality.config.enabled,
+      setup.vitePlus.quality.workflow.enabled &&
+        setup.vitePlus.quality.workflow.typecheck.length === 1 &&
+        setup.vitePlus.quality.workflow.typecheck[0] === "vp run typecheck",
       targets,
     );
 
@@ -887,7 +962,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       : yield* observePath(source.absolute);
 
     if (!setup.agentInstructions.enabled && sourceObservation?.kind !== "file") {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: "Claude instructions source is not a regular file: AGENTS.md",
       });
     }
@@ -905,23 +980,6 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       linkTarget,
     });
   }
-  if (setup.vitePlus.quality.config.enabled) {
-    const managed = yield* resolveManagedPath(projectDir, VITE_PLUS_CONFIG_PATH);
-    const template = yield* readGeneratedFileTemplate(packageRoot, VITE_PLUS_CONFIG_TEMPLATE);
-    const content = renderVitePlusConfigTemplate(template, setup.vitePlus.quality.config.typecheck);
-
-    outputs.push({
-      resourceId: "setup:vite-plus-config",
-      path: managed.relative,
-      sourcePath: VITE_PLUS_CONFIG_TEMPLATE,
-      mode: "copy",
-      kind: "file",
-      digest: yield* digestFileContent(content),
-      destination: managed.absolute,
-      content,
-      adoptIfExact: true,
-    });
-  }
   if (setup.vitePlus.quality.workflow.enabled) {
     const managed = yield* resolveManagedPath(projectDir, VITE_PLUS_GITHUB_ACTIONS_PATH);
     const template = yield* readGeneratedFileTemplate(
@@ -958,7 +1016,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       .filter((skill) => skill.name === duplicateOutput.name)
       .map((skill) => skill.selector);
 
-    return yield* new InvalidProjectStateError({
+    return yield* InvalidProjectStateError.make({
       message: `selected skills would both install as ${duplicateOutput.name}: ${selectors.join(", ")}`,
     });
   }
@@ -966,7 +1024,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
     const resolvedSource = sourceBySkill.get(skill.selector);
 
     if (resolvedSource === undefined) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `skill source is unavailable: ${skill.selector}`,
       });
     }
@@ -974,7 +1032,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
     const sourceObservation = yield* observePath(source);
 
     if (sourceObservation.kind !== "directory") {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `skill source is not a directory: ${source}`,
       });
     }
@@ -1027,8 +1085,8 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
   return outputs.sort((left, right) => left.path.localeCompare(right.path));
 });
 
-const canonicalLock = (lock: DevKitLock): string => `${JSON.stringify(lock, null, 2)}\n`;
-const canonicalState = (state: AppliedState): string => `${JSON.stringify(state, null, 2)}\n`;
+const canonicalLock = (lock: DevKitLock): string => `${encodeDevKitLockPrettyJson(lock)}\n`;
+const canonicalState = (state: AppliedState): string => `${encodeAppliedStatePrettyJson(state)}\n`;
 
 const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
   projectDir: string,
@@ -1284,7 +1342,7 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
 const lockedPlanMatches = (current: DevKitLock, next: DevKitLock): boolean =>
   current.toolVersion === next.toolVersion &&
   current.manifestDigest === next.manifestDigest &&
-  JSON.stringify(current.setup) === JSON.stringify(next.setup) &&
+  encodeDevKitSetupJson(current.setup ?? {}) === encodeDevKitSetupJson(next.setup ?? {}) &&
   current.outputs.length === next.outputs.length &&
   current.outputs.every((output, index) => {
     const nextOutput = next.outputs[index];
@@ -1318,11 +1376,11 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   const manifest = normalizeManifest(yield* readManifest(manifestManaged.absolute));
 
   const vitePlusQuality = manifest.setup.vitePlus.quality;
-  const vitePlusQualityEnabled = vitePlusQuality.config.enabled || vitePlusQuality.workflow.enabled;
+  const vitePlusQualityEnabled = vitePlusQuality.workflow.enabled;
 
   if (vitePlusQualityEnabled) {
     if (!manifest.setup.effectTsgo.enabled) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message:
           "setup.vitePlus.quality requires setup.effectTsgo.enabled so managed quality setup converges the Effect-patched compiler",
       });
@@ -1332,15 +1390,10 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
       packageRoot,
       manifest.setup.effectTsgo.typescriptPackage,
       {
-        ...(vitePlusQuality.config.enabled ? { config: vitePlusQuality.config.typecheck } : {}),
-        ...(vitePlusQuality.workflow.enabled
-          ? {
-              workflow: {
-                beforeChecks: vitePlusQuality.workflow.beforeChecks,
-                typecheck: vitePlusQuality.workflow.typecheck,
-              },
-            }
-          : {}),
+        workflow: {
+          beforeChecks: vitePlusQuality.workflow.beforeChecks,
+          typecheck: vitePlusQuality.workflow.typecheck,
+        },
       },
     );
   }
@@ -1368,7 +1421,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
 
   for (const [family, familySkills] of Object.entries(skillFamilies)) {
     if (availableSkills.includes(family)) {
-      return yield* new InvalidSkillCatalogError({
+      return yield* InvalidSkillCatalogError.make({
         family,
         message: `family name conflicts with a skill name: ${family}`,
       });
@@ -1376,7 +1429,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     const missing = familySkills.filter((skill) => !availableSkills.includes(skill));
 
     if (missing.length > 0) {
-      return yield* new InvalidSkillCatalogError({
+      return yield* InvalidSkillCatalogError.make({
         family,
         message: `family references missing skills: ${missing.join(", ")}`,
       });
@@ -1405,7 +1458,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     const catalogSkill = catalogBySelector.get(selector);
 
     if (catalogSkill === undefined) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `selected skill is unavailable: ${selector}`,
       });
     }
@@ -1422,7 +1475,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   const nextLock: DevKitLock = {
     version: 1,
     toolVersion: DEV_KIT_VERSION,
-    manifestDigest: yield* digestText(JSON.stringify(manifest)),
+    manifestDigest: yield* digestText(encodeManifestJson(manifest)),
     setup: {
       ...(effectSource === undefined
         ? {}
@@ -1509,12 +1562,12 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   ]);
   if (options.locked) {
     if (!currentLock) {
-      return yield* new LockedPlanMismatchError({
+      return yield* LockedPlanMismatchError.make({
         message: "dev-kit.lock.json is required with --locked",
       });
     }
     if (!lockedPlanMatches(currentLock, nextLock)) {
-      return yield* new LockedPlanMismatchError({
+      return yield* LockedPlanMismatchError.make({
         message: "manifest or packaged skills differ from dev-kit.lock.json",
       });
     }
@@ -1534,7 +1587,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   );
 
   if (manifest.setup.claudeInstructions.enabled && removesClaudeInstructionsSource) {
-    return yield* new InvalidProjectStateError({
+    return yield* InvalidProjectStateError.make({
       message:
         "cannot disable agentInstructions while claudeInstructions still links to an AGENTS.md that would be removed",
     });
@@ -1551,8 +1604,10 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     nextLock,
     nextState: planned.nextState,
     metadataChanged:
-      JSON.stringify(currentLock) !== JSON.stringify(nextLock) ||
-      JSON.stringify(currentState) !== JSON.stringify(planned.nextState),
+      currentLock === undefined ||
+      encodeDevKitLockJson(currentLock) !== encodeDevKitLockJson(nextLock) ||
+      currentState === undefined ||
+      encodeAppliedStateJson(currentState) !== encodeAppliedStateJson(planned.nextState),
   } satisfies SkillPlan;
 });
 
@@ -1652,12 +1707,11 @@ const verifyPackageSkillSources = Effect.fn("verifyPackageSkillSources")(functio
     const observation = yield* observePath(resolved.path);
 
     if (
-      resolved.path !== action.desired.source ||
       resolved.version !== catalog.version ||
       observation.kind !== "directory" ||
       observation.digest !== catalog.digest
     ) {
-      return yield* new ApplyRaceError({ path: action.desired.source });
+      return yield* ApplyRaceError.make({ path: action.desired.source });
     }
     verified.add(key);
   }
@@ -1667,7 +1721,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   const conflicts = plan.actions.filter((action) => action.action === "conflict");
 
   if (conflicts.length > 0) {
-    return yield* new PlanConflictError({
+    return yield* PlanConflictError.make({
       conflicts: conflicts.map((action) =>
         action.action === "conflict" ? `${action.path}: ${action.reason}` : "",
       ),
@@ -1677,7 +1731,9 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const mutating = plan.actions.filter(
-    (action): action is Exclude<SkillPlanAction, { readonly action: "unchanged" | "conflict" }> =>
+    (
+      action,
+    ): action is Extract<SkillPlanAction, { readonly action: "create" | "update" | "remove" }> =>
       action.action === "create" || action.action === "update" || action.action === "remove",
   );
 
@@ -1686,7 +1742,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
       action.action === "remove" ? action.destination : action.desired.destination;
 
     if (!observationsEqual(yield* observePath(destination), action.observed)) {
-      return yield* new ApplyRaceError({
+      return yield* ApplyRaceError.make({
         path: action.action === "remove" ? action.previous.path : action.desired.path,
       });
     }
@@ -1702,7 +1758,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   });
   const stageDir = path.join(tempDir, "stage");
   const backupDir = path.join(tempDir, "backup");
-  const stagedByResource = new Map<string, string>();
+  const stagedByAction = new Map<(typeof mutating)[number], string>();
   let stageIndex = 0;
 
   for (const action of mutating) {
@@ -1718,7 +1774,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
       yield* fs.writeFileString(staged, action.stagedContent);
     } else if (action.action === "remove") {
       if (action.stagedContent === undefined) {
-        return yield* new InvalidProjectStateError({
+        return yield* InvalidProjectStateError.make({
           message: `missing staged content for ${action.previous.resourceId}`,
         });
       }
@@ -1733,7 +1789,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
         const symbolicLink = yield* findNestedSymbolicLink(staged);
 
         if (symbolicLink !== undefined) {
-          return yield* new InvalidProjectStateError({
+          return yield* InvalidProjectStateError.make({
             message: `staged skill contains a symlink: ${action.desired.path}`,
           });
         }
@@ -1753,7 +1809,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
             : undefined;
 
         if (observation.kind !== "file" || digest !== action.desired.digest) {
-          return yield* new InvalidProjectStateError({
+          return yield* InvalidProjectStateError.make({
             message: `staged output digest mismatch for ${action.desired.path}`,
           });
         }
@@ -1761,15 +1817,12 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
         observation.kind !== action.desired.kind ||
         observation.digest !== action.desired.digest
       ) {
-        return yield* new InvalidProjectStateError({
+        return yield* InvalidProjectStateError.make({
           message: `staged output digest mismatch for ${action.desired.path}`,
         });
       }
     }
-    stagedByResource.set(
-      action.action === "remove" ? action.previous.resourceId : action.desired.resourceId,
-      staged,
-    );
+    stagedByAction.set(action, staged);
   }
 
   yield* verifyPackageSkillSources(plan);
@@ -1791,16 +1844,13 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   let replacementIndex = 0;
 
   for (const action of mutating) {
-    const staged =
-      action.action === "remove"
-        ? stagedByResource.get(action.previous.resourceId)
-        : stagedByResource.get(action.desired.resourceId);
+    const staged = stagedByAction.get(action);
 
     if (
       (action.action !== "remove" || action.stagedContent !== undefined) &&
       staged === undefined
     ) {
-      return yield* new InvalidProjectStateError({
+      return yield* InvalidProjectStateError.make({
         message: `missing staged output for ${
           action.action === "remove" ? action.previous.resourceId : action.desired.resourceId
         }`,
@@ -1849,7 +1899,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
         replacement.expected !== undefined &&
         !observationsEqual(observed, replacement.expected)
       ) {
-        return yield* new ApplyRaceError({ path: replacement.path });
+        return yield* ApplyRaceError.make({ path: replacement.path });
       }
       if (observed.kind !== "missing") {
         yield* fs.makeDirectory(path.dirname(replacement.backup), { recursive: true });
@@ -1887,7 +1937,7 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
   const conflicts = plan.actions.filter((action) => action.action === "conflict");
 
   if (conflicts.length > 0) {
-    return yield* new PlanConflictError({
+    return yield* PlanConflictError.make({
       conflicts: conflicts.map((action) =>
         action.action === "conflict" ? `${action.path}: ${action.reason}` : "",
       ),
@@ -1897,7 +1947,7 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
 
   yield* acquireProjectProcessLock(plan.projectDir);
   const replanned = yield* planProjectSkills(options);
-  const originalSignature = JSON.stringify({
+  const originalSignature = encodePlanSnapshotJson({
     actions: plan.actions,
     effectSource: plan.effectSource,
     effectTsgo: plan.effectTsgo,
@@ -1905,7 +1955,7 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
     nextLock: plan.nextLock,
     nextState: plan.nextState,
   });
-  const nextSignature = JSON.stringify({
+  const nextSignature = encodePlanSnapshotJson({
     actions: replanned.actions,
     effectSource: replanned.effectSource,
     effectTsgo: replanned.effectTsgo,
@@ -1915,7 +1965,7 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
   });
 
   if (originalSignature !== nextSignature) {
-    return yield* new ApplyRaceError({ path: "project state" });
+    return yield* ApplyRaceError.make({ path: "project state" });
   }
   const changes = plannedChangeCount(replanned);