ddduck 0.1.0 → 0.2.0

package/scripts/lib/skill-installer.mjs

@@ -1,3 +1,14 @@
+/**
+ * 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,
@@ -12,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 = {
@@ -112,21 +123,48 @@ 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, 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 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: 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);
@@ -149,51 +187,77 @@ export function planSkillInstall({ repository, skillName, bundle, operations = {
       canonical.type === "absent" &&
       resolvedOperations.readdirSync(paths.canonicalDirectory).length > 0
     ) {
-      throw new Error(`Conflicting canonical skill directory: ${paths.canonicalDirectory}`);
+      throw conflictingHostState(
+        `Conflicting canonical skill directory: ${paths.canonicalDirectory}`,
+        paths.canonicalDirectory,
+      );
     }
     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) {
-      throw new Error(`Conflicting canonical skill destination: ${paths.canonical}`);
+    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 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 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({
@@ -214,8 +278,8 @@ export function applySkillInstall({ packageVersion, bundle, plan, operations = {
   } catch (error) {
     const recoveryFailures = restoreAfterFailure({
       plan,
-      originalCanonical,
-      canonicalWritten,
+      originalBundle,
+      bundleWritten,
       materializedAdapters,
       operations: resolvedOperations,
       touched,
@@ -229,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: [],
   };
 }
 
@@ -320,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),
   };
 }
@@ -347,7 +429,18 @@ function expectedAdapters(topology) {
 
 function conflictingHostAdapter({ adapter }, paths) {
   const label = adapter.host === "claude-code" ? "Claude Code" : adapter.host;
-  return new Error(`Conflicting ${label} adapter: ${paths.adapters[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) {
@@ -363,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 {
@@ -376,23 +469,26 @@ 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;
 }
 
 function incompleteLock(lockPath) {
-  return new Error(`Incomplete or inconsistent skill lock: ${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) {
@@ -401,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");
 }

package/scripts/query-model.mjs

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 
-import path from "node:path";
+/**
+ * Implements `ddduck query`, the read-only query surface: dispatches the
+ * operations node, neighbors, impact, anchors, spec, and context to
+ * lib/product-query.mjs and lib/context-pack.mjs, emitting exactly one JSON
+ * document on stdout. The product root auto-resolves (enclosing directory,
+ * config, or unique discovery) unless --root is passed; busy or interrupted
+ * roots are refused before any answer is served. Also imported by ddduck.mjs
+ * and the agent-readiness evals as the runQuery entry point.
+ */
+
 import { fileURLToPath } from "node:url";
 import { resolveContextPack } from "./lib/context-pack.mjs";
 import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
@@ -14,6 +23,12 @@ import {
 } from "./lib/product-query.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
 
