ddduck 0.1.2 → 0.2.0

package/scripts/lib/cli-contract.mjs

@@ -82,7 +82,7 @@ export function renderHelp(command) {
   const usage = {
     undefined: [
       "Usage: ddduck <command> [options]",
-      "Commands: init, check, generate, query, install, create, move, split, retire.",
+      "Commands: init, check, generate, query, diff, install, create, move, split, retire.",
       "Run `ddduck <command> --help` for command usage.",
     ],
     init: [
@@ -118,19 +118,30 @@ export function renderHelp(command) {
       "JSON: output is always JSON; --json is accepted and has no effect.",
       "Options: --id <model-node-id> (repeatable for context), --root <product-root>, --history.",
     ],
+    diff: [
+      "Syntax: ddduck diff --base <previous-product-root> [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); --base is required; output is text.",
+      "Writes: nothing; source roots are validated independently and generated freshness is not required.",
+      "Success output: a stable-ID comparison of added, removed, changed, and relocated canonical records, with source digests and explicit exclusions.",
+      "Exit status: 0 on a completed comparison (including differences) or help; 2 for a busy root; 1 for invalid input, source, interrupted state, or different Model IDs.",
+      "JSON: --json emits one ModelDiff document; comparison is canonical YAML only and requires human interpretation.",
+    ],
     install: [
       "Syntax: ddduck install skill update-ddduck-specs [--repo <repository-root>]",
       "Defaults: --repo is the current directory.",
-      "Writes: the selected host skill adapter and .ddduck/agent-skills.lock.json in --repo.",
+      "Writes: the selected host skill bundle and .ddduck/agent-skills.lock.json in --repo.",
       "Success output: one text result with the action (created, upgraded, or no-op), repository, canonical path, and lock path.",
       "Exit status: 0 on installation, no-op, or help; nonzero on invalid input or conflicting host state.",
       "JSON: unavailable; --json is not accepted.",
     ],
     create: [
       "Syntax: ddduck create guarantee --origin <origin> --classification <invariant|acceptance-criterion> --owner <domain-id> --statement <text> [--root <product-root>] [--json]",
-      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); the next origin/classification serial is allocated.",
-      "Writes: the new Guarantee, its owning Domain, and all generated views through staged publication.",
-      "Success output: one text result with the allocated ID, root, canonical paths, and generated paths.",
+      "Syntax: ddduck create domain --id domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]",
+      "Syntax: ddduck create concept --id concept:<slug> --owner domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]",
+      "Syntax: ddduck create use-case --file <yaml-file> [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); guarantees allocate the next origin/classification serial; other kinds require an explicit ID or complete UseCase input.",
+      "Writes: the new node, its owning collection, and all generated views through staged publication; input files are read-only.",
+      "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
       "Exit status: 0 on publication or help; 2 when the product root is busy (operation lock held by a running process, retryable); 1 with no intended product changes on any other failure.",
       "JSON: --json emits the same result as one JSON object.",
     ],

package/scripts/lib/fr-to-code-audit.mjs

@@ -141,6 +141,12 @@ function renderReport(record, productionAnchors, testAnchors) {
     requirement: record.requirement,
     coverage: record.coverage,
     verdict: record.verdict,
+    verificationScope: {
+      verdictSource: "input-record",
+      anchorIntegrityChecked: true,
+      testsExecuted: false,
+      behaviorVerified: false,
+    },
     productionAnchors,
     testAnchors,
     reviewerDisposition: record.reviewerDisposition,

package/scripts/lib/product-authoring.mjs

@@ -0,0 +1,52 @@
+const kinds = {
+  Domain: { prefix: "domain", directory: "domains", collection: "domains" },
+  Concept: { prefix: "concept", directory: "concepts", collection: "concepts" },
+  UseCase: { prefix: "use-case", directory: "use-cases", collection: "useCases" },
+};
+
+export function buildAuthoringPlan(snapshot, request) {
+  const definition = kinds[request.kind];
+  if (!definition) throw new Error(`Unsupported creation kind ${request.kind}`);
+  const models = snapshot.nodes.filter(({ kind }) => kind === "Model");
+  if (models.length !== 1) throw new Error("Creation requires exactly one Model");
+  const [model] = models;
+  const node =
+    request.kind === "UseCase"
+      ? globalThis.structuredClone(request.node)
+      : {
+          schemaVersion: "1",
+          kind: request.kind,
+          id: request.id,
+          model: model.id,
+          ...(request.kind === "Concept" ? { ownerDomain: request.ownerDomain } : {}),
+          name: request.name,
+          purpose: request.purpose,
+          ...(request.kind === "Domain" ? { concepts: [], interfaces: [], guarantees: [] } : {}),
+        };
+  if (node?.kind !== request.kind) throw new Error(`create ${definition.prefix} requires kind ${request.kind}`);
+  if (node.model !== model.id) throw new Error(`New node model must be ${model.id}`);
+  if (typeof node.id !== "string" || !new RegExp(`^${definition.prefix}:[a-z0-9][a-z0-9-]*$`).test(node.id)) {
+    throw new Error(`Invalid ${request.kind} ID ${JSON.stringify(node.id)}`);
+  }
+  if (snapshot.nodes.some(({ id }) => id === node.id)) throw new Error(`Model node ${node.id} already exists`);
+  const destination = `model/${definition.directory}/${node.id.slice(definition.prefix.length + 1)}.yaml`;
+  if (Object.values(snapshot.canonicalPaths).includes(destination)) {
+    throw new Error(`Canonical destination already occupied: ${destination}`);
+  }
+  const parent =
+    request.kind === "Concept"
+      ? snapshot.nodes.find(({ id, kind }) => kind === "Domain" && id === node.ownerDomain)
+      : model;
+  if (!parent) throw new Error(`Unknown domain ${node.ownerDomain}`);
+  return {
+    operation: `create ${definition.prefix}`,
+    affectedIds: [node.id, parent.id],
+    replacements: [
+      { path: destination, value: node },
+      {
+        path: snapshot.canonicalPaths[parent.id],
+        value: { ...parent, [definition.collection]: [...(parent[definition.collection] ?? []), node.id] },
+      },
+    ],
+  };
+}

package/scripts/lib/product-diff.mjs

@@ -0,0 +1,155 @@
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { validateProduct } from "../check-model.mjs";
+import { shellQuote, sourceDigestFromSources } from "./context-pack.mjs";
+import { detectProductLayout, loadProductNodes } from "./product-layout.mjs";
+import { assertProductNotBusy, findLeftoverOperationState } from "./product-operation.mjs";
+
+export function compareProductSnapshots(before, after) {
+  const beforeModel = modelId(before);
+  const afterModel = modelId(after);
+  if (beforeModel !== afterModel) {
+    const error = new Error(`Cannot compare different Model IDs: ${beforeModel} and ${afterModel}`);
+    error.nextAction = "Choose two product roots representing the same Model ID, then retry the diff.";
+    throw error;
+  }
+  const beforeNodes = new Map(before.nodes.map((node) => [node.id, node]));
+  const afterNodes = new Map(after.nodes.map((node) => [node.id, node]));
+  const result = { added: [], removed: [], changed: [], relocated: [] };
+  for (const id of [...new Set([...beforeNodes.keys(), ...afterNodes.keys()])].sort()) {
+    const previous = beforeNodes.get(id);
+    const current = afterNodes.get(id);
+    if (!previous) {
+      result.added.push(record(current, after.canonicalPaths[id]));
+    } else if (!current) {
+      result.removed.push(record(previous, before.canonicalPaths[id]));
+    } else {
+      const changes = fieldChanges(previous, current);
+      if (changes.length > 0) result.changed.push({ id, kind: current.kind, changes });
+      if (before.canonicalPaths[id] !== after.canonicalPaths[id]) {
+        result.relocated.push({
+          id,
+          kind: current.kind,
+          beforePath: before.canonicalPaths[id],
+          afterPath: after.canonicalPaths[id],
+        });
+      }
+    }
+  }
+  return result;
+}
+
+export function compareProductRoots(beforeRoot, afterRoot) {
+  const before = loadDiffRoot(beforeRoot);
+  const after = loadDiffRoot(afterRoot);
+  return {
+    schemaVersion: "1",
+    kind: "ModelDiff",
+    before: { modelId: modelId(before.snapshot), sourceDigest: before.sourceDigest },
+    after: { modelId: modelId(after.snapshot), sourceDigest: after.sourceDigest },
+    scope: "canonical-yaml-only",
+    excludedScopes: ["decision-content", "evidence-content", "delivery-artifacts", "runtime"],
+    ...compareProductSnapshots(before.snapshot, after.snapshot),
+  };
+}
+
+export function renderProductDiff(report) {
+  const lines = [
+    `Model diff: ${report.before.modelId}`,
+    `Before: ${report.before.sourceDigest}`,
+    `After: ${report.after.sourceDigest}`,
+    `Scope: ${report.scope}`,
+    `Excluded: ${report.excludedScopes.join(", ")}`,
+  ];
+  for (const entry of report.added) lines.push(`Added ${entry.id} (${entry.kind}) at ${entry.sourcePath}`);
+  for (const entry of report.removed) lines.push(`Removed ${entry.id} (${entry.kind}) from ${entry.sourcePath}`);
+  for (const entry of report.changed) {
+    lines.push(`Changed ${entry.id} (${entry.kind})`);
+    for (const change of entry.changes) {
+      const before = change.beforePresent ? JSON.stringify(change.before) : "<absent>";
+      const after = change.afterPresent ? JSON.stringify(change.after) : "<absent>";
+      lines.push(`  ${change.path}: ${before} -> ${after}`);
+    }
+  }
+  for (const entry of report.relocated) {
+    lines.push(`Relocated ${entry.id} (${entry.kind}): ${entry.beforePath} -> ${entry.afterPath}`);
+  }
+  if ([report.added, report.removed, report.changed, report.relocated].every((entries) => entries.length === 0)) {
+    lines.push("No canonical record changes.");
+  }
+  lines.push("Structural comparison requires human interpretation; source reads are not atomic snapshots.");
+  return lines.join("\n");
+}
+
+function loadDiffRoot(rootPath) {
+  const layout = detectProductLayout(rootPath);
+  try {
+    assertReadable(layout.root);
+    const check = validateProduct(layout.root, { includeDocumentation: false, sourceOnly: true });
+    if (check.errors.length > 0) throw new Error(`Validation failed for ${layout.root}:\n${check.errors.join("\n")}`);
+    const loaded = loadProductNodes(layout);
+    const canonicalPaths = Object.fromEntries(
+      [...loaded.nodeFiles].map(([id, filePath]) => [
+        id,
+        path.relative(layout.root, filePath).split(path.sep).join("/"),
+      ]),
+    );
+    const sources = new Map([...loaded.nodeSources].map(([id, bytes]) => [canonicalPaths[id], bytes]));
+    assertReadable(layout.root);
+    return {
+      snapshot: { nodes: [...loaded.nodes.values()], canonicalPaths },
+      sourceDigest: sourceDigestFromSources(sources),
+    };
+  } catch (error) {
+    error.nextAction ??= `Fix the product root and its source files, run ddduck check --root ${shellQuote(layout.root)}, then retry the diff.`;
+    throw error;
+  }
+}
+
+function assertReadable(root) {
+  assertProductNotBusy(root);
+  const leftover = findLeftoverOperationState(root);
+  if (leftover) {
+    const error = new Error(`An interrupted ddduck operation left ${leftover.entries.join(", ")} in ${root}`);
+    error.nextAction = `Run ddduck generate --root ${shellQuote(root)} to reclaim the interrupted operation state, then retry the diff.`;
+    throw error;
+  }
+}
+
+function modelId(snapshot) {
+  const models = snapshot.nodes.filter((node) => node.kind === "Model");
+  if (models.length !== 1) throw new Error("A product snapshot must contain exactly one Model record");
+  return models[0].id;
+}
+
+function record(node, sourcePath) {
+  return { id: node.id, kind: node.kind, sourcePath, node: globalThis.structuredClone(node) };
+}
+
+function fieldChanges(before, after, pointer = "") {
+  const changes = [];
+  for (const key of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+    const fieldPath = `${pointer}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+    const beforePresent = Object.hasOwn(before, key);
+    const afterPresent = Object.hasOwn(after, key);
+    const previous = before[key];
+    const current = after[key];
+    if (beforePresent && afterPresent && isDeepStrictEqual(previous, current)) continue;
+    if (beforePresent && afterPresent && isMapping(previous) && isMapping(current)) {
+      changes.push(...fieldChanges(previous, current, fieldPath));
+    } else {
+      changes.push({
+        path: fieldPath,
+        beforePresent,
+        afterPresent,
+        ...(beforePresent ? { before: globalThis.structuredClone(previous) } : {}),
+        ...(afterPresent ? { after: globalThis.structuredClone(current) } : {}),
+      });
+    }
+  }
+  return changes.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+}
+
+function isMapping(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/scripts/lib/product-operation.mjs

@@ -26,7 +26,7 @@ import {
 } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { isScalar, parseDocument, stringify } from "yaml";
+import { isScalar, isSeq, parseDocument, stringify } from "yaml";
 import { checkGeneratedDocs } from "../check-generated-docs.mjs";
 import { checkGeneratedGraph } from "../check-generated-graph.mjs";
 import { validateProduct } from "../check-model.mjs";
@@ -476,6 +476,14 @@ function serializeReplacement(target, relativePath, value) {
     const existing = document.get(key, true);
     if (isScalar(existing) && (next === null || typeof next !== "object")) {
       existing.value = next;
+    } else if (
+      isSeq(existing) &&
+      Array.isArray(next) &&
+      next.length > existing.items.length &&
+      next.every((item) => item === null || typeof item !== "object") &&
+      existing.items.every((item, index) => isScalar(item) && item.value === next[index])
+    ) {
+      for (const item of next.slice(existing.items.length)) existing.add(document.createNode(item));
     } else {
       document.set(key, document.createNode(next));
     }

package/scripts/lib/skill-installer.mjs

@@ -2,10 +2,10 @@
  * Installer for the bundled update-ddduck-specs agent skill, behind `ddduck
  * install skill`. Selects a host topology from the repository state (codex
  * .agents/, claude-code .claude/, or shared via symlink), plans create,
- * upgrade, or no-op against the canonical SKILL.md and the
+ * upgrade, or no-op against the canonical skill bundle and the
  * .ddduck/agent-skills.lock.json lock, and applies the plan with atomic
  * writes plus rollback of everything touched on failure. Conflicting host
- * state or a locally modified canonical file refuses with a nextAction
+ * state or a locally modified managed bundle refuses with a nextAction
  * naming the exact path to resolve.
  */
 
@@ -23,7 +23,7 @@ import {
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 
-const lockSchemaVersion = 1;
+const lockSchemaVersion = 2;
 const lockRelativePath = path.join(".ddduck", "agent-skills.lock.json");
 
 const defaultOperations = {
@@ -126,7 +126,7 @@ const installTopologies = [
 /**
  * Install (or upgrade) the bundled skill into a repository: load, plan, apply.
  * @param {{repository: string, skillName: string, skillPath: string, packageVersion: string, operations?: object}} options - Repository root, skill identity, bundled asset path, and ddduck version for the lock.
- * @returns {{action: "create"|"upgrade"|"no-op", skillSha256: string, canonicalPath: string, lockPath: string}} The installation result.
+ * @returns {{action: "create"|"upgrade"|"no-op", skillSha256: string, bundleSha256: string, canonicalPath: string, lockPath: string}} The installation result.
  */
 export function installSkill(options) {
   const bundle = loadSkillBundle(options);
@@ -135,25 +135,35 @@ export function installSkill(options) {
 }
 
 /**
- * Read the bundled skill asset and compute its sha256.
+ * Read the bundled skill directory and compute per-file and bundle digests.
  * @param {{skillName: string, skillPath: string, operations?: object}} options - Skill name, SKILL.md path, and fs overrides for tests.
- * @returns {{name: string, bytes: Buffer, sha256: string}} The loaded bundle.
+ * @returns {{name: string, files: {path: string, bytes: Buffer, sha256: string}[], skillSha256: string, bundleSha256: string, sha256: string}} The loaded bundle.
  */
 export function loadSkillBundle({ skillName, skillPath, operations = {} }) {
   const resolvedOperations = { ...defaultOperations, ...operations };
   if (pathState(skillPath, resolvedOperations).type !== "file") {
     throw new Error(`Missing bundled skill asset: ${skillPath}`);
   }
-  const bytes = resolvedOperations.readFileSync(skillPath);
-  return { name: skillName, bytes, sha256: sha256(bytes) };
+  const files = readBundleFiles(path.dirname(skillPath), resolvedOperations);
+  const skill = files.find(({ path: relativePath }) => relativePath === skillFileName);
+  if (!skill) throw new Error(`Missing bundled skill asset: ${skillPath}`);
+  const bundleSha256 = files.length === 1 ? skill.sha256 : digestBundle(files);
+  return {
+    name: skillName,
+    files,
+    skillSha256: skill.sha256,
+    bundleSha256,
+    // Preserve the internal single-file field while older callers migrate.
+    sha256: skill.sha256,
+  };
 }
 
 /**
  * Inspect the repository's lock, canonical file, and host adapters and decide
  * the action: create, upgrade, or no-op — or throw on conflicting host state,
  * an incomplete lock, or a locally modified canonical skill.
- * @param {{repository: string, skillName: string, bundle: {sha256: string}, operations?: object}} options - Repository root, skill name, loaded bundle, and fs overrides.
- * @returns {{action: string, paths: object, topology: object, adaptersToMaterialize: object[], writeCanonical: boolean}} The install plan for applySkillInstall.
+ * @param {{repository: string, skillName: string, bundle: object, operations?: object}} options - Repository root, skill name, loaded bundle, and fs overrides.
+ * @returns {{action: string, paths: object, topology: object, adaptersToMaterialize: object[], writeBundle: boolean, staleFiles: string[]}} The install plan for applySkillInstall.
  */
 export function planSkillInstall({ repository, skillName, bundle, operations = {} }) {
   const resolvedOperations = { ...defaultOperations, ...operations };
@@ -183,55 +193,71 @@ export function planSkillInstall({ repository, skillName, bundle, operations = {
       );
     }
     if (canonical.type === "absent") {
-      return createPlan({ paths, adapters, writeCanonical: true });
+      return createPlan({ paths, adapters, writeBundle: true });
     }
-    if (canonical.type !== "file" || sha256(resolvedOperations.readFileSync(paths.canonical)) !== bundle.sha256) {
+    if (
+      canonical.type !== "file" ||
+      sha256(resolvedOperations.readFileSync(paths.canonical)) !== bundle.skillSha256 ||
+      bundle.files.length !== 1
+    ) {
       throw conflictingHostState(`Conflicting canonical skill destination: ${paths.canonical}`, paths.canonical);
     }
-    return createPlan({ paths, adapters, writeCanonical: false });
+    return createPlan({ paths, adapters, writeBundle: false });
   }
 
   const lock = lockState.value;
   if (!isValidLock(lock, skillName, topology)) throw incompleteLock(paths.lock);
-  if (canonical.type === "absent") return createPlan({ paths, adapters, writeCanonical: true });
-  if (canonical.type !== "file") throw locallyModifiedCanonical(paths.canonical);
-  if (sha256(resolvedOperations.readFileSync(paths.canonical)) !== lock.skillSha256) {
-    throw locallyModifiedCanonical(paths.canonical);
+  if (canonical.type === "absent") {
+    assertRemainingBundleMatchesLock(paths, lock, resolvedOperations);
+    return createPlan({ paths, adapters, writeBundle: true });
   }
+  if (canonical.type !== "file") throw locallyModifiedCanonical(paths.canonical);
+  assertInstalledBundleMatchesLock(paths, lock, resolvedOperations);
   if (adapters.some(({ state }) => state !== "valid")) throw incompleteLock(paths.lock);
 
+  const installedDigest = lock.bundleSha256 ?? lock.skillSha256;
+  const staleFiles =
+    lock.files
+      ?.map(({ path: relativePath }) => relativePath)
+      .filter((relativePath) => !bundle.files.some((file) => file.path === relativePath)) ?? [];
+
   return {
-    action: lock.skillSha256 === bundle.sha256 ? "no-op" : "upgrade",
+    action: installedDigest === bundle.bundleSha256 ? "no-op" : "upgrade",
     paths,
     topology,
     adaptersToMaterialize: [],
-    writeCanonical: lock.skillSha256 !== bundle.sha256,
+    writeBundle: installedDigest !== bundle.bundleSha256,
+    staleFiles,
   };
 }
 
 /**
- * Execute an install plan: atomically write the canonical skill, materialize
+ * Execute an install plan: atomically write each bundled file, materialize
  * host adapters, and write the lock; on failure roll back everything touched
  * and report any recovery failures in the thrown error.
- * @param {{packageVersion: string, bundle: {name: string, bytes: Buffer, sha256: string}, plan: object, operations?: object}} options - ddduck version for the lock, loaded bundle, plan from planSkillInstall, and fs overrides.
- * @returns {{action: string, skillSha256: string, canonicalPath: string, lockPath: string}} The installation result.
+ * @param {{packageVersion: string, bundle: object, plan: object, operations?: object}} options - ddduck version for the lock, loaded bundle, plan from planSkillInstall, and fs overrides.
+ * @returns {{action: string, skillSha256: string, bundleSha256: string, canonicalPath: string, lockPath: string}} The installation result.
  */
 export function applySkillInstall({ packageVersion, bundle, plan, operations = {} }) {
   const resolvedOperations = { ...defaultOperations, ...operations };
   if (plan.action === "no-op") return installResult("no-op", bundle, plan);
 
   const touched = [];
-  const originalCanonical =
-    plan.writeCanonical && pathState(plan.paths.canonical, resolvedOperations).type === "file"
-      ? resolvedOperations.readFileSync(plan.paths.canonical)
-      : null;
-  let canonicalWritten = false;
+  const originalBundle = plan.writeBundle ? snapshotDirectory(plan.paths.canonicalDirectory, resolvedOperations) : null;
+  let bundleWritten = false;
   const materializedAdapters = [];
 
   try {
-    if (plan.writeCanonical) {
-      atomicWrite(plan.paths.canonical, bundle.bytes, resolvedOperations, touched);
-      canonicalWritten = true;
+    if (plan.writeBundle) {
+      bundleWritten = true;
+      for (const file of bundle.files) {
+        atomicWrite(path.join(plan.paths.canonicalDirectory, file.path), file.bytes, resolvedOperations, touched);
+      }
+      for (const relativePath of plan.staleFiles ?? []) {
+        const stalePath = path.join(plan.paths.canonicalDirectory, relativePath);
+        touched.push(stalePath);
+        resolvedOperations.rmSync(stalePath, { force: true });
+      }
     }
     for (const adapter of plan.adaptersToMaterialize) {
       adapter.materialize({
@@ -252,8 +278,8 @@ export function applySkillInstall({ packageVersion, bundle, plan, operations = {
   } catch (error) {
     const recoveryFailures = restoreAfterFailure({
       plan,
-      originalCanonical,
-      canonicalWritten,
+      originalBundle,
+      bundleWritten,
       materializedAdapters,
       operations: resolvedOperations,
       touched,
@@ -267,19 +293,21 @@ export function applySkillInstall({ packageVersion, bundle, plan, operations = {
 function installResult(action, bundle, plan) {
   return {
     action,
-    skillSha256: bundle.sha256,
+    skillSha256: bundle.skillSha256,
+    bundleSha256: bundle.bundleSha256,
     canonicalPath: toPosixPath(plan.topology.canonicalRelativePath),
     lockPath: toPosixPath(lockRelativePath),
   };
 }
 
-function createPlan({ paths, adapters, writeCanonical }) {
+function createPlan({ paths, adapters, writeBundle }) {
   return {
     action: "create",
     paths,
     topology: paths.topology,
     adaptersToMaterialize: adapters.filter(({ state }) => state === "absent").map(({ adapter }) => adapter),
-    writeCanonical,
+    writeBundle,
+    staleFiles: [],
   };
 }
 
@@ -358,23 +386,39 @@ function selectTopology({ root, lockState, operations }) {
 function isValidLock(lock, skillName, topology) {
   return (
     lock &&
-    lock.schemaVersion === lockSchemaVersion &&
+    [1, lockSchemaVersion].includes(lock.schemaVersion) &&
     lock.skill === skillName &&
     typeof lock.ddduckVersion === "string" &&
     lock.ddduckVersion.length > 0 &&
     toPosixPath(lock.canonicalPath) === toPosixPath(topology.canonicalRelativePath) &&
     /^[a-f0-9]{64}$/.test(lock.skillSha256) &&
+    (lock.schemaVersion === 1 || isValidBundleLock(lock)) &&
     JSON.stringify(lock.adapters) === JSON.stringify(expectedAdapters(topology))
   );
 }
 
 function createLock({ packageVersion, bundle, topology }) {
+  if (bundle.files.length === 1) {
+    return {
+      schemaVersion: 1,
+      skill: bundle.name,
+      ddduckVersion: packageVersion,
+      canonicalPath: toPosixPath(topology.canonicalRelativePath),
+      skillSha256: bundle.skillSha256,
+      adapters: expectedAdapters(topology),
+    };
+  }
   return {
     schemaVersion: lockSchemaVersion,
     skill: bundle.name,
     ddduckVersion: packageVersion,
     canonicalPath: toPosixPath(topology.canonicalRelativePath),
-    skillSha256: bundle.sha256,
+    skillSha256: bundle.skillSha256,
+    bundleSha256: bundle.bundleSha256,
+    files: bundle.files.map(({ path: relativePath, sha256: fileSha256 }) => ({
+      path: relativePath,
+      sha256: fileSha256,
+    })),
     adapters: expectedAdapters(topology),
   };
 }
@@ -412,7 +456,7 @@ function atomicWrite(destination, content, operations, touched) {
   }
 }
 
-function restoreAfterFailure({ plan, originalCanonical, canonicalWritten, materializedAdapters, operations, touched }) {
+function restoreAfterFailure({ plan, originalBundle, bundleWritten, materializedAdapters, operations, touched }) {
   const failures = [];
   for (const adapter of materializedAdapters.toReversed()) {
     try {
@@ -425,17 +469,16 @@ function restoreAfterFailure({ plan, originalCanonical, canonicalWritten, materi
       failures.push(`remove ${adapter.host} adapter: ${error.message}`);
     }
   }
-  if (!canonicalWritten) return failures;
+  if (!bundleWritten && originalBundle === null) return failures;
 
   try {
-    if (originalCanonical) {
-      atomicWrite(plan.paths.canonical, originalCanonical, operations, touched);
-    } else {
-      touched.push(plan.paths.canonical);
-      operations.rmSync(plan.paths.canonical, { force: true });
+    touched.push(plan.paths.canonicalDirectory);
+    operations.rmSync(plan.paths.canonicalDirectory, { recursive: true, force: true });
+    for (const file of originalBundle ?? []) {
+      atomicWrite(path.join(plan.paths.canonicalDirectory, file.path), file.bytes, operations, touched);
     }
   } catch (error) {
-    failures.push(`restore canonical skill: ${error.message}`);
+    failures.push(`restore canonical skill bundle: ${error.message}`);
   }
   return failures;
 }
@@ -454,6 +497,98 @@ function locallyModifiedCanonical(canonicalPath) {
   return error;
 }
 
+function locallyModifiedBundle(bundlePath) {
+  const error = new Error(`Locally modified canonical skill bundle: ${bundlePath}`);
+  error.nextAction = `Revert or remove ${bundlePath}, then re-run ddduck install skill update-ddduck-specs.`;
+  return error;
+}
+
+function readBundleFiles(directory, operations, relativeDirectory = "") {
+  const current = path.join(directory, relativeDirectory);
+  const files = [];
+  const entries = operations
+    .readdirSync(current, { withFileTypes: true })
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  for (const entry of entries) {
+    const relativePath = path.join(relativeDirectory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...readBundleFiles(directory, operations, relativePath));
+      continue;
+    }
+    if (!entry.isFile()) throw new Error(`Unsupported bundled skill entry: ${path.join(directory, relativePath)}`);
+    const bytes = operations.readFileSync(path.join(directory, relativePath));
+    files.push({ path: toPosixPath(relativePath), bytes, sha256: sha256(bytes) });
+  }
+  return files;
+}
+
+function digestBundle(files) {
+  const digest = createHash("sha256");
+  for (const file of files) {
+    digest.update(`${file.path.length}:${file.path}:${file.bytes.length}:`);
+    digest.update(file.bytes);
+  }
+  return digest.digest("hex");
+}
+
+function isValidBundleLock(lock) {
+  return (
+    /^[a-f0-9]{64}$/.test(lock.bundleSha256) &&
+    Array.isArray(lock.files) &&
+    lock.files.length > 0 &&
+    lock.files.every(
+      (file) =>
+        file &&
+        typeof file.path === "string" &&
+        file.path.length > 0 &&
+        !path.isAbsolute(file.path) &&
+        !file.path.split("/").includes("..") &&
+        /^[a-f0-9]{64}$/.test(file.sha256),
+    )
+  );
+}
+
+function assertInstalledBundleMatchesLock(paths, lock, operations) {
+  if (lock.schemaVersion === 1) {
+    if (sha256(operations.readFileSync(paths.canonical)) !== lock.skillSha256) {
+      throw locallyModifiedCanonical(paths.canonical);
+    }
+    const entries = snapshotDirectory(paths.canonicalDirectory, operations) ?? [];
+    if (entries.some(({ path: relativePath }) => relativePath !== skillFileName)) {
+      throw locallyModifiedBundle(paths.canonicalDirectory);
+    }
+    return;
+  }
+
+  const installed = snapshotDirectory(paths.canonicalDirectory, operations) ?? [];
+  const expectedPaths = lock.files.map(({ path: relativePath }) => relativePath);
+  if (
+    JSON.stringify(installed.map(({ path: relativePath }) => relativePath)) !== JSON.stringify(expectedPaths) ||
+    installed.some((file, index) => file.sha256 !== lock.files[index].sha256)
+  ) {
+    throw locallyModifiedBundle(paths.canonicalDirectory);
+  }
+}
+
+function assertRemainingBundleMatchesLock(paths, lock, operations) {
+  const installed = snapshotDirectory(paths.canonicalDirectory, operations) ?? [];
+  const expected = new Map(
+    lock.schemaVersion === 1
+      ? [[skillFileName, lock.skillSha256]]
+      : lock.files.map(({ path: relativePath, sha256: fileSha256 }) => [relativePath, fileSha256]),
+  );
+  if (installed.some((file) => expected.get(file.path) !== file.sha256)) {
+    throw locallyModifiedBundle(paths.canonicalDirectory);
+  }
+}
+
+function snapshotDirectory(directory, operations) {
+  const state = pathState(directory, operations);
+  if (state.type === "absent") return null;
+  if (state.type !== "directory") throw locallyModifiedBundle(directory);
+  return readBundleFiles(directory, operations);
+}
+
 function sha256(bytes) {
   return createHash("sha256").update(bytes).digest("hex");
 }