ddduck 0.1.2 → 0.3.0

package/scripts/ddduck.mjs

@@ -2,8 +2,8 @@
 
 /**
  * Entry point for the `ddduck` CLI (the package bin). Dispatches the commands
- * init, check, generate, query, install, and the guarantee lifecycle commands
- * create/move/split/retire. Mutations run through the locked, staged operation
+ * init, check, generate, query, install, --version, and the guarantee lifecycle
+ * commands create/move/split/retire. Mutations run through the locked, staged operation
  * runner in lib/product-operation.mjs; init publishes a fresh product root via
  * PID-stamped staging; check delegates to check-model.mjs plus the generated
  * freshness gates. Errors leave through writeCliError with a Next: action line.
@@ -41,12 +41,29 @@ import {
 import { resolveContainedOutput } from "./lib/product-paths.mjs";
 import { initStagingPrefix, resolveInitDestination, resolveProductRoot } from "./lib/product-root-resolver.mjs";
 import { defaultConfigIgnore, findRepositoryRoot, loadDdduckConfig } from "./lib/ddduck-config.mjs";
-import { installSkill } from "./lib/skill-installer.mjs";
+import { delegateSkillInstall } from "./lib/skill-delegation.mjs";
 import { runQuery } from "./query-model.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
+import { buildAuthoringPlan } from "./lib/product-authoring.mjs";
+import { parseYamlMapping } from "./lib/product-layout.mjs";
+import { compareProductRoots, renderProductDiff } from "./lib/product-diff.mjs";
 
 const frameworkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
+const topLevelCommands = [
+  "init",
+  "check",
+  "generate",
+  "query",
+  "diff",
+  "install",
+  "create",
+  "move",
+  "split",
+  "retire",
+  "--version",
+];
+
 const cliArgs = process.argv.slice(2);
 
 try {
@@ -65,17 +82,21 @@ function run(args) {
     process.stdout.write(renderHelp());
     return;
   }
-  const [command, ...commandArgs] = args;
-  if (
-    !command ||
-    !["init", "check", "generate", "query", "install", "create", "move", "split", "retire"].includes(command)
-  ) {
+  const [rawCommand, ...commandArgs] = args;
+  // -v is the only short alias in the contract; normalizing it here keeps the
+  // help lookup, the dispatch, and the error next action on one command name.
+  const command = rawCommand === "-v" ? "--version" : rawCommand;
+  if (!command || !topLevelCommands.includes(command)) {
     throw new CliUsageError(`Unknown command ${command ?? "(missing)"}`);
   }
   if (commandArgs.includes("--help")) {
     process.stdout.write(renderHelp(command));
     return;
   }
+  if (command === "--version") {
+    reportVersion(commandArgs);
+    return;
+  }
   if (command === "init") {
     const { result, json } = initialize(commandArgs);
     writeProductOperationResult(result, json);
@@ -93,10 +114,24 @@ function run(args) {
     runQuery(commandArgs);
     return;
   }
+  if (command === "diff") {
+    const { options } = parseCommandArgs(commandArgs, {
+      options: { base: { value: true }, root: { value: true }, json: { value: false } },
+    });
+    const base = requiredOption(options, "base", "diff requires --base <previous-product-root>");
+    const root = resolveProductRoot({ explicitRoot: options.root });
+    const report = compareProductRoots(path.resolve(base), root);
+    process.stdout.write(`${options.json ? JSON.stringify(report) : renderProductDiff(report)}\n`);
+    return;
+  }
   if (command === "install") {
     install(commandArgs);
     return;
   }
+  if (command === "create" && ["domain", "concept", "use-case"].includes(commandArgs[0])) {
+    createNode(commandArgs);
+    return;
+  }
   if (["create", "move", "split", "retire"].includes(command)) {
     transitionGuarantee(command, commandArgs);
     return;
@@ -104,39 +139,53 @@ function run(args) {
 }
 
 /**
- * Implement `ddduck install skill update-ddduck-specs`: install the bundled
- * host skill adapter and .ddduck/agent-skills.lock.json into --repo.
+ * Implement `ddduck --version` (alias `-v`): print the installed package name
+ * and version from the package's own manifest. It reads no product, so it also
+ * serves as the probe that confirms a candidate executable really is ddduck.
+ * @param {string[]} args - Arguments after the version flag.
+ * @returns {void}
+ */
+function reportVersion(args) {
+  const { options } = parseCommandArgs(args, { options: { json: { value: false } } });
+  const { name, version } = readPackageManifest();
+  process.stdout.write(options.json ? `${JSON.stringify({ name, version })}\n` : `${name} ${version}\n`);
+}
+
+function readPackageManifest() {
+  return JSON.parse(readFileSync(path.join(frameworkRoot, "package.json"), "utf8"));
+}
+
+/**
+ * Implement `ddduck install skill`: print the `npx skills add` command for the
+ * bundled skills directory, confirm it unless --yes was passed, run it in
+ * --repo, and propagate its exit status. ddduck installs nothing itself.
  * @param {string[]} args - Arguments after the `install` command word.
  * @returns {void}
  */
 function install(args) {
   const { positionals, options } = parseCommandArgs(args, {
-    positionals: { min: 2, max: 2 },
-    options: { repo: { value: true } },
+    positionals: { min: 1, max: 1, syntax: "ddduck install skill [--repo <repository-root>] [--yes]" },
+    options: { repo: { value: true }, yes: { value: false } },
   });
-  const [kind, skillName] = positionals;
-  if (kind !== "skill" || skillName !== "update-ddduck-specs") {
-    throw new CliUsageError("install requires skill update-ddduck-specs");
+  if (positionals[0] !== "skill") {
+    throw new CliUsageError(`install requires the subject skill, not ${JSON.stringify(positionals[0])}`);
   }
-  const packageVersion = JSON.parse(readFileSync(path.join(frameworkRoot, "package.json"), "utf8")).version;
   const repository = path.resolve(options.repo ?? process.cwd());
-  // A typo'd --repo must fail instead of silently manufacturing a directory
-  // tree (and a lock) at the wrong path while the real repository gets nothing.
+  // A typo'd --repo must fail instead of installing into the wrong directory
+  // (npx would happily create it) while the real repository gets nothing.
   if (!existsSync(repository) || !statSync(repository).isDirectory()) {
     throw new CliUsageError(`install requires an existing repository directory: ${repository}`, {
       nextAction: "Pass --repo <existing-repository-root> and retry.",
     });
   }
-  const result = installSkill({
-    repository,
-    skillName,
-    skillPath: path.join(frameworkRoot, "skills", skillName, "SKILL.md"),
-    packageVersion,
-  });
-  const actionLabels = { create: "created", upgrade: "upgraded", "no-op": "no-op" };
-  process.stdout.write(
-    `install skill ${skillName} (${actionLabels[result.action]}) in ${repository}; canonical: ${result.canonicalPath}; lock: ${result.lockPath}\n`,
-  );
+  const skillsDirectory = path.join(frameworkRoot, "skills");
+  if (!existsSync(skillsDirectory) || !statSync(skillsDirectory).isDirectory()) {
+    const error = new Error(`Missing bundled skills directory: ${skillsDirectory}`);
+    error.nextAction = "Reinstall ddduck so the packaged skills are present, then retry.";
+    throw error;
+  }
+  const { status } = delegateSkillInstall({ skillsDirectory, repository, assumeYes: options.yes });
+  if (status !== 0) process.exitCode = status;
 }
 
 /**
@@ -358,6 +407,38 @@ function generate(args) {
   writeProductOperationResult(result, options.json);
 }
 
+function createNode(args) {
+  const kind = args[0];
+  const shared = { root: { value: true }, json: { value: false } };
+  const fields =
+    kind === "use-case"
+      ? { file: { value: true } }
+      : {
+          id: { value: true },
+          name: { value: true },
+          purpose: { value: true },
+          ...(kind === "concept" ? { owner: { value: true } } : {}),
+        };
+  const { options } = parseCommandArgs(args, {
+    positionals: { min: 1, max: 1 },
+    options: { ...shared, ...fields },
+  });
+  const required = (field) => requiredOption(options, field, `create ${kind} requires --${field} <value>`);
+  const request =
+    kind === "use-case"
+      ? { kind: "UseCase", node: parseYamlMapping(path.resolve(required("file"))) }
+      : {
+          kind: kind === "domain" ? "Domain" : "Concept",
+          id: required("id"),
+          name: required("name"),
+          purpose: required("purpose"),
+          ...(kind === "concept" ? { ownerDomain: required("owner") } : {}),
+        };
+  const root = resolveProductRoot({ explicitRoot: options.root });
+  const result = runProductOperation({ root, transform: (snapshot) => buildAuthoringPlan(snapshot, request) });
+  writeProductOperationResult(result, options.json);
+}
+
 /**
  * Implement the guarantee lifecycle commands create, move, split, and retire:
  * parse per-command options, require a registered decision for split/retire,
@@ -679,8 +760,8 @@ function writeConfigIfAbsent(destination) {
 }
 
 function nextActionFor(args) {
-  const command = args[0];
-  if (["init", "check", "generate", "query", "install", "create", "move", "split", "retire"].includes(command)) {
+  const command = args[0] === "-v" ? "--version" : args[0];
+  if (topLevelCommands.includes(command)) {
     return `Run ddduck ${command} --help, correct the input, and retry.`;
   }
   return "Run ddduck --help, choose a command, and retry.";

package/scripts/generate-docs.mjs

@@ -137,7 +137,7 @@ function renderModelOverview(view) {
   lines.push("## Decisions", "");
   for (const decision of view.decisions) lines.push(`- \`${decision}\``);
   lines.push("");
-  return lines.join("\n");
+  return `${lines.join("\n").trimEnd()}\n`;
 }
 
 function renderNodeList(lines, title, nodes) {

package/scripts/lib/cli-contract.mjs

@@ -82,9 +82,18 @@ 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.",
+      "Flags: --version (-v) prints the installed ddduck version.",
       "Run `ddduck <command> --help` for command usage.",
     ],
+    "--version": [
+      "Syntax: ddduck --version [--json]   (alias: ddduck -v)",
+      "Defaults: text output; no product root is resolved and no product is read.",
+      "Writes: nothing.",
+      "Success output: one text line naming the package and its installed version.",
+      "Exit status: 0 on success or help; 1 on invalid input.",
+      "JSON: --json emits one object with name and version.",
+    ],
     init: [
       "Syntax: ddduck init [destination] --id model:<product-id> [--json]",
       "Defaults: destination is the productRoot configured in .ddduck/config.json, else ddd.",
@@ -118,19 +127,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.",
-      "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.",
+      "Syntax: ddduck install skill [--repo <repository-root>] [--yes]",
+      "Defaults: --repo is the current directory; the confirmation prompt is asked unless --yes is passed.",
+      "Writes: nothing directly; it runs `npx --yes '--package=skills@^1.7.0' -- skills add <ddduck>/skills --skill '*' -y` in --repo, and the skills CLI installs every bundled skill into that project (canonical copy plus per-agent symlinks) and owns its own state.",
+      "Success output: the exact delegated command on its own line, the confirmation prompt, then the streamed output of the delegated command.",
+      "Exit status: 0 on a successful delegated install or help; 1 when the confirmation is declined (nothing installed), when input is invalid, or when npx cannot be started; otherwise the exit status of the delegated command.",
       "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-delegation.mjs

@@ -0,0 +1,129 @@
+/**
+ * Delegation for `ddduck install skill`. ddduck installs nothing itself: it
+ * builds the `npx skills add` command for the bundled skills directory, prints
+ * that command verbatim, confirms it on standard input unless --yes was
+ * passed, then runs it as a child process whose output streams through and
+ * whose exit status is propagated. The `skills` CLI owns the host topology
+ * (canonical copy plus per-agent symlinks) and its own installation state.
+ */
+
+import { Buffer } from "node:buffer";
+import { spawnSync } from "node:child_process";
+import { readSync } from "node:fs";
+import { shellQuote } from "./context-pack.mjs";
+
+const defaultOperations = { spawnSync, readAnswer };
+
+/** The delegated CLI, pinned so npx resolves it from the registry. */
+export const skillsPackageSpecifier = "skills@^1.7.0";
+
+/**
+ * Build the delegated command: every bundled skill, project scope, and no
+ * second confirmation inside the child (ddduck already confirmed the printed
+ * command). `npx --yes` keeps an uncached `skills` from prompting to install.
+ * `--package=` is load-bearing: a bare command name resolves against the
+ * target repository's node_modules/.bin first, so an unrelated `skills` binary
+ * hoisted there (a generic name in a monorepo) would run instead of the CLI
+ * the printed command names. The `--` separator keeps npx from reading the
+ * command word as another package specifier.
+ * @param {string} skillsDirectory - Absolute path of the bundled skills directory.
+ * @returns {{command: string, args: string[]}} The command and its argument vector.
+ */
+export function buildSkillsAddCommand(skillsDirectory) {
+  return {
+    command: "npx",
+    args: [
+      "--yes",
+      `--package=${skillsPackageSpecifier}`,
+      "--",
+      "skills",
+      "add",
+      skillsDirectory,
+      "--skill",
+      "*",
+      "-y",
+    ],
+  };
+}
+
+/**
+ * Render the delegated command as one copy-pasteable shell line.
+ * @param {string} skillsDirectory - Absolute path of the bundled skills directory.
+ * @returns {string} The command line, shell-quoted where needed.
+ */
+export function renderSkillsAddCommand(skillsDirectory) {
+  const { command, args } = buildSkillsAddCommand(skillsDirectory);
+  return [command, ...args].map(shellQuote).join(" ");
+}
+
+/**
+ * Print the delegated command, confirm it unless --yes was passed, and run it
+ * in the target repository.
+ * @param {{skillsDirectory: string, repository: string, assumeYes?: boolean, stdout?: {write: (chunk: string) => unknown}, operations?: {spawnSync?: Function, readAnswer?: Function}}} options - Bundled skills directory, repository to install into, confirmation bypass, output stream, and child-process/stdin overrides for tests.
+ * @returns {{status: number}} The delegated command's exit status (1 when it was killed by a signal).
+ */
+export function delegateSkillInstall({
+  skillsDirectory,
+  repository,
+  assumeYes = false,
+  stdout = process.stdout,
+  operations = {},
+}) {
+  const resolvedOperations = { ...defaultOperations, ...operations };
+  const { command, args } = buildSkillsAddCommand(skillsDirectory);
+
+  stdout.write(`install skill delegates to the skills CLI; ddduck runs this command in ${repository}:\n`);
+  stdout.write(`${renderSkillsAddCommand(skillsDirectory)}\n`);
+  if (!assumeYes) {
+    stdout.write("Run it? [y/n] ");
+    const answer = resolvedOperations.readAnswer();
+    if (answer !== "y" && answer !== "Y") throw declinedConfirmation();
+  }
+
+  const result = resolvedOperations.spawnSync(command, args, { cwd: repository, stdio: "inherit" });
+  if (result.error) {
+    const error = new Error(`Failed to run the skills CLI via npx: ${result.error.message}`);
+    error.nextAction = "Make sure npx (Node.js) is on PATH, then re-run the printed command yourself.";
+    throw error;
+  }
+  // A signal-killed child reports a null status; the CLI still has to exit
+  // nonzero, because nothing was necessarily installed.
+  return { status: Number.isInteger(result.status) ? result.status : 1 };
+}
+
+// A declined confirmation is neither an input error nor a host-state error:
+// nothing was touched, and the only two ways forward are the flag or the
+// printed command.
+function declinedConfirmation() {
+  const error = new Error("install skill declined at the confirmation prompt; nothing was installed");
+  error.nextAction = "Re-run with --yes to skip the confirmation, or run the printed command yourself.";
+  return error;
+}
+
+/**
+ * Read one answer line from standard input synchronously, one byte at a time,
+ * so the prompt works on a terminal without switching the synchronous CLI to
+ * an asynchronous readline. A closed or exhausted stdin yields an empty
+ * answer, which declines.
+ * @returns {string} The trimmed answer (empty at end of input).
+ */
+function readAnswer() {
+  const buffer = Buffer.alloc(1);
+  let answer = "";
+  for (;;) {
+    let bytesRead;
+    try {
+      bytesRead = readSync(0, buffer, 0, 1, null);
+    } catch (error) {
+      // A non-blocking terminal has nothing to give yet; EOF ends the answer.
+      if (error.code === "EAGAIN") continue;
+      if (error.code === "EOF") break;
+      throw error;
+    }
+    if (bytesRead === 0) break;
+    const character = buffer.toString("utf8");
+    if (character === "\n" || character === "\r") break;
+    answer += character;
+  }
+  return answer.trim();
+}