+/**
+ * Parse and run one query invocation, writing the JSON document to stdout.
+ * @param {string[]} args - Arguments after the `query` command word.
+ * @param {{cwd?: string, stdout?: {write: (chunk: string) => unknown}}} [io] - Working directory for root resolution and the output stream (used by the evals harness to capture output).
+ * @returns {void}
+ */
 export function runQuery(args, { cwd = process.cwd(), stdout = process.stdout } = {}) {
   if (args.includes("--help")) {
     stdout.write(renderHelp("query"));
@@ -30,14 +45,10 @@ export function runQuery(args, { cwd = process.cwd(), stdout = process.stdout }
   const ids = options.id;
   const id = ids[0];
   if (operation !== "context" && ids.length > 1) throw new CliUsageError(`query ${operation} accepts exactly one --id`);
-  if (operation === "context") {
-    if (options.history) throw new CliUsageError("query context does not support --history");
-    if (!options.root) throw new CliUsageError("query context requires --root <product-root>");
-  }
+  if (operation === "context" && options.history) throw new CliUsageError("query context does not support --history");
   if (operation !== "spec" && !id) throw new CliUsageError(`query ${operation} requires --id <model-node-id>`);
 
-  const root =
-    operation === "context" ? path.resolve(cwd, options.root) : resolveProductRoot({ cwd, explicitRoot: options.root });
+  const root = resolveProductRoot({ cwd, explicitRoot: options.root });
   const product = loadQueryProduct(root, { history: options.history });
   if (operation === "spec" && id && id !== product.rootModelId) {
     throw new CliUsageError(`query spec --id must be ${product.rootModelId}`);

package/scripts/run-agent-readiness-evals.mjs

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 
+/**
+ * CLI wrapper for the agent-readiness eval harness: reads a JSONL file of eval
+ * records (--input) that each name a product root below --repo-root, a query
+ * to run, and candidate evidence to verify, then delegates to
+ * lib/agent-readiness-evals.mjs. Emits one JSON result document on stdout,
+ * optionally mirrors it to --output (contained below the repo root, never
+ * .git), and exits 1 unless every case passed.
+ */
+
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { format } from "prettier";
 import { runAgentReadinessEvals } from "./lib/agent-readiness-evals.mjs";
 import { resolveContainedOutput } from "./lib/product-paths.mjs";
 
@@ -10,7 +18,9 @@ try {
   const options = parseArgs(process.argv.slice(2));
   const outputTarget = options.output ? resolveOutputPath(options.repoRoot, options.output) : null;
   const result = runAgentReadinessEvals(options);
-  const output = await format(JSON.stringify(result), { parser: "json", printWidth: 120 });
+  // Deterministic serialization with no runtime formatter dependency: the
+  // published package must run without devDependencies.
+  const output = `${JSON.stringify(result, null, 2)}\n`;
   process.stdout.write(output);
   if (outputTarget) writeOutput(outputTarget, output);
   process.exitCode = result.passed ? 0 : 1;
@@ -19,6 +29,12 @@ try {
   process.exitCode = 1;
 }
 
+/**
+ * Parse the --input/--repo-root/--output arguments, rejecting duplicates and
+ * missing values.
+ * @param {string[]} args - Raw CLI arguments.
+ * @returns {{inputPath: string, repoRoot: string, output: string|undefined}} Resolved option paths.
+ */
 function parseArgs(args) {
   const options = {};
   for (let index = 0; index < args.length; index += 1) {

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

@@ -1,98 +1,40 @@
 ---
 name: update-ddduck-specs
-description: Use when a repository's ddduck product model needs to be created, audited against current code, tests, and documentation, or reconciled after product changes.
+description: Use when a repository's ddduck product model needs to be created, audited against current code, tests, and documentation, compared across revisions, or reconciled after product changes.
 ---
 
 # Update ddduck Specs
 
-Maintain or bootstrap a repository's ddduck product model from evidence visible in the current working tree.
+Maintain or bootstrap a ddduck product model from evidence in the current working tree. Preserve the difference between observed implementation, accepted intent, canonical product meaning, generated views, and runtime proof.
 
-## Inputs and boundaries
+## Operating contract
 
-- Resolve the repository root, read all applicable repository instructions, and inspect Git status before analysis.
-- Use an explicitly requested product root; otherwise let ddduck resolve it in its own order: the enclosing product root of the current directory, else the `productRoot` in `.ddduck/config.json`, else the unique discovered product root in the repository. `ddduck query spec` reports the resolved root. Ambiguous resolution is a stop condition: report the candidates and ask; never bootstrap a second product root beside an existing one.
-- Default to plan-only. Mutate files only when the current user request explicitly authorizes application, including prose that clearly authorizes the evidence-backed changes. `--root <path>` and `--apply` may be convenient shorthand, but ordinary prose must work.
-- Preserve unrelated and uncommitted work. Stop when intended target files overlap user changes inseparably.
-- Write only `<root>/product.yaml`, `<root>/model/**`, `<root>/decisions/**`, and regenerated `<root>/generated/**`.
-- Never edit generated views directly. Regenerate them with ddduck.
-- Use only evidence visible in the current working tree. Do not rely on prior chat, cursor, cache, or an assumed previous revision.
-- Preserve stable IDs and Guarantee lifecycle. Never silently delete or reuse a Guarantee ID. Use ddduck lifecycle commands where they cover the mutation.
-- Never create an ADR merely to satisfy validation or justify an inferred change.
-- Keep unresolved questions out of canonical model facts.
-- Prefer the smallest coherent product-model change. Avoid ornamental DDD vocabulary and speculative structure.
-- Do not commit or push consumer changes unless the user separately requests it.
+- 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.
+- 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.
+- Preserve stable IDs and Guarantee history. Use lifecycle commands for Guarantee transitions and the supported creation commands for Domain, Concept, and UseCase.
+- Keep unresolved questions in prose. Canonicalize only meaning that is unambiguous and supported by inspected evidence or accepted authority.
+- Commit, push, consumer migration, and external effects require separate authorization.
 
-Use a repository-compatible ddduck executable. Do not install dependencies or silently fall back to an unrelated global version.
+## Load the relevant reference
 
-## Establish the baseline
+Read each selected reference completely before acting. All references are one level below this file.
 
-Classify the selected root exactly once:
+- 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.
 
-- `existing`: `product.yaml` exists. Run `ddduck query spec --root <root> --json` and `ddduck check --root <root>`, recording both outcomes independently. A failing existing model is invalid, not absent, and must not be reinitialized.
-- `absent`: the root is missing or empty. Inspect the repository before proposing initialization.
-- `path-collision`: the root is non-empty but not a recognizable ddduck product. Report the collision and never initialize over it.
+## Workflow
 
-Stop before mutation when the ddduck executable is missing or incompatible, multiple product roots are plausible and none was selected, the selected root is a non-empty path collision, bootstrap identity, purpose, or initial domain seams are not grounded, evidence conflicts materially change the proposed model, target model files overlap inseparable user changes, or the analyzed working-tree state changed before application.
+1. Resolve and classify the product root. Record `query spec` and `check` independently; an invalid existing model is not an absent model.
+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.
+5. If application is explicitly authorized, recheck Git status, decisive evidence, and target files; then apply only the approved unambiguous changes.
+6. Run the complete verification sequence from the authoring reference. Any failed command makes the result `incomplete`.
 
-## Gather evidence
+## Completion criteria
 
-Inspect relevant current code, tests, public interfaces, documentation, configuration, schemas, workspace structure, and accepted decisions. Record material exclusions and coverage gaps.
-
-For every candidate fact, record:
-
-- proposed model assertion;
-- repository-relative path plus line, symbol, heading, or test name;
-- evidence role: implementation, verification, documentation, decision, or configuration;
-- contradictory evidence;
-- inspected scope and remaining unknowns.
-
-Executable behavior and passing tests establish observed behavior. Accepted requirements and decisions establish intended behavior. Treat conflicts between them as inconsistencies; do not silently encode either a possible bug or an unimplemented requirement as product truth.
-
-The current schema restricts persisted interface evidence anchors to paths inside the product root. Cite repository-wide evidence in the plan and final report, but persist only schema-supported product-root anchors. Do not copy source evidence into the product root, invent unsupported metadata, or create bridge documents merely to manufacture provenance.
-
-For a greenfield repository, use runtime-supported subagents only when no model exists and the relevant corpus spans several substantial, independent packages, applications, or domain areas that cannot be covered reliably in the coordinating context. Repository file count alone is not sufficient. Subagents are read-only evidence adapters: assign non-overlapping scopes, provide applicable repository instructions, forbid writes and canonical model synthesis, require candidate facts with exact evidence locations, conflicts, unknowns, and coverage, then re-read decisive evidence before adopting it. The coordinator is the sole writer. If subagents are unavailable, inspect the same scopes sequentially and disclose the coverage limitations.
-
-## Compare and classify
-
-Classify every material difference as exactly one of:
-
-- verified omission;
-- stale modeled fact;
-- structural inconsistency with an unambiguous repair;
-- contradiction or uncertainty requiring a human decision;
-- irrelevant implementation detail;
-- insufficiently covered.
-
-For existing models, preserve identity and history.
-
-## Plan-only workflow
-
-Before any mutation, report in this order:
-
-1. Mode, resolved root, and model state.
-2. Baseline query and validation status.
-3. Inspected coverage, exclusions, and gaps.
-4. Proposed changes with classification, concrete evidence, and exact target files.
-5. Contradictions, uncertainties, and required decisions.
-6. Exact generation and verification commands.
-
-Without explicit application authorization, stop before all writes. Plan mode performs no writes, including initialization and generation.
-
-## Apply workflow
-
-When application is explicitly authorized:
-
-1. Recheck Git status, intended target files, and decisive evidence.
-2. Initialize only an absent or empty root whose model identity, purpose, and initial domain seams are explicit or unambiguously grounded. Otherwise request the missing decision.
-3. Apply only planned, evidence-backed changes whose meaning is unambiguous.
-4. Leave unresolved findings unchanged.
-5. Use ddduck lifecycle commands for Guarantee transitions. Author other canonical YAML against installed schemas and existing model conventions.
-6. Run `ddduck check --root <root> --source-only` before generation; hand-authored canonical edits legitimately leave generated views stale until step 7.
-7. Run `ddduck generate --root <root>`.
-8. Run `ddduck check --root <root>` again.
-9. Run `ddduck query spec --root <root> --json` and require every generated view to be fresh.
-10. Inspect the final diff for scope.
-
-Any command failure makes the result incomplete. Inspect and report the resulting working tree; never destructively roll back unrelated user work.
-
-Report changed canonical, decision, and generated files; evidence supporting each material change; skipped and unresolved findings; exact command outcomes and diagnostics; final generated-view freshness; and remaining coverage gaps. Explicitly report `incomplete` when any verification or scope check fails. A verified no-op is a valid result; do not create model content merely to demonstrate activity.
+Report the resolved root and mode, baseline outcomes, inspected coverage, changed or proposed IDs and files, supporting evidence, contradictions and open decisions, exact command results, generated-view freshness, and remaining gaps. For comparisons, distinguish structural differences from semantic approval. For applications, inspect the final scoped diff and report every skipped or unresolved finding.