ddduck 0.1.0

package/scripts/lib/skill-installer.mjs

@@ -0,0 +1,410 @@
+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 = 1;
+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],
+  },
+];
+
+export function installSkill(options) {
+  const bundle = loadSkillBundle(options);
+  const plan = planSkillInstall({ ...options, bundle });
+  return applySkillInstall({ ...options, bundle, plan });
+}
+
+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) };
+}
+
+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 new Error(`Conflicting canonical skill directory: ${paths.canonicalDirectory}`);
+    }
+    if (canonical.type === "absent") {
+      return createPlan({ paths, adapters, writeCanonical: true });
+    }
+    if (canonical.type !== "file" || sha256(resolvedOperations.readFileSync(paths.canonical)) !== bundle.sha256) {
+      throw new Error(`Conflicting canonical skill destination: ${paths.canonical}`);
+    }
+    return createPlan({ paths, adapters, writeCanonical: 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 (adapters.some(({ state }) => state !== "valid")) throw incompleteLock(paths.lock);
+
+  return {
+    action: lock.skillSha256 === bundle.sha256 ? "no-op" : "upgrade",
+    paths,
+    topology,
+    adaptersToMaterialize: [],
+    writeCanonical: lock.skillSha256 !== bundle.sha256,
+  };
+}
+
+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 materializedAdapters = [];
+
+  try {
+    if (plan.writeCanonical) {
+      atomicWrite(plan.paths.canonical, bundle.bytes, resolvedOperations, touched);
+      canonicalWritten = 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,
+      originalCanonical,
+      canonicalWritten,
+      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.sha256,
+    canonicalPath: toPosixPath(plan.topology.canonicalRelativePath),
+    lockPath: toPosixPath(lockRelativePath),
+  };
+}
+
+function createPlan({ paths, adapters, writeCanonical }) {
+  return {
+    action: "create",
+    paths,
+    topology: paths.topology,
+    adaptersToMaterialize: adapters.filter(({ state }) => state === "absent").map(({ adapter }) => adapter),
+    writeCanonical,
+  };
+}
+
+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 &&
+    lock.schemaVersion === lockSchemaVersion &&
+    lock.skill === skillName &&
+    typeof lock.ddduckVersion === "string" &&
+    lock.ddduckVersion.length > 0 &&
+    toPosixPath(lock.canonicalPath) === toPosixPath(topology.canonicalRelativePath) &&
+    /^[a-f0-9]{64}$/.test(lock.skillSha256) &&
+    JSON.stringify(lock.adapters) === JSON.stringify(expectedAdapters(topology))
+  );
+}
+
+function createLock({ packageVersion, bundle, topology }) {
+  return {
+    schemaVersion: lockSchemaVersion,
+    skill: bundle.name,
+    ddduckVersion: packageVersion,
+    canonicalPath: toPosixPath(topology.canonicalRelativePath),
+    skillSha256: bundle.sha256,
+    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 new Error(`Conflicting ${label} adapter: ${paths.adapters[adapter.host]}`);
+}
+
+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, originalCanonical, canonicalWritten, 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 (!canonicalWritten) 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 });
+    }
+  } catch (error) {
+    failures.push(`restore canonical skill: ${error.message}`);
+  }
+  return failures;
+}
+
+function incompleteLock(lockPath) {
+  return new Error(`Incomplete or inconsistent skill lock: ${lockPath}`);
+}
+
+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 sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function toPosixPath(value) {
+  return String(value).replaceAll("\\", "/");
+}

package/scripts/query-model.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveContextPack } from "./lib/context-pack.mjs";
+import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
+import {
+  loadQueryProduct,
+  queryAnchors,
+  queryImpact,
+  queryNeighbors,
+  queryNode,
+  querySpec,
+} from "./lib/product-query.mjs";
+import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
+
+export function runQuery(args, { cwd = process.cwd(), stdout = process.stdout } = {}) {
+  if (args.includes("--help")) {
+    stdout.write(renderHelp("query"));
+    return;
+  }
+  const { positionals, options } = parseCommandArgs(args, {
+    positionals: { min: 1, max: 1 },
+    options: { id: { value: true, repeatable: true }, root: { value: true }, history: {}, json: {} },
+  });
+  const [operation] = positionals;
+  if (!operation || !["node", "neighbors", "impact", "anchors", "spec", "context"].includes(operation)) {
+    throw new CliUsageError("query requires operation node, neighbors, impact, anchors, spec, or context");
+  }
+  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 !== "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 product = loadQueryProduct(root, { history: options.history });
+  if (operation === "spec" && id && id !== product.rootModelId) {
+    throw new CliUsageError(`query spec --id must be ${product.rootModelId}`);
+  }
+  const document = {
+    node: () => queryNode(product, id, { history: options.history }),
+    neighbors: () => queryNeighbors(product, id, { history: options.history }),
+    impact: () => queryImpact(product, id, { history: options.history }),
+    anchors: () => queryAnchors(product, id, { history: options.history }),
+    spec: () => querySpec(product, { history: options.history }),
+    context: () => resolveContextPack(product, ids),
+  }[operation]();
+  stdout.write(`${JSON.stringify(document)}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    runQuery(process.argv.slice(2));
+  } catch (error) {
+    writeCliError(error, {
+      nextAction: "Run ddduck query --help, correct the input, and retry.",
+    });
+  }
+}

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+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";
+
+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 });
+  process.stdout.write(output);
+  if (outputTarget) writeOutput(outputTarget, output);
+  process.exitCode = result.passed ? 0 : 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}
+
+function parseArgs(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!["--input", "--repo-root", "--output"].includes(argument)) {
+      throw new Error(
+        "usage: node scripts/run-agent-readiness-evals.mjs --input <jsonl> --repo-root <path> [--output <json>]",
+      );
+    }
+    if (Object.hasOwn(options, argument)) throw new Error(`duplicate CLI argument: ${argument}`);
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`missing value for ${argument}`);
+    options[argument] = value;
+    index += 1;
+  }
+  if (!options["--input"] || !options["--repo-root"]) {
+    throw new Error(
+      "usage: node scripts/run-agent-readiness-evals.mjs --input <jsonl> --repo-root <path> [--output <json>]",
+    );
+  }
+  return {
+    inputPath: path.resolve(options["--input"]),
+    repoRoot: path.resolve(options["--repo-root"]),
+    output: options["--output"],
+  };
+}
+
+function resolveOutputPath(repoRoot, outputPath) {
+  if (outputPath.split(/[\\/]/)[0] === ".git") throw new Error("output path must not target .git");
+  return resolveContainedOutput(repoRoot, outputPath);
+}
+
+function writeOutput(target, output) {
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, output);
+}

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

@@ -0,0 +1,98 @@
+---
+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.
+---
+
+# Update ddduck Specs
+
+Maintain or bootstrap a repository's ddduck product model from evidence visible in the current working tree.
+
+## Inputs and boundaries
+
+- 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.
+
+Use a repository-compatible ddduck executable. Do not install dependencies or silently fall back to an unrelated global version.
+
+## Establish the baseline
+
+Classify the selected root exactly once:
+
+- `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.
+
+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.
+
+## Gather evidence
+
+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.