ddduck 0.2.0 → 0.3.0

package/README.md

@@ -91,11 +91,16 @@ safety net.
 Install the evidence-backed model maintenance skill in a consumer repository:
 
 ```bash
-ddduck install skill update-ddduck-specs --repo <repository-root>
+ddduck install skill --repo <repository-root>
 ```
 
-`--repo` defaults to the current directory. See [the CLI reference](docs/cli.md#install-an-agent-skill)
-for the installed layout, host invocation, and plan-only behavior.
+`--repo` defaults to the current directory. ddduck installs nothing itself: it prints the exact
+`npx --yes '--package=skills@^1.7.0' -- skills add <ddduck-package>/skills --skill '*' -y`
+command it will run, asks `[y/n]`, and
+delegates the installation to the [`skills`](https://www.npmjs.com/package/skills) CLI, which
+supports 79 agent hosts. Pass `--yes` to skip the confirmation in CI or when an agent runs the
+command. See [the CLI reference](docs/cli.md#install-an-agent-skill) for the delegated flags,
+exit statuses, host invocation, and plan-only behavior.
 
 ## Product queries
 

package/docs/cli.md

@@ -14,6 +14,25 @@ retry logic never has to string-match standard error; every other failure exits
 This package is published to npm as `ddduck`; install the CLI globally with `npm install -g ddduck`
 (see [the getting-started guide](getting-started.md#install-ddduck)).
 
+## `--version`
+
+```text
+ddduck --version [--json]
+ddduck -v [--json]
+```
+
+| Option   | Default | Meaning                                        |
+| -------- | ------- | ---------------------------------------------- |
+| `--json` | false   | Emit one JSON object instead of the text line. |
+
+`--version` (alias `-v`) prints the installed package name and version taken from the package's
+own `package.json`, as one text line — `ddduck <version>` — or, with `--json`, one object:
+`{"name":"ddduck","version":"<version>"}`. It resolves no product root and reads no product, so
+it is the cheapest way to confirm that a candidate executable really is ddduck and which version
+is installed. `ddduck --version --help` prints the flag's contract like every other command.
+Exit status: 0 on success or help; 1 on invalid input (an unknown option, for example). The
+retryable busy exit 2 cannot occur, because no product root is touched.
+
 ## Product root resolution
 
 Product-facing commands accept `--root <product-root>`. When `--root` is omitted, ddduck resolves
@@ -286,28 +305,37 @@ The command does not recursively expand the perimeter.
 ## Install an agent skill
 
 ```text
-ddduck install skill update-ddduck-specs [--repo <repository-root>]
+ddduck install skill [--repo <repository-root>] [--yes]
 ```
 
-`--repo` defaults to the current directory. The installer chooses the least intrusive host
-topology from the repository's existing directories:
+`--repo` defaults to the current directory. ddduck installs nothing itself: it delegates to the
+[`skills`](https://www.npmjs.com/package/skills) CLI, which supports 79 agent hosts and owns the
+installed layout and its own state. The command prints the exact command it will run, on its own
+line, and then runs it in `--repo`:
 
 ```text
-no .agents/ or .claude/   -> .agents/skills/update-ddduck-specs/SKILL.md
-.agents/ only             -> .agents/skills/update-ddduck-specs/SKILL.md
-.claude/ only             -> .claude/skills/update-ddduck-specs/SKILL.md
-.agents/ and .claude/     -> .agents/skills/update-ddduck-specs/SKILL.md
-                             .claude/skills/update-ddduck-specs -> ../../.agents/skills/update-ddduck-specs
+npx --yes '--package=skills@^1.7.0' -- skills add <ddduck-package>/skills --skill '*' -y
 ```
 
-The installer writes `.ddduck/agent-skills.lock.json` with the selected canonical path, host
-adapters, package version, installed file manifest, `SKILL.md` SHA-256, and whole-bundle SHA-256.
-It installs `SKILL.md` and its bundled `references/` directory, refuses locally modified managed
-files, and upgrades legacy single-file locks without overwriting extra local files. It does not
-create a host directory for a host that is absent from the repository, except for the `.agents/`
-fallback when no host directory exists. On success it prints one result line naming the action
-(`created`, `upgraded`, or `no-op`), the repository, the canonical skill path, and the lock path. It does not accept
-`--json`.
+The bundled skills directory is resolved inside the installed ddduck package
+(`./node_modules/ddduck/skills` from a consumer repository, or the repository's own `skills/`
+when the repository under analysis is ddduck itself). `--skill '*'` installs every bundled skill,
+the absent `-g` keeps the install project-scoped, and `-y` answers the delegated CLI's own
+prompts, because the command it applies has already been shown and confirmed here. `skills`
+writes one canonical copy (by default `.agents/skills/<skill-name>/`) and symlinks it into the
+agent directories that exist in the project.
+
+`--package=` pins the delegated package so npx resolves it from the registry. Without it, npx
+resolves the bare name `skills` against `--repo`'s own `node_modules/.bin` first, so an unrelated
+binary under that generic name — a sibling package hoisted to a monorepo root, for example —
+would run instead of the CLI the printed command names. The `--` separator keeps npx from
+reading the command word as a second package specifier.
+
+Before running it, ddduck asks `[y/n]` on standard input. Only `y` or `Y` proceeds; any other
+answer — including an empty line and a closed standard input — aborts, installs nothing, and
+exits 1. `--yes` skips that confirmation and keeps the command usable in CI and by agents; the
+command is still printed. The delegated command's output streams through unchanged and its exit
+status is propagated. `--json` is not accepted.
 
 Invoke the skill from the relevant host:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ddduck",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An opinionated DDD framework for authoring, validating, and visualizing machine-readable product-spec models.",
   "keywords": [
     "ddd",

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,7 +41,7 @@ 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";
@@ -50,6 +50,20 @@ 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 {
@@ -68,17 +82,21 @@ function run(args) {
     process.stdout.write(renderHelp());
     return;
   }
-  const [command, ...commandArgs] = args;
-  if (
-    !command ||
-    !["init", "check", "generate", "query", "diff", "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);
@@ -121,39 +139,53 @@ function run(args) {
 }
 
 /**
- * Implement `ddduck install skill update-ddduck-specs`: install the bundled
- * host skill bundle 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;
 }
 
 /**
@@ -728,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/lib/cli-contract.mjs

@@ -83,8 +83,17 @@ export function renderHelp(command) {
     undefined: [
       "Usage: ddduck <command> [options]",
       "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.",
@@ -127,11 +136,11 @@ export function renderHelp(command) {
       "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 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.",
+      "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: [

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();
+}

package/skills/update-ddduck-specs/SKILL.md

@@ -10,7 +10,7 @@ Maintain or bootstrap a ddduck product model from evidence in the current workin
 ## Operating contract
 
 - Resolve the repository root, read every applicable instruction file, and inspect Git status before analysis.
-- Use the repository-compatible ddduck executable. Do not install dependencies or substitute an unrelated global version.
+- Resolve a repository-compatible ddduck executable with the probe order in [executable resolution](references/executable-resolution.md). Do not install dependencies or substitute an unrelated global version.
 - Default to plan-only. Mutate model files only when the current request explicitly authorizes applying the evidence-backed proposal.
 - Preserve unrelated work. Stop when intended model edits overlap user changes inseparably or the analyzed tree changes before application.
 - Write only `<root>/product.yaml`, `<root>/model/**`, `<root>/decisions/**`, and regenerated `<root>/generated/**`. Regenerate derived views; never edit them directly.
@@ -22,13 +22,14 @@ Maintain or bootstrap a ddduck product model from evidence in the current workin
 
 Read each selected reference completely before acting. All references are one level below this file.
 
+- Before the first ddduck command, read [executable resolution](references/executable-resolution.md).
 - For every bootstrap, audit, or reconciliation, read [modeling and evidence](references/modeling-and-evidence.md).
 - When comparing revisions, reviewing moves/removals, or selecting affected context, read [reviewing changes](references/reviewing-changes.md). Start with `ddduck diff --base <before-root> --root <after-root> --json` when two valid roots exist.
 - Before proposing or applying canonical changes, read [authoring and verification](references/authoring-and-verification.md). Use `ddduck create domain`, `ddduck create concept`, and `ddduck create use-case` for the kinds they support.
 
 ## Workflow
 
-1. Resolve and classify the product root. Record `query spec` and `check` independently; an invalid existing model is not an absent model.
+1. Resolve the executable, then resolve and classify the product root. Record `query spec` and `check` independently; an invalid existing model is not an absent model, and a root that was never inspected is `undetermined`, never absent.
 2. Gather current code, tests, interfaces, documentation, configuration, schemas, and accepted decisions. Record contradictions, exclusions, and coverage gaps.
 3. Separate observed behavior, accepted intent, open questions, and rejected alternatives. Classify every material model difference using the modeling reference.
 4. Produce the plan-only report defined in the authoring reference. A partial or zero-model-change result is valid when it is the evidence-backed outcome.

package/skills/update-ddduck-specs/references/authoring-and-verification.md

@@ -4,15 +4,17 @@ Read this reference before proposing or applying canonical ddduck changes.
 
 ## Resolve and classify once
 
-Use an explicitly requested root. Otherwise let ddduck resolve the enclosing product root, then `.ddduck/config.json`, then the unique repository candidate. `ddduck query spec --root <root> --json` reports the resolved root. Ambiguity is a stop condition: report candidates and ask rather than initializing a second model.
+Root resolution is delegated to the executable, so resolve one first with the probe order in [executable resolution](executable-resolution.md). Every `ddduck …` command in this file names that resolved command; substitute it before running. Then use an explicitly requested root. Otherwise let ddduck resolve the enclosing product root, then `.ddduck/config.json`, then the unique repository candidate. `ddduck query spec --root <root> --json` reports the resolved root. Ambiguity is a stop condition: report candidates and ask rather than initializing a second model.
 
-Classify the selected path:
+Classify the selected path. These three states are observations; each requires an inspection that actually ran.
 
 - `existing`: `product.yaml` exists. Run `query spec` and `check` independently. A failing model remains existing and invalid.
 - `absent`: the root is missing or empty. Inspect the repository before proposing initialization.
 - `path-collision`: the path is non-empty but is not a recognizable product. Report it and do not initialize over it.
 
-Stop before mutation when the executable is missing or incompatible, the root is ambiguous, the path collides, bootstrap identity or seams are ungrounded, evidence conflicts change the proposal materially, target files overlap inseparable user work, or the analyzed working tree changed.
+When no executable resolves, or the inspection that distinguishes those states did not complete, the state is `undetermined`: the absence of an observation rather than a fourth thing observed. Report `undetermined` and stop; never downgrade it to `absent`, because `absent` is the only state that authorizes initialization.
+
+Stop before mutation when the executable is unresolved, missing, or incompatible, the model state is `undetermined`, the root is ambiguous, the path collides, bootstrap identity or seams are ungrounded, evidence conflicts change the proposal materially, target files overlap inseparable user work, or the analyzed working tree changed.
 
 ## Plan-only report
 

package/skills/update-ddduck-specs/references/executable-resolution.md

@@ -0,0 +1,39 @@
+# Executable resolution
+
+Read this reference before running any ddduck command. Root classification, baselines, and verification results are only as trustworthy as the executable that produced them, so resolving one is a precondition for the workflow rather than a step inside it.
+
+## Probe in order
+
+Take the first candidate that runs. Confirm a candidate by appending `--version` to that candidate's own command, never by running a different one: `node_modules/.bin/ddduck --version` for probe 2, `node scripts/ddduck.mjs --version` for probe 3, and the bare `ddduck --version` only when `ddduck` on `PATH` is itself the candidate being probed. A working repository-local candidate must not be rejected because `ddduck` is absent from `PATH`. The command prints `ddduck <version>`; read the resolved version from that output.
+
+1. A command or path supplied in the current request.
+2. `node_modules/.bin/ddduck` at the repository root, then at any enclosing workspace root.
+3. `node scripts/ddduck.mjs`, the repository's own `package.json` `bin` target, when the repository under analysis is ddduck itself.
+4. `ddduck` on `PATH`.
+5. A ddduck source checkout that the user named or that the repository records, only when its reported version matches the version the repository pins: a `ddduck` dependency in `package.json`, or `ddduckVersion` in `.ddduck/agent-skills.lock.json`.
+
+Do not install dependencies and do not substitute an unrelated global version. A candidate that fails to run, or that reports a version incompatible with the pinned one, is not a resolution; continue with the next probe.
+
+Record which probe resolved, the exact command, and its reported version. Reuse that one command for every subsequent ddduck invocation.
+
+Every `ddduck <subcommand>` form written in this skill and its references names the resolved command, not the literal `ddduck` on `PATH`. Substitute the resolved command before running any of them: with probe 3 resolved, `ddduck check --root <root>` is run as `node scripts/ddduck.mjs check --root <root>`.
+
+## Named paths only, never scan
+
+Probe only the paths listed above plus the paths the request or the repository explicitly names. Never search parent directories or the wider filesystem for a checkout. An unbounded search exhausts the available budget, times out, and still resolves nothing.
+
+## An unresolved executable is `undetermined`
+
+`existing`, `absent`, and `path-collision` are observations, and each one requires an inspection that actually ran. When no probe resolves, that inspection never ran and the model state is `undetermined`.
+
+Report `undetermined`, stop before any mutation, and never downgrade it to `absent`. Only `absent` authorizes initialization, and initializing on an unverified `absent` bootstraps a second product root beside a healthy one. A named `productRoot` in `.ddduck/config.json`, or an existing `product.yaml`, is evidence against `absent` even while the executable remains unresolved.
+
+## Remediation
+
+When no probe resolves, report every probe attempted and its outcome, then present these options and let the user choose:
+
+- `npm i -g ddduck`
+- `npm i --save-dev ddduck`
+- `npx ddduck@<version>`, using the pinned version when the repository records one
+
+Present the options only. Do not install anything, and do not invoke an installer or `npx` on the user's behalf.

package/skills/update-ddduck-specs/references/reviewing-changes.md

@@ -1,6 +1,6 @@
 # Reviewing changes
 
-Read this reference when two product roots or revisions must be compared, or when a move, removal, or affected-context review is requested.
+Read this reference when two product roots or revisions must be compared, or when a move, removal, or affected-context review is requested. Every `ddduck …` command below names the command resolved by [executable resolution](executable-resolution.md); substitute it before running.
 
 ## Structural comparison
 

package/scripts/lib/skill-installer.mjs

@@ -1,598 +0,0 @@
-/**
- * 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 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 managed bundle refuses with a nextAction
- * naming the exact path to resolve.
- */
-
-import {
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  readlinkSync,
-  renameSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { createHash, randomUUID } from "node:crypto";
-import path from "node:path";
-
-const lockSchemaVersion = 2;
-const lockRelativePath = path.join(".ddduck", "agent-skills.lock.json");
-
-const defaultOperations = {
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  readlinkSync,
-  renameSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync,
-};
-
-const codexSkillDirectory = path.join(".agents", "skills", "update-ddduck-specs");
-const claudeSkillDirectory = path.join(".claude", "skills", "update-ddduck-specs");
-const skillFileName = "SKILL.md";
-
-const hostSkillAdapters = {
-  codex: {
-    host: "codex",
-    relativePath: codexSkillDirectory,
-    lockEntry() {
-      return { host: this.host, path: ".agents/skills/update-ddduck-specs" };
-    },
-    parentPaths(adapterPath) {
-      return [path.dirname(path.dirname(adapterPath)), path.dirname(adapterPath)];
-    },
-    inspect({ adapterPath, operations }) {
-      const state = pathState(adapterPath, operations);
-      if (state.type === "absent") return "absent";
-      return state.type === "directory" ? "valid" : "conflict";
-    },
-    materialize({ adapterPath, operations, touched }) {
-      touched.push(adapterPath);
-      operations.mkdirSync(adapterPath, { recursive: true });
-    },
-  },
-  claudeDirectory: {
-    host: "claude-code",
-    relativePath: claudeSkillDirectory,
-    lockEntry() {
-      return { host: this.host, path: ".claude/skills/update-ddduck-specs" };
-    },
-    parentPaths(adapterPath) {
-      return [path.dirname(path.dirname(adapterPath)), path.dirname(adapterPath)];
-    },
-    inspect({ adapterPath, operations }) {
-      const state = pathState(adapterPath, operations);
-      if (state.type === "absent") return "absent";
-      return state.type === "directory" ? "valid" : "conflict";
-    },
-    materialize({ adapterPath, operations, touched }) {
-      touched.push(adapterPath);
-      operations.mkdirSync(adapterPath, { recursive: true });
-    },
-  },
-  claudeSymlink: {
-    host: "claude-code",
-    relativePath: claudeSkillDirectory,
-    target: "../../.agents/skills/update-ddduck-specs",
-    lockEntry() {
-      return { host: this.host, path: ".claude/skills/update-ddduck-specs", target: this.target };
-    },
-    parentPaths(adapterPath) {
-      return [path.dirname(path.dirname(adapterPath)), path.dirname(adapterPath)];
-    },
-    inspect({ adapterPath, operations }) {
-      const state = pathState(adapterPath, operations);
-      if (state.type === "absent") return "absent";
-      if (state.type !== "symlink" || operations.readlinkSync(adapterPath) !== this.target) return "conflict";
-      return pathState(path.join(adapterPath, skillFileName), operations).type === "file" ? "valid" : "conflict";
-    },
-    materialize({ adapterPath, operations, touched }) {
-      touched.push(path.dirname(adapterPath), adapterPath);
-      operations.mkdirSync(path.dirname(adapterPath), { recursive: true });
-      operations.symlinkSync(this.target, adapterPath);
-    },
-  },
-};
-
-const installTopologies = [
-  {
-    id: "codex",
-    canonicalRelativePath: path.join(codexSkillDirectory, skillFileName),
-    adapters: [hostSkillAdapters.codex],
-  },
-  {
-    id: "claude-code",
-    canonicalRelativePath: path.join(claudeSkillDirectory, skillFileName),
-    adapters: [hostSkillAdapters.claudeDirectory],
-  },
-  {
-    id: "shared",
-    canonicalRelativePath: path.join(codexSkillDirectory, skillFileName),
-    adapters: [hostSkillAdapters.codex, hostSkillAdapters.claudeSymlink],
-  },
-];
-
-/**
- * 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, bundleSha256: string, canonicalPath: string, lockPath: string}} The installation result.
- */
-export function installSkill(options) {
-  const bundle = loadSkillBundle(options);
-  const plan = planSkillInstall({ ...options, bundle });
-  return applySkillInstall({ ...options, bundle, plan });
-}
-
-/**
- * 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, 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 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: 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 };
-  const root = path.resolve(repository);
-  const lockPath = path.join(root, lockRelativePath);
-  const lockState = readLock(lockPath, resolvedOperations);
-  const topology = selectTopology({ root, lockState, operations: resolvedOperations });
-  const paths = installationPaths(root, topology);
-  assertDirectoryParents(paths, topology, resolvedOperations);
-  const canonical = pathState(paths.canonical, resolvedOperations);
-  const adapters = inspectHostAdapters(paths, topology, resolvedOperations);
-  const conflictingAdapter = adapters.find(({ state }) => state === "conflict");
-
-  if (lockState.type === "invalid") throw incompleteLock(paths.lock);
-  if (conflictingAdapter) throw conflictingHostAdapter(conflictingAdapter, paths);
-
-  if (lockState.type === "absent") {
-    const canonicalDirectory = pathState(paths.canonicalDirectory, resolvedOperations);
-    if (
-      canonicalDirectory.type === "directory" &&
-      canonical.type === "absent" &&
-      resolvedOperations.readdirSync(paths.canonicalDirectory).length > 0
-    ) {
-      throw conflictingHostState(
-        `Conflicting canonical skill directory: ${paths.canonicalDirectory}`,
-        paths.canonicalDirectory,
-      );
-    }
-    if (canonical.type === "absent") {
-      return createPlan({ paths, adapters, writeBundle: true });
-    }
-    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, writeBundle: false });
-  }
-
-  const lock = lockState.value;
-  if (!isValidLock(lock, skillName, topology)) throw incompleteLock(paths.lock);
-  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: installedDigest === bundle.bundleSha256 ? "no-op" : "upgrade",
-    paths,
-    topology,
-    adaptersToMaterialize: [],
-    writeBundle: installedDigest !== bundle.bundleSha256,
-    staleFiles,
-  };
-}
-
-/**
- * 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: 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 originalBundle = plan.writeBundle ? snapshotDirectory(plan.paths.canonicalDirectory, resolvedOperations) : null;
-  let bundleWritten = false;
-  const materializedAdapters = [];
-
-  try {
-    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({
-        adapterPath: plan.paths.adapters[adapter.host],
-        operations: resolvedOperations,
-        touched,
-      });
-      materializedAdapters.push(adapter);
-    }
-
-    atomicWrite(
-      plan.paths.lock,
-      `${JSON.stringify(createLock({ packageVersion, bundle, topology: plan.topology }), null, 2)}\n`,
-      resolvedOperations,
-      touched,
-    );
-    return installResult(plan.action, bundle, plan);
-  } catch (error) {
-    const recoveryFailures = restoreAfterFailure({
-      plan,
-      originalBundle,
-      bundleWritten,
-      materializedAdapters,
-      operations: resolvedOperations,
-      touched,
-    });
-    const paths = [...new Set(touched)].join(", ") || "none";
-    const recovery = recoveryFailures.length === 0 ? "" : ` Recovery failures: ${recoveryFailures.join("; ")}.`;
-    throw new Error(`Skill installation failed after touching: ${paths}. ${error.message}.${recovery}`);
-  }
-}
-
-function installResult(action, bundle, plan) {
-  return {
-    action,
-    skillSha256: bundle.skillSha256,
-    bundleSha256: bundle.bundleSha256,
-    canonicalPath: toPosixPath(plan.topology.canonicalRelativePath),
-    lockPath: toPosixPath(lockRelativePath),
-  };
-}
-
-function createPlan({ paths, adapters, writeBundle }) {
-  return {
-    action: "create",
-    paths,
-    topology: paths.topology,
-    adaptersToMaterialize: adapters.filter(({ state }) => state === "absent").map(({ adapter }) => adapter),
-    writeBundle,
-    staleFiles: [],
-  };
-}
-
-function installationPaths(root, topology) {
-  const canonical = path.join(root, topology.canonicalRelativePath);
-  return {
-    canonical,
-    canonicalDirectory: path.dirname(canonical),
-    topology,
-    adapters: Object.fromEntries(
-      topology.adapters.map((adapter) => [adapter.host, path.join(root, adapter.relativePath)]),
-    ),
-    lock: path.join(root, lockRelativePath),
-  };
-}
-
-function inspectHostAdapters(paths, topology, operations) {
-  return topology.adapters.map((adapter) => ({
-    adapter,
-    state: adapter.inspect({ adapterPath: paths.adapters[adapter.host], operations }),
-  }));
-}
-
-function assertDirectoryParents(paths, topology, operations) {
-  const directories = [
-    ...topology.adapters.flatMap((adapter) => adapter.parentPaths(paths.adapters[adapter.host])),
-    path.dirname(paths.lock),
-  ];
-  for (const directory of new Set(directories)) {
-    const state = pathState(directory, operations);
-    if (!["absent", "directory"].includes(state.type)) {
-      throw new Error(`Conflicting skill installation path: ${directory}`);
-    }
-  }
-}
-
-function readLock(lockPath, operations) {
-  const state = pathState(lockPath, operations);
-  if (state.type === "absent") return { type: "absent" };
-  if (state.type !== "file") return { type: "invalid" };
-  try {
-    return { type: "valid", value: JSON.parse(operations.readFileSync(lockPath, "utf8")) };
-  } catch {
-    return { type: "invalid" };
-  }
-}
-
-function pathState(filePath, operations) {
-  try {
-    const stat = operations.lstatSync(filePath);
-    if (stat.isFile()) return { type: "file" };
-    if (stat.isDirectory()) return { type: "directory" };
-    if (stat.isSymbolicLink()) return { type: "symlink" };
-    return { type: "other" };
-  } catch (error) {
-    if (error.code === "ENOENT") return { type: "absent" };
-    throw error;
-  }
-}
-
-function selectTopology({ root, lockState, operations }) {
-  if (lockState.type === "valid") {
-    const topology = installTopologies.find(
-      (candidate) => toPosixPath(candidate.canonicalRelativePath) === toPosixPath(lockState.value.canonicalPath),
-    );
-    return topology ?? installTopologies[0];
-  }
-
-  const agents = pathState(path.join(root, ".agents"), operations).type;
-  const claude = pathState(path.join(root, ".claude"), operations).type;
-  if (agents === "directory" && claude === "directory") return installTopologies.find(({ id }) => id === "shared");
-  if (claude === "directory") return installTopologies.find(({ id }) => id === "claude-code");
-  return installTopologies.find(({ id }) => id === "codex");
-}
-
-function isValidLock(lock, skillName, topology) {
-  return (
-    lock &&
-    [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.skillSha256,
-    bundleSha256: bundle.bundleSha256,
-    files: bundle.files.map(({ path: relativePath, sha256: fileSha256 }) => ({
-      path: relativePath,
-      sha256: fileSha256,
-    })),
-    adapters: expectedAdapters(topology),
-  };
-}
-
-function expectedAdapters(topology) {
-  return topology.adapters.map((adapter) => adapter.lockEntry());
-}
-
-function conflictingHostAdapter({ adapter }, paths) {
-  const label = adapter.host === "claude-code" ? "Claude Code" : adapter.host;
-  return conflictingHostState(
-    `Conflicting ${label} adapter: ${paths.adapters[adapter.host]}`,
-    paths.adapters[adapter.host],
-  );
-}
-
-// Host-state conflicts are environment failures, not input failures: name the
-// pre-existing path the user must resolve instead of the usage hint.
-function conflictingHostState(message, conflictingPath) {
-  const error = new Error(message);
-  error.nextAction = `Move ${conflictingPath} aside or remove it, then re-run ddduck install skill update-ddduck-specs.`;
-  return error;
-}
-
-function atomicWrite(destination, content, operations, touched) {
-  const directory = path.dirname(destination);
-  const temporary = path.join(directory, `.${path.basename(destination)}.${randomUUID()}.tmp`);
-  touched.push(directory, temporary, destination);
-  try {
-    operations.mkdirSync(directory, { recursive: true });
-    operations.writeFileSync(temporary, content);
-    operations.renameSync(temporary, destination);
-  } finally {
-    if (pathState(temporary, operations).type !== "absent") operations.rmSync(temporary, { force: true });
-  }
-}
-
-function restoreAfterFailure({ plan, originalBundle, bundleWritten, materializedAdapters, operations, touched }) {
-  const failures = [];
-  for (const adapter of materializedAdapters.toReversed()) {
-    try {
-      const adapterPath = plan.paths.adapters[adapter.host];
-      touched.push(adapterPath);
-      if (pathState(adapterPath, operations).type !== "absent") {
-        operations.rmSync(adapterPath, { recursive: true, force: true });
-      }
-    } catch (error) {
-      failures.push(`remove ${adapter.host} adapter: ${error.message}`);
-    }
-  }
-  if (!bundleWritten && originalBundle === null) return failures;
-
-  try {
-    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 bundle: ${error.message}`);
-  }
-  return failures;
-}
-
-function incompleteLock(lockPath) {
-  const error = new Error(`Incomplete or inconsistent skill lock: ${lockPath}`);
-  // Deleting the lock is safe: the next install rebuilds it from the repository
-  // state, and any canonical mismatch then surfaces as its own conflict.
-  error.nextAction = `Delete ${lockPath}, then re-run ddduck install skill update-ddduck-specs to rebuild it.`;
-  return error;
-}
-
-function locallyModifiedCanonical(canonicalPath) {
-  const error = new Error(`Locally modified canonical skill: ${canonicalPath}`);
-  error.nextAction = `Revert or remove ${canonicalPath}, then re-run ddduck install skill update-ddduck-specs.`;
-  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");
-}
-
-function toPosixPath(value) {
-  return String(value).replaceAll("\\", "/");
-}