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

package/skills/dld-common/scripts/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.3";
+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,17 +7927,17 @@ 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
@@ -7962,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) {
@@ -7990,7 +7991,7 @@ function openPrIds(ctx, paths, base) {
       "open",
       `--base=${prBase}`,
       "--json",
-      "files,headRefName,isCrossRepository",
+      "files,headRefName,headRefOid,isCrossRepository",
       "--limit",
       PR_LIMIT
     ]);
@@ -8004,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;
@@ -8027,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] : []
@@ -8095,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
   };
@@ -8190,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}
@@ -8202,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.");
@@ -8255,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);
   }
@@ -8326,24 +8417,35 @@ function skippedNotice(reason) {
 // src/cli/commands/commit-reindex.ts
 var commitReindexCommand = {
   name: "commit-reindex",
-  summary: "Squash the branch into one reindex commit",
+  summary: "Commit the renamed decisions",
   internal: true,
-  usage: `Usage: dld commit-reindex --base <ref> < plan
+  usage: `Usage: dld commit-reindex --base <ref> [--squash] < plan
 
-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.
+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.
+
+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;
   }
@@ -8726,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))
   ]);
 }
@@ -8756,9 +8858,9 @@ 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
@@ -8787,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",
@@ -8795,7 +8897,7 @@ function changedFiles(ctx, paths, commit) {
       "--find-renames",
       "--name-only",
       "--diff-filter=AMR",
-      commit
+      commit2
     )
   );
 }
