dld-kit 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/dld.mjs

@@ -7372,7 +7372,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 // package.json
-var version = "1.0.0-rc.2";
+var version = "1.0.0-rc.4";
 
 // src/core/errors.ts
 var EXIT_ERROR = 1;
@@ -7902,11 +7902,11 @@ function detectSnapshotChanges(ctx, project) {
   if ((stored === void 0 || stored === "unknown") && lastRun !== void 0) {
     stored = gitOrEmpty(git, "log", `--until=${lastRun}`, "--format=%h", "-1").trim() || void 0;
   }
-  const commit = resolveStateCommit(git, stored);
+  const commit2 = resolveStateCommit(git, stored);
   let modifiedDecisions = [];
   let commitRange = "";
-  if (commit !== void 0 && commit !== shortHead(ctx, paths.root)) {
-    commitRange = `${commit}..HEAD`;
+  if (commit2 !== void 0 && commit2 !== shortHead(ctx, paths.root)) {
+    commitRange = `${commit2}..HEAD`;
     const numbers = nulSeparated(
       gitOrEmpty(git, "diff", "-z", "--name-only", commitRange, "--", recordsPathspec(paths))
     ).map((path) => basename3(path)).filter((name) => RECORD_FILE.test(name)).map((name) => recordNumber(name)).filter((number) => number <= includedNumber);
@@ -7927,23 +7927,24 @@ function formatSnapshotChanges(changes) {
 function updateSnapshotState(ctx, project, customArtifacts) {
   const { paths } = project;
   const timestamp = formatTimestamp(ctx.now());
-  const commit = shortHead(ctx, paths.root);
+  const commit2 = shortHead(ctx, paths.root);
   const highest = readRecords(ctx, project).filter((record) => record.accepted).reduce((max, record) => Math.max(max, record.number), 0);
   const artifacts = /* @__PURE__ */ Object.create(null);
   for (const name of [...BUILT_IN_ARTIFACTS, ...customArtifacts]) artifacts[name] = timestamp;
   writeStateSection(ctx, paths, "snapshot", {
     last_run: timestamp,
-    commit_hash: commit,
+    commit_hash: commit2,
     decisions_included: String(highest),
     artifacts
   });
-  return { timestamp, commit, highest };
+  return { timestamp, commit: commit2, highest };
 }
 
 // src/cli/commands/collect-active-decisions.ts
 var collectActiveDecisionsCommand = {
   name: "collect-active-decisions",
   summary: "Print every accepted decision record",
+  internal: true,
   usage: "Usage: dld collect-active-decisions\n\nPrint each accepted record in ID order, separated by ===DLD_DECISION_BOUNDARY=== lines.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -7961,8 +7962,9 @@ import { basename as basename4 } from "node:path";
 // src/core/open-prs.ts
 var GITHUB_REMOTE = /github\.com[:/]/;
 var PR_LIMIT = "100";
+var COMMIT_ID = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
 function openPrIds(ctx, paths, base) {
-  const skipped = (reason) => ({ ids: [], skipped: reason });
+  const skipped = (reason) => ({ claims: [], skipped: reason });
   try {
     ctx.gh(["--version"]);
   } catch (error) {
@@ -7989,7 +7991,7 @@ function openPrIds(ctx, paths, base) {
       "open",
       `--base=${prBase}`,
       "--json",
-      "files,headRefName,isCrossRepository",
+      "files,headRefName,headRefOid,isCrossRepository",
       "--limit",
       PR_LIMIT
     ]);
@@ -8003,14 +8005,15 @@ function openPrIds(ctx, paths, base) {
   if (prs === void 0) return skipped("gh pr list returned unexpected output");
   const current = gitOrEmpty(git, "rev-parse", "--abbrev-ref", "HEAD").trim();
   const prefix = `${recordsPathspec(paths)}/`;
-  const ids = [];
+  const claims = [];
   for (const pr of prs) {
     if (!pr.isCrossRepository && pr.headRefName === current) continue;
     for (const path of pr.files) {
-      if (path.startsWith(prefix)) ids.push(...path.match(DECISION_MENTION) ?? []);
+      if (!path.startsWith(prefix)) continue;
+      for (const id of path.match(DECISION_MENTION) ?? []) claims.push({ id, head: pr.headRefOid });
     }
   }
-  return { ids };
+  return { claims };
 }
 function parsePrList(output) {
   let value;
@@ -8026,6 +8029,7 @@ function parsePrList(output) {
     const files = Array.isArray(item.files) ? item.files : [];
     prs.push({
       headRefName: typeof item.headRefName === "string" ? item.headRefName : void 0,
+      headRefOid: typeof item.headRefOid === "string" && COMMIT_ID.test(item.headRefOid) ? item.headRefOid : void 0,
       isCrossRepository: item.isCrossRepository === true,
       files: files.flatMap(
         (file) => isObject(file) && typeof file.path === "string" ? [file.path] : []
@@ -8094,24 +8098,56 @@ function takenIds(ctx, paths, base) {
     gitOrEmpty(git, "ls-tree", "-r", "-z", "--name-only", base, "--", recordsPathspec(paths))
   ).flatMap((path) => path.match(DECISION_MENTION) ?? []);
   const scan = openPrIds(ctx, paths, base);
-  const ids = [.../* @__PURE__ */ new Set([...onBase, ...scan.ids])].sort(compareIds);
-  return scan.skipped === void 0 ? { ids } : { ids, skipped: scan.skipped };
+  const ids = [.../* @__PURE__ */ new Set([...onBase, ...scan.claims.map(({ id }) => id)])].sort(compareIds);
+  const taken = { ids, onBase: new Set(onBase), claims: scan.claims };
+  return scan.skipped === void 0 ? taken : { ...taken, skipped: scan.skipped };
+}
+function isAncestor(git, ancestor, commit2) {
+  try {
+    git("merge-base", "--is-ancestor", ancestor, commit2);
+    return true;
+  } catch (error) {
+    if (error instanceof GitCommandError) return false;
+    throw error;
+  }
+}
+function collides(git, base, { path, id }, taken) {
+  if (taken.onBase.has(id)) return true;
+  const claims = taken.claims.filter((claim) => claim.id === id);
+  if (claims.length === 0) return false;
+  const added = git(
+    "--literal-pathspecs",
+    "log",
+    // log.follow or log.showSignature in the user's config would change the output.
+    "--no-follow",
+    "--no-show-signature",
+    "-1",
+    "--format=%H",
+    "--diff-filter=A",
+    `${base}..HEAD`,
+    "--",
+    path
+  ).trim();
+  return claims.some(
+    ({ head }) => head === void 0 || added === "" || !isAncestor(git, added, head)
+  );
 }
 function listTakenIds(ctx, { paths }, base) {
   verifyBase(ctx, paths, base, " Fetch first or pass --base.");
-  return takenIds(ctx, paths, base);
+  const { ids, skipped } = takenIds(ctx, paths, base);
+  return skipped === void 0 ? { ids } : { ids, skipped };
 }
 function collisionsOf(ctx, paths, base) {
-  const added = localAdditions(gitAt(ctx, paths.root), paths, base);
+  const git = gitAt(ctx, paths.root);
+  const added = localAdditions(git, paths, base);
   const local = added.flatMap((path) => {
     const id = basename4(path, ".md");
     return RECORD_FILE.test(basename4(path)) ? [{ path, id }] : [];
   });
   if (local.length === 0) return { collisions: [], localIds: [], taken: [] };
   const taken = takenIds(ctx, paths, base);
-  const takenSet = new Set(taken.ids);
   const result = {
-    collisions: local.filter(({ id }) => takenSet.has(id)),
+    collisions: local.filter((record) => collides(git, base, record, taken)),
     localIds: local.map(({ id }) => id),
     taken: taken.ids
   };
@@ -8189,7 +8225,7 @@ function parseRenamePlan(paths, text) {
 
 // src/core/commit-reindex.ts
 var SUBJECT_LIST_LIMIT = 3;
-function reindexMessage(renames, originalSubjects) {
+function reindexMessage(renames, originalSubjects = "") {
   const pairs = renames.map(({ oldId, newId }) => `${oldId} -> ${newId}`);
   const subject = renames.length > SUBJECT_LIST_LIMIT ? `reindex ${renames.length} local decisions to avoid base-branch collisions` : `reindex local decisions: ${pairs.join(", ")}`;
   const message = `${subject}
@@ -8201,11 +8237,75 @@ ${pairs.map((pair) => `- ${pair}`).join("\n")}`;
 Squashed from original branch commits:
 ${originalSubjects}`;
 }
-function commitReindex(ctx, { paths }, planText, base) {
-  const git = gitAt(ctx, paths.root);
+function commitReindex(ctx, { paths }, planText, base, { squash = false } = {}) {
   verifyBase(ctx, paths, base);
   const renames = parseRenamePlan(paths, planText);
   if (renames.length === 0) throw new DldError("no rename plan on stdin.");
+  for (const { oldId, newId, path } of renames) {
+    const renamed = posix2.join(posix2.dirname(path), `${newId}.md`);
+    if (!ctx.fs.isRegularFile(join7(paths.root, renamed))) {
+      throw new DldError(`${renamed} not found. Run rename-decision for ${oldId} first.`);
+    }
+  }
+  const git = gitAt(ctx, paths.root);
+  return squash ? squashReindex(ctx, git, paths, renames, base) : commitOnTop(ctx, git, paths, renames);
+}
+function commitOnTop(ctx, git, paths, renames) {
+  const stage = /* @__PURE__ */ new Set();
+  for (const { path, newId } of renames) {
+    stage.add(path);
+    stage.add(posix2.join(posix2.dirname(path), `${newId}.md`));
+  }
+  for (const file of nulSeparated(git("diff", "-z", "--no-renames", "--name-only", "HEAD"))) {
+    stage.add(file);
+  }
+  const head = git("rev-parse", "HEAD").trim();
+  const tree = git("write-tree").trim();
+  let stepName = "staging";
+  try {
+    for (const path of [...stage].sort()) {
+      stepName = `staging ${path}`;
+      stagePath(ctx, git, join7(paths.root, path), path);
+    }
+    stepName = "checking the staged changes";
+    if (!hasStagedChanges(git)) {
+      throw new DldError(
+        "nothing to commit. The reindex may have already been committed, or the plan didn't match the working tree."
+      );
+    }
+    stepName = "committing";
+    commit(git, reindexMessage(renames));
+  } catch (error) {
+    try {
+      git("read-tree", tree);
+    } catch (restoreError) {
+      throw new DldError(
+        `commit-reindex failed while ${stepName}: ${describe(error)}
+Restoring the index also failed: ${describe(restoreError)}
+To restore by hand: git read-tree ${tree}`
+      );
+    }
+    if (!(error instanceof DldError)) throw error;
+    throw new DldError(
+      `commit-reindex failed while ${stepName}: ${error.message}
+The index was restored.`,
+      error.exitCode
+    );
+  }
+  return {
+    commit: git("rev-parse", "--short", "HEAD").trim(),
+    onto: git("rev-parse", "--short", head).trim()
+  };
+}
+function commit(git, message) {
+  try {
+    git("commit", "--quiet", "-m", message);
+  } catch (error) {
+    if (error instanceof GitCommandError) throw new DldError(`git commit failed: ${error.stderr}`);
+    throw error;
+  }
+}
+function squashReindex(ctx, git, paths, renames, base) {
   const onto = mergeBase(ctx, paths, base);
   const head = git("rev-parse", "HEAD").trim();
   if (onto === head) throw new DldError("HEAD is already at the merge-base \u2014 nothing to squash.");
@@ -8254,15 +8354,7 @@ function commitReindex(ctx, { paths }, planText, base) {
         );
       }
     });
-    step("committing", () => {
-      try {
-        git("commit", "--quiet", "-m", message);
-      } catch (error) {
-        if (error instanceof GitCommandError)
-          throw new DldError(`git commit failed: ${error.stderr}`);
-        throw error;
-      }
-    });
+    step("committing", () => commit(git, message));
   } catch (error) {
     throw rollback(ctx, git, indexFull, saved, stepName, error);
   }
@@ -8325,23 +8417,35 @@ function skippedNotice(reason) {
 // src/cli/commands/commit-reindex.ts
 var commitReindexCommand = {
   name: "commit-reindex",
-  summary: "Squash the branch into one reindex commit",
-  usage: `Usage: dld commit-reindex --base <ref> < plan
+  summary: "Commit the renamed decisions",
+  internal: true,
+  usage: `Usage: dld commit-reindex --base <ref> [--squash] < plan
+
+Read a rename plan on standard input and commit the renames, which rename-decision has
+already applied. By default this adds one commit on top of HEAD with the plan's paths and
+every tracked file changed since HEAD; untracked files are left out. On failure the index is
+restored.
 
-Read a rename plan on standard input and squash the branch's commits since the merge-base
-with <ref> into one reindex commit. INDEX.md is left at its merge-base state. On failure the
-branch, index and INDEX.md are restored.
+With --squash, the branch's commits since the merge-base with <ref> are squashed into one
+reindex commit instead, and INDEX.md is left at its merge-base state. On failure the branch,
+index and INDEX.md are restored.
 
 Options:
   --base <ref>  Base ref (required)
+  --squash      Squash the branch instead of adding a commit
 `,
   run(args, io, ctx) {
-    const { values } = parseCommandArgs({ args: [...args], options: { base: { type: "string" } } });
+    const { values } = parseCommandArgs({
+      args: [...args],
+      options: { base: { type: "string" }, squash: { type: "boolean" } }
+    });
     if (!values.base) throw new DldError("--base is required.");
     const base = baseOption(values.base);
     const project = loadProject(ctx);
-    const { commit, onto } = commitReindex(ctx, project, ctx.readStdin(), base);
-    io.stdout(`Created reindex commit ${commit} on top of ${onto}
+    const { commit: commit2, onto } = commitReindex(ctx, project, ctx.readStdin(), base, {
+      squash: values.squash === true
+    });
+    io.stdout(`Created reindex commit ${commit2} on top of ${onto}
 `);
     return EXIT_OK;
   }
@@ -8386,6 +8490,7 @@ function createDirectories(ctx, { config, paths }) {
 var createConfigCommand = {
   name: "create-config",
   summary: "Create dld.config.yaml at the project root",
+  internal: true,
   usage: "Usage: dld create-config <flat|namespaced> [namespace ...]\n\nCreate dld.config.yaml. Namespaced mode needs at least one namespace.\n",
   run(args, io, ctx) {
     const { positionals } = parseCommandArgs({
@@ -8443,6 +8548,7 @@ function isSafeDirName(name) {
 var createDecisionCommand = {
   name: "create-decision",
   summary: "Create a proposed decision record",
+  internal: true,
   usage: `Usage: dld create-decision --id <DL-NNN> --title <title> [options]
 
 Create a decision record with status proposed and print its path.
@@ -8494,6 +8600,7 @@ Options:
 var createDirectoriesCommand = {
   name: "create-directories",
   summary: "Create the decisions directory structure from the config",
+  internal: true,
   usage: "Usage: dld create-directories\n\nCreate the decisions and records directories, and one per namespace.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8562,6 +8669,7 @@ function writeIndex(ctx, paths, content) {
 var createEmptyIndexCommand = {
   name: "create-empty-index",
   summary: "Write an INDEX.md with no decisions",
+  internal: true,
   usage: "Usage: dld create-empty-index\n\nWrite INDEX.md in the decisions directory with only the table header.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8577,6 +8685,7 @@ var createEmptyIndexCommand = {
 var detectSnapshotChangesCommand = {
   name: "detect-snapshot-changes",
   summary: "Report what changed since the last snapshot",
+  internal: true,
   usage: "Usage: dld detect-snapshot-changes\n\nPrint mode (full or incremental), new_decisions, modified_decisions and commit_range.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8589,7 +8698,14 @@ var detectSnapshotChangesCommand = {
 import { join as join11, relative as relative6, sep as sep3 } from "node:path";
 var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git",
+  // Agent configuration directories, which hold installed skills.
   ".claude",
+  ".agents",
+  ".agent",
+  ".codex",
+  ".cursor",
+  ".opencode",
+  ".pi",
   ".tessl",
   "node_modules",
   "vendor",
@@ -8668,6 +8784,7 @@ function formatAnnotation({ file, line, id }) {
 var findAnnotationsCommand = {
   name: "find-annotations",
   summary: "List every annotation in the codebase",
+  internal: true,
   usage: "Usage: dld find-annotations\n\nPrint <file>:<line>:<DL-NNN> for every annotation, one per line.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8683,6 +8800,7 @@ var findAnnotationsCommand = {
 var findCollisionsCommand = {
   name: "find-collisions",
   summary: "List locally added decisions whose IDs are taken",
+  internal: true,
   usage: `Usage: dld find-collisions [--base <ref>]
 
 Print <path>\\t<DL-NNN> for each decision added on this branch whose ID is taken on the base
@@ -8710,11 +8828,11 @@ var idNumber2 = (id) => Number.parseInt(id.slice(3), 10);
 function recordsChangedSinceAudit(ctx, { paths }) {
   const git = gitAt(ctx, paths.root);
   const stored = stateString(readStateSection(ctx, paths, "audit"), "commit_hash");
-  const commit = resolveStateCommit(git, stored);
-  if (commit === void 0) return void 0;
+  const commit2 = resolveStateCommit(git, stored);
+  if (commit2 === void 0) return void 0;
   const records = recordsPathspec(paths);
   return /* @__PURE__ */ new Set([
-    ...nulSeparated(git("diff", "-z", "--name-only", commit, "--", records)),
+    ...nulSeparated(git("diff", "-z", "--name-only", commit2, "--", records)),
     ...nulSeparated(git("ls-files", "-z", "--others", "--exclude-standard", "--", records))
   ]);
 }
@@ -8740,15 +8858,16 @@ function findMissingAmends(ctx, project, { all }) {
 }
 function updateAuditState(ctx, { paths }) {
   const timestamp = formatTimestamp(ctx.now());
-  const commit = shortHead(ctx, paths.root);
-  writeStateSection(ctx, paths, "audit", { last_run: timestamp, commit_hash: commit });
-  return { timestamp, commit };
+  const commit2 = shortHead(ctx, paths.root);
+  writeStateSection(ctx, paths, "audit", { last_run: timestamp, commit_hash: commit2 });
+  return { timestamp, commit: commit2 };
 }
 
 // src/cli/commands/find-missing-amends.ts
 var findMissingAmendsCommand = {
   name: "find-missing-amends",
   summary: "List decision IDs mentioned in a body but not declared",
+  internal: true,
   usage: `Usage: dld find-missing-amends [--all]
 
 Print <source-id>:<referenced-id> for each decision ID a record's body mentions without
@@ -8770,7 +8889,7 @@ Options:
 import { Buffer as Buffer2 } from "node:buffer";
 import { join as join12, posix as posix3 } from "node:path";
 var idPattern = (id, flags = "") => new RegExp(`${id}(?![0-9])`, flags);
-function changedFiles(ctx, paths, commit) {
+function changedFiles(ctx, paths, commit2) {
   return nulSeparated(
     gitAt(ctx, paths.root)(
       "diff",
@@ -8778,7 +8897,7 @@ function changedFiles(ctx, paths, commit) {
       "--find-renames",
       "--name-only",
       "--diff-filter=AMR",
-      commit
+      commit2
     )
   );
 }
@@ -8829,7 +8948,7 @@ function renameDecision(ctx, project, rename, base) {
 }
 function findStaleMentions(ctx, { paths }, planText, base) {
   const renames = parseRenamePlan(paths, planText);
-  if (renames.length === 0) return [];
+  if (renames.length === 0) throw new DldError("no rename plan on stdin.");
   verifyBase(ctx, paths, base);
   const decisions = `${decisionsPathspec(paths)}/`;
   const files = changedFiles(ctx, paths, mergeBase(ctx, paths, base)).flatMap((file) => {
@@ -8859,6 +8978,7 @@ function formatStaleMention({ file, line, oldId, newId, text }) {
 var findStaleMentionsCommand = {
   name: "find-stale-mentions",
   summary: "List remaining mentions of renamed decision IDs",
+  internal: true,
   usage: `Usage: dld find-stale-mentions --base <ref> < plan
 
 Read a rename plan (<path>\\t<DL-OLD>\\t<DL-NEW> per line) on standard input and print
@@ -9040,7 +9160,6 @@ var AGENTS_LAYOUT = {
   dir: ".agents/skills"
 };
 var LAYOUTS = [CLAUDE_LAYOUT, AGENTS_LAYOUT];
-var AGENTS_FIRST = ["AGENTS.md", "CLAUDE.md"];
 var HARNESSES = [
   {
     name: "claude",
@@ -9048,7 +9167,7 @@ var HARNESSES = [
     layout: CLAUDE_LAYOUT,
     rule: "claude-file",
     markers: [".claude", "CLAUDE.md"],
-    // @decision(DL-054) Any of the first three stops Claude Code from reading AGENTS.md.
+    // @decision(DL-054) @decision(DL-055)
     instructions: ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]
   },
   {
@@ -9073,7 +9192,9 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".cursor"],
-    instructions: ["AGENTS.md"]
+    // @decision(DL-061)
+    instructions: ["AGENTS.md", "CLAUDE.md"],
+    readsAll: true
   },
   {
     name: "opencode",
@@ -9081,7 +9202,8 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".opencode", "opencode.json", "opencode.jsonc"],
-    instructions: AGENTS_FIRST
+    // @decision(DL-061) OpenCode 2.x; 1.x also fell back to CLAUDE.md.
+    instructions: ["AGENTS.md"]
   },
   {
     name: "pi",
@@ -9089,7 +9211,7 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".pi"],
-    instructions: AGENTS_FIRST
+    instructions: ["AGENTS.md", "CLAUDE.md"]
   }
 ];
 var GENERIC_MARKERS = ["AGENTS.md", ".agents/skills"];
@@ -9256,20 +9378,23 @@ function removeEmptyParents(ctx, dir, paths) {
 }
 
 // src/generate/rule.ts
-import { dirname as dirname3, join as join15 } from "node:path";
+import { dirname as dirname3, join as join15, posix as posix4 } from "node:path";
 
 // templates/rules/dld-workflow.md
-var dld_workflow_default = "# DLD (Decision-Linked Development)\n\nThis project uses Decision-Linked Development. Decision records (DL-*.md) live in the `records/` subdirectory of the decisions directory set in `dld.config.yaml` (`decisions/` by default). High-level docs (INDEX.md, OVERVIEW.md, SNAPSHOT.md) live in the decisions directory.\n\n## Rules\n\n- When you encounter `@decision(DL-XXX)` annotations in code, read the referenced decision with the dld-lookup skill BEFORE modifying the annotated code.\n- ALWAYS look up and verify related decisions before modifying annotated code. Do not skip this step.\n- NEVER modify code in a way that contradicts an existing decision without first confirming with the user. If the change requires breaking a previous decision, a new decision must be recorded (with the dld-decide skill) that explicitly supersedes the old one. If it only partially modifies a previous decision, record it as an amendment instead.\n\n## Skills\n\n- dld-decide: record a new decision\n- dld-plan: break down a feature into multiple grouped decisions\n- dld-implement: implement proposed decisions\n- dld-lookup: query decisions by ID, tag, or code path\n- dld-adjust: adjust or update existing decisions\n- dld-audit: scan for drift between decisions and code\n- dld-snapshot: regenerate SNAPSHOT.md and OVERVIEW.md from the decision log\n- dld-status: a quick overview of the decision log state\n- dld-retrofit: generate decisions from an existing codebase\n- dld-reindex: resolve decision-ID collisions with the base branch (and open PRs) before rebasing\n";
+var dld_workflow_default = "# DLD (Decision-Linked Development)\n\nThis project uses Decision-Linked Development. Decision records (DL-*.md) live in the `records/` subdirectory of the decisions directory set in `dld.config.yaml` (`decisions/` by default). High-level docs (INDEX.md, OVERVIEW.md, SNAPSHOT.md) live in the decisions directory.\n\n## Rules\n\n- When you encounter `@decision(DL-XXX)` annotations in code, read the referenced decision with the dld-lookup skill BEFORE modifying the annotated code.\n- ALWAYS look up and verify related decisions before modifying annotated code. Do not skip this step.\n- NEVER modify code in a way that contradicts an existing decision without first confirming with the user. If the change requires breaking a previous decision, a new decision must be recorded (with the dld-decide skill) that explicitly supersedes the old one. If it only partially modifies a previous decision, record it as an amendment instead.\n\n## Skills\n\n- dld-decide: record a new decision\n- dld-plan: break down a feature into multiple grouped decisions\n- dld-implement: implement proposed decisions\n- dld-lookup: query decisions by ID, tag, or code path\n- dld-adjust: adjust or update existing decisions\n- dld-audit: scan for drift between decisions and code\n- dld-snapshot: regenerate SNAPSHOT.md and OVERVIEW.md from the decision log\n- dld-status: a quick overview of the decision log state\n- dld-retrofit: generate decisions from an existing codebase\n- dld-reindex: resolve decision-ID collisions with the base branch and open PRs\n";
 
 // src/generate/rule.ts
 var RULE_TEXT = dld_workflow_default;
 var RULE_SOURCE = "templates/rules/dld-workflow.md";
 var CLAUDE_RULE_FILE = ".claude/rules/dld-workflow.md";
 var AGENTS_RULE_FILE = ".agents/rules/dld-workflow.md";
+var CLAUDE_IMPORT_FILE = ".claude/CLAUDE.md";
 var BLOCK_START = "<!-- dld-kit:start -->";
 var BLOCK_END = "<!-- dld-kit:end -->";
 var AGENTS_MD = "AGENTS.md";
 var CLAUDE_MD = "CLAUDE.md";
+var CLAUDE_FILES = [CLAUDE_MD, CLAUDE_IMPORT_FILE, "CLAUDE.local.md"];
+var SHARED_CLAUDE_FILES = [CLAUDE_MD, CLAUDE_IMPORT_FILE];
 var RULE_FILES = {
   "claude-file": CLAUDE_RULE_FILE,
   "agents-file": AGENTS_RULE_FILE
@@ -9287,6 +9412,16 @@ function renderRuleFile(channel, text, version2) {
 
 ${text}`;
 }
+function renderImportFile(version2) {
+  return `<!-- Generated by dld-kit ${version2} for Claude Code: it loads AGENTS.md, which holds the DLD rule, through the import below. Do not edit: updating the rule overwrites this file. -->
+
+@../AGENTS.md
+`;
+}
+var IMPORT_STAMP = /^<!-- Generated by dld-kit (\S+) for Claude Code:/;
+function importFileVersion(content) {
+  return IMPORT_STAMP.exec(content)?.[1];
+}
 function renderBlock(text, version2) {
   const body = text.endsWith("\n") ? text.slice(0, -1) : text;
   return [BLOCK_START, notice(version2, "block"), "", ...body.split("\n"), BLOCK_END];
@@ -9335,20 +9470,41 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   let blockFiles = [AGENTS_MD, CLAUDE_MD].filter(
     (file) => regular(file) && findBlock(read(file), file) !== void 0
   );
-  if (blockFiles.length === 0 && channels.has("block")) blockFiles = [blockPlacement(ctx, root)];
+  if (blockFiles.length === 0 && channels.has("block")) {
+    const targets = harnesses.filter((h) => h.rule === "block");
+    const file = blockPlacement(ctx, root, targets);
+    blockFiles = [file];
+    plan.warnings.push(...switchWarnings(ctx, root, file, targets));
+  }
+  const pending = /* @__PURE__ */ new Map();
   for (const file of blockFiles) {
     const content = read(file);
     const updated = upsertBlock(content, renderBlock(text, version2), file);
+    pending.set(file, updated);
     if (updated !== content) plan.writes.push({ path: file, content: updated });
   }
+  const linkedDir = symlinkedPart(ctx, root, dirname3(CLAUDE_IMPORT_FILE));
+  const ownsImport = linkedDir === void 0 && importFileVersion(read(CLAUDE_IMPORT_FILE)) !== void 0;
+  const wantsImport = channels.has("claude-file") && blockFiles.includes(AGENTS_MD) && !SHARED_CLAUDE_FILES.some((file) => ctx.fs.lexists(join15(root, file)));
+  if (ownsImport || wantsImport && linkedDir === void 0) {
+    const content = renderImportFile(version2);
+    pending.set(CLAUDE_IMPORT_FILE, content);
+    if (read(CLAUDE_IMPORT_FILE) !== content) {
+      plan.writes.push({ path: CLAUDE_IMPORT_FILE, content });
+    }
+  } else if (wantsImport) {
+    plan.warnings.push(
+      `${linkedDir} is a symlink, so dld-kit does not write ${CLAUDE_IMPORT_FILE}, which would import AGENTS.md for Claude Code. Claude Code reads the rule block in AGENTS.md by itself only while the project has no CLAUDE.md, ${CLAUDE_IMPORT_FILE} or CLAUDE.local.md.`
+    );
+  }
   const withBlock = new Set(blockFiles.map(resolved));
-  const loads = (file) => withBlock.has(resolved(file));
-  const planned = new Set(blockFiles);
-  const reads = (harness) => instructionFile(ctx, root, harness, planned);
-  const readsBlock = (harness) => {
-    const file = reads(harness);
-    return file !== void 0 && loads(file);
+  const current = projectView(ctx, root);
+  const view = {
+    exists: (file) => pending.has(file) || current.exists(file),
+    read: (file) => pending.get(file) ?? current.read(file)
   };
+  const reads = (harness) => instructionFiles(harness, view)[0];
+  const readsBlock = (harness) => instructionFiles(harness, view).some((file) => withBlock.has(resolved(file)));
   const ownerOf = (channel) => HARNESSES.find((h) => h.rule === channel);
   const loadsBlock = (channel) => {
     const owner = ownerOf(channel);
@@ -9362,11 +9518,6 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
         reads
       )
     );
-    const claude = harnesses.find((h) => h.rule === "claude-file");
-    const blockWritten = plan.writes.some((write) => write.path === AGENTS_MD);
-    if (claude !== void 0 && reads(claude) === AGENTS_MD && readsBlock(claude) && blockWritten) {
-      plan.warnings.push(CLAUDE_READS_AGENTS_NOTE);
-    }
   }
   for (const channel of ["claude-file", "agents-file"]) {
     const path = RULE_FILES[channel];
@@ -9382,8 +9533,45 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   plan.warnings.push(...legacyBlockWarnings(read(CLAUDE_MD), ruleInstalled));
   return plan;
 }
-function instructionFile(ctx, root, harness, planned = /* @__PURE__ */ new Set()) {
-  return harness.instructions.find((file) => planned.has(file) || ctx.fs.exists(join15(root, file)));
+function projectView(ctx, root) {
+  const exists = (file) => ctx.fs.exists(join15(root, file));
+  return {
+    exists,
+    read: (file) => exists(file) && !ctx.fs.isDirectory(join15(root, file)) ? ctx.fs.readFile(join15(root, file)) : ""
+  };
+}
+function instructionFiles(harness, view) {
+  if (harness.name !== "claude") {
+    if (harness.readsAll) return harness.instructions.filter((f) => view.exists(f));
+    const file = harness.instructions.find((f) => view.exists(f));
+    return file === void 0 ? [] : [file];
+  }
+  const files = CLAUDE_FILES.filter((file) => view.exists(file));
+  if (files.length === 0) return view.exists(AGENTS_MD) ? [AGENTS_MD] : [];
+  const imported = files.some((file) => importsAgentsMd(view.read(file), file));
+  return imported && view.exists(AGENTS_MD) ? [...files, AGENTS_MD] : files;
+}
+var FENCE = /^ {0,3}(`{3,}|~{3,})/;
+function importsAgentsMd(content, file) {
+  const dir = posix4.dirname(file);
+  let fence;
+  for (const line of content.split(/\r?\n/)) {
+    const marker = FENCE.exec(line)?.[1];
+    if (marker !== void 0) {
+      if (fence === void 0) fence = marker;
+      else if (marker[0] === fence[0] && marker.length >= fence.length) fence = void 0;
+      continue;
+    }
+    if (fence !== void 0) continue;
+    const prose = line.replace(/`[^`]*`/g, "");
+    for (const match of prose.matchAll(/(?:^|\s)@(\S+)/g)) {
+      const target = match[1];
+      if (target !== void 0 && posix4.normalize(posix4.join(dir, target)) === AGENTS_MD) {
+        return true;
+      }
+    }
+  }
+  return false;
 }
 function blindWarnings(blockFiles, blind, reads) {
   const byFile = /* @__PURE__ */ new Map();
@@ -9397,18 +9585,30 @@ function blindWarnings(blockFiles, blind, reads) {
     return `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${one ? "reads" : "read"} ${file}. To cover ${one ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${file}, then run dld install-rule.`;
   });
 }
-var CLAUDE_READS_AGENTS_NOTE = "Claude Code reads the DLD rule from the AGENTS.md block, because the project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md. Adding one of those later stops Claude Code from reading AGENTS.md; run dld update then, which installs .claude/rules/dld-workflow.md.";
-function blockPlacement(ctx, root) {
-  for (const file of [AGENTS_MD, CLAUDE_MD]) {
-    if (ctx.fs.isRegularFile(join15(root, file))) return file;
+function blockPlacement(ctx, root, targets) {
+  if (ctx.fs.isRegularFile(join15(root, AGENTS_MD))) return AGENTS_MD;
+  const agentsLinked = ctx.fs.lexists(join15(root, AGENTS_MD));
+  if (ctx.fs.isRegularFile(join15(root, CLAUDE_MD)) && (agentsLinked || targets.every((h) => h.instructions.includes(CLAUDE_MD)))) {
+    return CLAUDE_MD;
   }
-  if (ctx.fs.lexists(join15(root, AGENTS_MD))) {
+  if (agentsLinked) {
     throw new DldError(
       `${AGENTS_MD} is not a regular file (a symlink?); dld-kit does not edit through it. Point it at a regular file or add the dld-kit block by hand.`
     );
   }
   return AGENTS_MD;
 }
+function switchWarnings(ctx, root, file, targets) {
+  if (file !== AGENTS_MD || ctx.fs.lexists(join15(root, AGENTS_MD))) return [];
+  const claudeMd = join15(root, CLAUDE_MD);
+  if (!ctx.fs.exists(claudeMd) || ctx.fs.isDirectory(claudeMd)) return [];
+  const switching = targets.filter((h) => !h.readsAll && h.instructions.includes(CLAUDE_MD));
+  if (switching.length === 0) return [];
+  const names = switching.map((h) => h.title).join(" and ");
+  return [
+    `dld-kit puts the rule block in a new AGENTS.md. ${names} will read AGENTS.md instead of CLAUDE.md from now on, so move anything ${switching.length === 1 ? "it needs" : "they need"} from CLAUDE.md into AGENTS.md.`
+  ];
+}
 var LEGACY_HEADING = /^## DLD \(Decision-Linked Development\)\s*$/;
 function legacyBlockWarnings(claudeMd, ruleInstalled) {
   const span = findBlock(claudeMd, CLAUDE_MD);
@@ -9423,32 +9623,43 @@ function loadsRule(ctx, root, harness) {
   if (harness.rule !== "block" && ctx.fs.exists(join15(root, RULE_FILES[harness.rule]))) {
     return true;
   }
-  const file = instructionFile(ctx, root, harness);
-  if (file === void 0) return false;
-  return ctx.fs.readFile(join15(root, file)).split(/\r?\n/).some((line) => line === BLOCK_START || LEGACY_HEADING.test(line));
+  const view = projectView(ctx, root);
+  return instructionFiles(harness, view).some(
+    (file) => view.read(file).split(/\r?\n/).some((line) => line === BLOCK_START || LEGACY_HEADING.test(line))
+  );
 }
 function sessionContext(ctx, root, harness, text = RULE_TEXT) {
   if (!ctx.fs.exists(join15(root, CONFIG_FILE))) return void 0;
   return loadsRule(ctx, root, harness) ? void 0 : text;
 }
-function refuseSymlinkedDir(ctx, root, dir) {
+function symlinkedPart(ctx, root, dir) {
   let current = "";
   for (const part of dir.split("/")) {
     current = current === "" ? part : `${current}/${part}`;
     const full = join15(root, current);
-    if (!ctx.fs.lexists(full)) return;
+    if (!ctx.fs.lexists(full)) return void 0;
     if (!ctx.fs.exists(full) || ctx.fs.realPath(full) !== join15(ctx.fs.realPath(root), current)) {
-      throw new DldError(
-        `${current} is a symlink; dld-kit does not install through symlinks. Replace it with a directory (dld-kit keeps each agent's copy separate).`
-      );
+      return current;
     }
   }
+  return void 0;
+}
+function refuseSymlinkedDir(ctx, root, dir) {
+  const linked = symlinkedPart(ctx, root, dir);
+  if (linked !== void 0) {
+    throw new DldError(
+      `${linked} is a symlink; dld-kit does not install through symlinks. Replace it with a directory (dld-kit keeps each agent's copy separate).`
+    );
+  }
 }
 function installedRuleChannels(ctx, root) {
   const channels = /* @__PURE__ */ new Set();
   for (const channel of ["claude-file", "agents-file"]) {
     if (ctx.fs.lexists(join15(root, RULE_FILES[channel]))) channels.add(channel);
   }
+  if (importFileVersion(projectView(ctx, root).read(CLAUDE_IMPORT_FILE)) !== void 0) {
+    channels.add("claude-file");
+  }
   for (const file of [AGENTS_MD, CLAUDE_MD]) {
     const path = join15(root, file);
     if (ctx.fs.isRegularFile(path) && findBlock(ctx.fs.readFile(path), file) !== void 0) {
@@ -9463,6 +9674,8 @@ function installedRuleStamps(ctx, root) {
   for (const file of [CLAUDE_RULE_FILE, AGENTS_RULE_FILE].filter(regular)) {
     stamps.push({ path: file, version: ruleVersion(ctx.fs.readFile(join15(root, file))) });
   }
+  const imported = importFileVersion(projectView(ctx, root).read(CLAUDE_IMPORT_FILE));
+  if (imported !== void 0) stamps.push({ path: CLAUDE_IMPORT_FILE, version: imported });
   for (const file of [AGENTS_MD, CLAUDE_MD].filter(regular)) {
     const content = ctx.fs.readFile(join15(root, file));
     const span = findBlock(content, file);
@@ -9705,8 +9918,13 @@ function printReport(io, report2) {
     io.stdout(`${dir}: ${written} written, ${removed} removed, ${unchanged} unchanged
 `);
   }
-  for (const path of report2.ruleWritten) io.stdout(`Wrote the DLD rule to ${path}
-`);
+  for (const path of report2.ruleWritten) {
+    io.stdout(
+      path === CLAUDE_IMPORT_FILE ? `Wrote ${path} (imports AGENTS.md for Claude Code)
+` : `Wrote the DLD rule to ${path}
+`
+    );
+  }
   for (const path of report2.ruleRemoved) io.stdout(`Removed ${path} (the rule is in the block)
 `);
   for (const warning of report2.warnings) io.stderr(`Warning: ${warning}
@@ -9835,6 +10053,7 @@ ${AGENT_HELP}
 var listTakenIdsCommand = {
   name: "list-taken-ids",
   summary: "List decision IDs taken on the base branch and in open PRs",
+  internal: true,
   usage: `Usage: dld list-taken-ids [--base <ref>]
 
 Print the decision IDs on the base branch and in records touched by open pull requests
@@ -9858,6 +10077,7 @@ Options:
 var nextIdCommand = {
   name: "next-id",
   summary: "Print the next sequential decision ID",
+  internal: true,
   usage: "Usage: dld next-id\n\nPrint the next decision ID, e.g. DL-004.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -9872,6 +10092,7 @@ var nextIdCommand = {
 var planRenamesCommand = {
   name: "plan-renames",
   summary: "Plan renames that resolve decision ID collisions",
+  internal: true,
   usage: `Usage: dld plan-renames [--base <ref>]
 
 Print <path>\\t<DL-OLD>\\t<DL-NEW> for each colliding local decision, assigning the next free
@@ -9895,6 +10116,7 @@ Options:
 var regenerateIndexCommand = {
   name: "regenerate-index",
   summary: "Rebuild INDEX.md from the decision records",
+  internal: true,
   usage: `Usage: dld regenerate-index [--include-base <ref>]
 
 Rebuild INDEX.md from every decision record.
@@ -9922,6 +10144,7 @@ Options:
 var renameDecisionCommand = {
   name: "rename-decision",
   summary: "Rename a local decision and rewrite its references",
+  internal: true,
   usage: `Usage: dld rename-decision --old <DL-OLD> --new <DL-NEW> --path <path> [--base <ref>]
 
 Rename a locally added decision with git mv, rewrite its id and references in changed
@@ -9957,6 +10180,7 @@ Options:
 var resolveBaseCommand = {
   name: "resolve-base",
   summary: "Print the base ref to check decision IDs against",
+  internal: true,
   usage: `Usage: dld resolve-base
 
 Print the current branch's upstream when it tracks a differently named branch, otherwise
@@ -10068,11 +10292,12 @@ ${AGENT_HELP}
 var updateAuditStateCommand = {
   name: "update-audit-state",
   summary: "Record the audit run in .dld-state.yaml",
+  internal: true,
   usage: "Usage: dld update-audit-state\n\nRecord the current time and HEAD commit as the last audit.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
-    const { timestamp, commit } = updateAuditState(ctx, loadProject(ctx));
-    io.stdout(`Audit state updated: ${timestamp} at ${commit}
+    const { timestamp, commit: commit2 } = updateAuditState(ctx, loadProject(ctx));
+    io.stdout(`Audit state updated: ${timestamp} at ${commit2}
 `);
     return EXIT_OK;
   }
@@ -10082,6 +10307,7 @@ var updateAuditStateCommand = {
 var updateSnapshotStateCommand = {
   name: "update-snapshot-state",
   summary: "Record the snapshot run in .dld-state.yaml",
+  internal: true,
   usage: `Usage: dld update-snapshot-state [artifact ...]
 
 Record the snapshot time, HEAD commit and highest accepted decision, with timestamps for
@@ -10093,8 +10319,8 @@ SNAPSHOT.md, OVERVIEW.md and any custom artifacts named.
       options: {},
       allowPositionals: true
     });
-    const { timestamp, commit, highest } = updateSnapshotState(ctx, loadProject(ctx), positionals);
-    io.stdout(`Snapshot state updated: ${timestamp} at ${commit} (through ${formatId(highest)})
+    const { timestamp, commit: commit2, highest } = updateSnapshotState(ctx, loadProject(ctx), positionals);
+    io.stdout(`Snapshot state updated: ${timestamp} at ${commit2} (through ${formatId(highest)})
 `);
     return EXIT_OK;
   }
@@ -10104,6 +10330,7 @@ SNAPSHOT.md, OVERVIEW.md and any custom artifacts named.
 var updateStatusCommand = {
   name: "update-status",
   summary: "Set a decision's status",
+  internal: true,
   usage: `Usage: dld update-status <DL-NNN> <${STATUSES.join("|")}>
 
 Change only the status line of a decision record.
@@ -10135,6 +10362,7 @@ var EXIT_MISSING = 1;
 var verifyAnnotationsCommand = {
   name: "verify-annotations",
   summary: "Check that decisions have annotations in the code",
+  internal: true,
   usage: "Usage: dld verify-annotations <DL-NNN> [DL-NNN ...]\n\nExit 0 if every decision has at least one annotation, 1 if any are missing.\n",
   run(args, io, ctx) {
     const { positionals: ids } = parseCommandArgs({
@@ -10188,11 +10416,19 @@ var COMMANDS = [
   findStaleMentionsCommand,
   commitReindexCommand
 ];
+var INTERNAL_HEADING = "Commands the skills run (internal; may change in minor releases)";
+var INTERNAL_NOTE = "Internal: the dld-kit skills run this command. Its name, arguments and output may change in a minor release.\n";
 function usage(commands) {
+  const list = (group) => group.map((c) => `  ${c.name.padEnd(25)} ${c.summary}`).join("\n");
+  const setup = commands.filter((c) => !c.internal);
+  const internal = commands.filter((c) => c.internal);
+  const sections = [`Setup commands:
+${list(setup)}`];
+  if (internal.length > 0) sections.push(`${INTERNAL_HEADING}:
+${list(internal)}`);
   return `Usage: dld <command> [options]
 
-Commands:
-${commands.map((c) => `  ${c.name.padEnd(20)} ${c.summary}`).join("\n")}
+${sections.join("\n\n")}
 
 Options:
   -h, --help     Show this help, or a command's help after its name
@@ -10231,7 +10467,8 @@ ${usage(commands)}`);
 }
 function report(error, command, io) {
   if (error instanceof HelpRequested) {
-    io.stdout(command.usage);
+    io.stdout(command.internal ? `${command.usage}
+${INTERNAL_NOTE}` : command.usage);
     return EXIT_OK;
   }
   if (error instanceof UsageError) {