@@ -8846,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) => {
@@ -9279,7 +9381,7 @@ function removeEmptyParents(ctx, dir, paths) {
 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;
@@ -10194,8 +10296,8 @@ var updateAuditStateCommand = {
   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;
   }
@@ -10217,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;
   }

package/skills/dld-decide/SKILL.md

@@ -3,7 +3,7 @@ name: dld-decide
 description: Record a single development decision as a markdown file with YAML frontmatter. Collects context, rationale, and code references interactively.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-decide/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-implement/SKILL.md

@@ -3,7 +3,7 @@ name: dld-implement
 description: Implement one or more proposed decisions. Makes code changes, adds `@decision` annotations, and updates decision status.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-implement/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-init/SKILL.md

@@ -3,7 +3,7 @@ name: dld-init
 description: Bootstrap DLD (Decision-Linked Development) in a repository. Creates dld.config.yaml, the decisions/ directory, and INDEX.md. Run once per project.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-init/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-lookup/SKILL.md

@@ -3,7 +3,7 @@ name: dld-lookup
 description: Look up decisions by ID, tag, code path, or keyword. IMPORTANT — use this proactively whenever you encounter `@decision` annotations in code you are about to read or modify.
 compatibility: No external dependencies.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-lookup/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-plan/SKILL.md

@@ -3,7 +3,7 @@ name: dld-plan
 description: Break down a feature into multiple decisions interactively. Creates a set of decision records grouped by a shared tag.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-plan/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-reindex/SKILL.md

@@ -1,23 +1,23 @@
 ---
 name: dld-reindex
-description: Resolve decision ID collisions between a local branch and the base branch (and open PRs) before rebasing. Renames colliding local decisions with git mv, rewrites cross-references and annotations, then squashes branch commits into a single rebase-clean reindex commit.
+description: Resolve decision ID collisions between a local branch and the base branch (and open PRs). Renames colliding local decisions with git mv, rewrites cross-references and annotations, and commits the renames on top of the branch. Squashes the branch only when the user asks.
 compatibility: Requires Node.js 20+ and git. Open-PR scanning additionally needs the `gh` CLI authenticated against a GitHub remote — the skill falls back gracefully when unavailable.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-reindex/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 
 # /dld-reindex — Resolve Decision ID Collisions
 
-You are helping the developer untangle decision ID collisions before they rebase. Two or more developers can draft `DL-NNN` decisions in parallel; once one of them lands on the base branch (or appears in an open PR), the others must rename their local copies to the next free ID. This skill handles that mechanically and produces a branch state that rebases cleanly.
+You are helping the developer untangle decision ID collisions. Two or more developers can draft `DL-NNN` decisions in parallel; once one of them lands on the base branch (or appears in an open PR), the others must rename their local copies to the next free ID. This skill does that mechanically.
 
-**This skill rewrites branch history.** That's not optional: if a colliding path (e.g. `decisions/records/DL-205.md`) was added by any commit on the branch, `git rebase` will hit an add/add conflict on that commit *before* it ever sees a later rename. The only fix is to ensure the colliding path never appears in the branch's history. The skill does this by squashing all branch commits since the merge-base into one reindex commit containing the renamed files.
+**By default the skill adds a commit and does not rewrite history.** The renames go into one new commit on top of the branch (or a few, for a large reindex). A merge only compares end states, so once the branch tip has the record at its new path, `git merge <base>` and merging the PR on GitHub (merge commit or squash merge) don't conflict on the records. A normal push is enough.
 
-If the branch has already been pushed, finishing the reindex will require a `--force-with-lease` push. The skill asks for explicit consent before rewriting history.
+**Squash mode, only when the user asks for it.** A rebase replays every branch commit, and the commit that added the colliding path (e.g. `decisions/records/DL-205.md`) hits an add/add conflict, whatever later commits do. If the user wants to rebase (or their repo uses GitHub's "Rebase and merge"), they can ask for a squash: the branch's commits since the merge-base become one reindex commit, and a pushed branch then needs `git push --force-with-lease`. Use squash mode only when the user's request says so (e.g. `/dld-reindex squash`, "squash it", "I want to rebase"). Never pick it on your own.
 
 ## Interaction style
 
-Use the `AskUserQuestion` tool when prompting for consent and at the finish step. Everything else is deterministic.
+Use the `AskUserQuestion` tool when asking about pushing and, in squash mode, for consent to rewrite history. Everything else is deterministic.
 
 **Do not redirect any command output to `/tmp` files.** The commands in this skill emit only what you need to act on; piping to `/tmp/*.txt`, `tee`-ing into scratch files, or stashing stderr separately is unnecessary and creates clutter outside the repo. If a command's output is too long to read in one go, narrow it (`| tail -N`, `| head -N`, or pass a more specific flag) rather than persisting it.
 
@@ -27,6 +27,8 @@ The commands below run the `dld` CLI bundled with the dld-common skill, and need
 
 This skill uses: `resolve-base`, `plan-renames`, `rename-decision`, `find-stale-mentions`, `commit-reindex`, `regenerate-index`.
 
+The steps below use shell variables (`BASE`, `PLAN`, `GROUP`). If your shell doesn't keep variables between commands, set them again in each command, or write the values out (e.g. pipe the plan lines with `printf '%s\t%s\t%s\n' ...`). `find-stale-mentions` and `commit-reindex` fail on an empty plan, so a lost variable shows up as an error.
+
 ## Prerequisites
 
 1. Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
@@ -44,7 +46,7 @@ BASE=$(node "<skill-dir>/../dld-common/scripts/dld.mjs" resolve-base)
 
 `resolve-base` prefers the branch's upstream when it tracks a *different* branch (the typical "feature → main" setup). It falls back to `origin/main` if the upstream is unset OR if the upstream tracks the same branch name as the current branch (i.e. it's just the remote copy of this same branch, not a useful collision base).
 
-The user may pass an explicit base when invoking the skill (e.g. `/dld-reindex origin/develop`) — honor it if present.
+The user may pass an explicit base when invoking the skill (e.g. `/dld-reindex origin/develop`) — honor it if present. The word `squash` is not a base: it selects squash mode (`/dld-reindex squash origin/develop` does both).
 
 ## Step 2: Plan the renames
 
@@ -61,17 +63,26 @@ Output is tab-separated, one rename per line:
 
 If the output is empty, exit with:
 
-> No ID collisions detected. Safe to rebase onto `$BASE`.
+> No ID collisions with `$BASE` or open PRs.
 
 `plan-renames` may print a stderr note like `[dld-reindex] open PRs not scanned: gh CLI not installed`. **Always surface this to the user** so they know the renamed IDs were chosen against base-branch state only and may still collide with an open PR.
 
+**Check that each rename is a real collision.** For each plan line, compare the local record with the base's record of the same ID: `git show "$BASE:<path>"`, or, when the base keeps it in another namespace directory, find it with `git ls-tree -r --name-only "$BASE" | grep '/DL-205\.md$'`. If they are the same decision (same title and substance, give or take later edits), the branch got it from a PR that has since merged into the base, typically a decisions PR this branch was stacked on that was squash- or rebase-merged. Don't rename it. Stop and tell the user to merge the base into the branch first (`git merge $BASE`; if INDEX.md conflicts, `node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index` and `git add` it), then run `/dld-reindex` again.
+
+A record this branch got from an open PR it is stacked on (an implementation branch cut from a decisions PR) is not a collision with that PR: it is the same decision. This needs the PR's head commit locally, which the `git fetch origin` above provides; a PR from a fork whose head isn't fetched still counts as a collision.
+
 The underlying helpers (`find-collisions`, `list-taken-ids`) remain available for debugging, but the SKILL flow always goes through `plan-renames`.
 
-## Step 3: Get explicit consent for the history rewrite
+## Step 3: Choose how to commit
+
+**Default mode (no squash requested).** Don't ask for consent; the renames are new commits the user can review or revert. Decide how many commits to make:
 
-Show the user the rename plan and the implication. Use `AskUserQuestion`:
+- **One commit** for the whole plan. This is the normal case.
+- **Several commits** when the reindex is large: many renames, or renames that rewrite many files (lots of annotations, amendments, supersedes or references between the renamed decisions). Each commit holds one decision, or a group of related ones (e.g. a decision and the local decisions that amend or supersede it). Say in a line which groups you chose.
 
-> Resolving these collisions requires rewriting branch history. I will squash the N commits since `<merge-base>` into a single reindex commit. The original commit subjects will be preserved in the new commit body. If the branch has already been pushed, finishing will require `git push --force-with-lease`. How should I proceed?
+**Squash mode (the user asked for it).** Show the rename plan and the implication, then use `AskUserQuestion`:
+
+> Squashing rewrites branch history. I will squash the N commits since `<merge-base>` into a single reindex commit. The original commit subjects will be preserved in the new commit body. If the branch has already been pushed, finishing will require `git push --force-with-lease`. How should I proceed?
 
 Options:
 - **Rewrite and force-push** — agent applies renames, squashes, commits, and runs `git push --force-with-lease`.
@@ -82,7 +93,14 @@ If the user cancels, exit without touching anything.
 
 ## Step 4: Apply renames
 
-For each line in the plan, call:
+Run steps 4 to 6 once for the whole plan, or, in default mode, once per group when you split the work. Put the lines you are working on in `GROUP`, in the plan's format. For a single commit or a squash, that's the whole plan; for a group, pick its lines by old ID:
+
+```bash
+GROUP="$PLAN"                                          # whole plan
+GROUP=$(printf '%s\n' "$PLAN" | grep -E $'\t(DL-205|DL-207)\t')  # one group
+```
+
+For each line in the plan (or group), call:
 
 ```bash
 node "<skill-dir>/../dld-common/scripts/dld.mjs" rename-decision --old DL-OLD --new DL-NEW --path <relative-path> --base "$BASE"
@@ -102,10 +120,10 @@ The substitution is digit-aware: renaming `DL-100` will not accidentally rewrite
 
 ## Step 5: Review plain-text DL-OLD mentions
 
-After all renames are applied (but before the squash), find any remaining bare `DL-OLD` references in non-decision changed files:
+After the renames are applied (and before committing), find any remaining bare `DL-OLD` references in non-decision changed files:
 
 ```bash
-echo "$PLAN" | node "<skill-dir>/../dld-common/scripts/dld.mjs" find-stale-mentions --base "$BASE"
+echo "$GROUP" | node "<skill-dir>/../dld-common/scripts/dld.mjs" find-stale-mentions --base "$BASE"
 ```
 
 Output is tab-separated, one match per line: `<path>\t<line>\t<DL-OLD>\t<DL-NEW>\t<line-content>`. Empty output means nothing to review.
@@ -119,12 +137,25 @@ For each match:
 
 Surface the list of matches to the user with your verdicts before you finish, so they can sanity-check the judgment calls.
 
-## Step 6: Squash and commit
+## Step 6: Commit
+
+**Do not use `git add -A` or `git commit -a` anywhere in this flow.** Use only `commit-reindex` to commit.
+
+**Default mode.** Regenerate INDEX.md so it lists the new IDs, then commit:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+echo "$GROUP" | node "<skill-dir>/../dld-common/scripts/dld.mjs" commit-reindex --base "$BASE"
+```
+
+`commit-reindex` checks that every renamed file exists, stages the plan's old and new paths plus every tracked file changed since HEAD (the renames, the rewritten references and annotations, your step 5 edits, INDEX.md), and commits on top of HEAD. Untracked files are not staged. The message lists the group's renames. If the commit fails (e.g. a hook rejects it), the index is restored and HEAD has not moved.
 
-Pipe the rename plan into `commit-reindex`:
+If you split the work, go back to step 4 for the next group.
+
+**Squash mode.** Pipe the whole rename plan into `commit-reindex --squash`:
 
 ```bash
-echo "$PLAN" | node "<skill-dir>/../dld-common/scripts/dld.mjs" commit-reindex --base "$BASE"
+echo "$PLAN" | node "<skill-dir>/../dld-common/scripts/dld.mjs" commit-reindex --base "$BASE" --squash
 ```
 
 This:
@@ -135,11 +166,19 @@ This:
 4. Stages **only** an explicit path list derived from the original branch diff and the rename plan — the old paths (for deletions), the new paths (for additions), every other file the branch touched. Untracked unrelated paths (e.g. `.claude/worktrees`, scratch files, in-progress edits to unrelated files) are deliberately NOT swept in.
 5. Commits with a templated message that lists the renames in the subject and preserves the original branch commits' subjects in the body.
 
-**Do not use `git add -A` or `git commit -a` anywhere in this flow.** Use only `commit-reindex` to commit. Targeting paths explicitly is the whole point of this step.
+## Step 7: Push
 
-## Step 7: Push (if the user chose force-push)
+**Default mode.** Use `AskUserQuestion` to ask whether to push now (options: **Push** / **Don't push**). If yes:
 
-If step 3's answer was "Rewrite and force-push":
+```bash
+if git rev-parse --verify --quiet "@{upstream}" >/dev/null; then
+  git push
+else
+  git push -u origin HEAD
+fi
+```
+
+**Squash mode.** If step 3's answer was "Rewrite and force-push":
 
 ```bash
 if git rev-parse --verify --quiet "@{upstream}" >/dev/null; then
@@ -157,8 +196,16 @@ Print:
 
 - The renames table.
 - The stderr note from step 2 if `gh` was skipped.
-- The number of commits squashed.
-- The next steps:
+- The commits created (default mode), or the number of commits squashed (squash mode).
+- The next steps.
+
+Default mode:
+
+> 1. Bring in the base when you need it: `git merge $BASE`, or merge the PR as usual.
+> 2. If INDEX.md conflicts (both sides added rows), run `node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index`, then `git add` INDEX.md and finish the merge.
+> 3. Don't rebase this branch onto `$BASE`: its earlier commits still add the old paths and will conflict. To rebase anyway, before you merge the base, drop the reindex commits (`git reset --keep HEAD~N`, N = the number of reindex commits) and run `/dld-reindex squash`.
+
+Squash mode:
 
 > 1. `git rebase $BASE`
 > 2. `node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index` (to repopulate INDEX.md with the renamed locals — the reindex commit intentionally leaves INDEX.md alone to keep the rebase conflict-free; INDEX.md is missing the renamed rows until you regenerate)
@@ -169,5 +216,5 @@ The skill never rebases or merges — that is always the user's call.
 ## Out of scope
 
 - **Already-conflicted rebases.** If the user is mid-rebase with conflicts, tell them to `git rebase --abort` first and re-run this skill.
-- **Preserving per-commit granularity.** The squash trades original commit boundaries for a deterministic rewrite. A future `--preserve-history` flag could perform a cherry-pick walk that rewrites each commit individually, but the edge cases (commits modifying an already-renamed file, merge commits, partial reruns) make it materially more complex than the squash.
+- **Rewriting each commit in place.** Neither mode rewrites the branch commit by commit (a cherry-pick walk); the edge cases (commits modifying an already-renamed file, merge commits, partial reruns) make it much more complex than adding a commit or squashing.
 - **Cross-namespace ID reconciliation** in namespaced projects. IDs are assumed globally unique across namespaces, matching `next-id`.

package/skills/dld-retrofit/SKILL.md

@@ -3,7 +3,7 @@ name: dld-retrofit
 description: Bootstrap DLD decisions from an existing codebase. Analyzes code to infer rationale, generates decision records, and adds `@decision` annotations.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.3"
+  dld-kit-version: "1.0.0-rc.4"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-retrofit/SKILL.md. Do not edit: updating the skills overwrites this file. -->