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

package/README.md

@@ -36,7 +36,7 @@ This writes:
 
 - `dld.config.yaml`, `decisions/records/` and `decisions/INDEX.md`
 - the `dld-*` skills for each selected agent: `.claude/skills/` for Claude Code, `.agents/skills/` for the others
-- the always-on rule: `.claude/rules/dld-workflow.md` for Claude Code, `.agents/rules/dld-workflow.md` for Antigravity, and a block between `<!-- dld-kit:start -->` and `<!-- dld-kit:end -->` in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi
+- the always-on rule, once per agent: a block between `<!-- dld-kit:start -->` and `<!-- dld-kit:end -->` in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi, `.agents/rules/dld-workflow.md` for Antigravity, and `.claude/rules/dld-workflow.md` for Claude Code unless Claude Code already reads the block (see [Agents](#agents))
 
 `init` detects the agents from files in the project (`.claude/`, `.codex/`, `.cursor/`, `opencode.json`, `.pi/`, `AGENTS.md` and so on) and asks you to confirm the list. Options:
 
@@ -114,7 +114,7 @@ Channels can be combined. These combinations need care:
 
 | Agent | Skills (`dld init`) | Always-on rule (`dld init`, `/dld-init`) | Run a skill |
 |---|---|---|---|
-| Claude Code | `.claude/skills/` | `.claude/rules/dld-workflow.md` | `/dld-plan` |
+| Claude Code | `.claude/skills/` | `.claude/rules/dld-workflow.md`, or the block in `AGENTS.md` when the project has no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` | `/dld-plan` |
 | Antigravity | `.agents/skills/` | `.agents/rules/dld-workflow.md` | Ask for the dld-plan skill |
 | Codex | `.agents/skills/` | Block in `AGENTS.md` | Ask for the dld-plan skill |
 | Cursor | `.agents/skills/` | Block in `AGENTS.md` | Ask for the dld-plan skill |
@@ -124,6 +124,8 @@ Channels can be combined. These combinations need care:
 
 A new block goes into `AGENTS.md` if it exists, else into `CLAUDE.md` if that exists, else into a new `AGENTS.md`. Codex and Cursor read only `AGENTS.md`: when the block ends up in `CLAUDE.md`, `dld install-rule` warns and says how to move it.
 
+Each agent gets the rule once. Claude Code reads `AGENTS.md` only when the project has no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md`; in that case the block in `AGENTS.md` is its rule, and `init` prints a note. If one of those files is added later, run `npx dld-kit@latest update` (or `dld install-rule`), which then installs `.claude/rules/dld-workflow.md`.
+
 The examples below use Claude Code's `/dld-plan` form. In other agents, name the skill instead, e.g. "use the dld-plan skill to plan the retry feature".
 
 ## Get started
@@ -411,7 +413,7 @@ DLD is under active development. Feature requests and ideas are welcome — [ope
 
 ## Manual rule setup
 
-The always-on rule tells the agent to read a decision before changing code annotated with it. `/dld-init` installs it with `dld install-rule --agent <harness>`, which picks the file the harness loads: `.claude/rules/dld-workflow.md` for Claude Code, `.agents/rules/dld-workflow.md` for Antigravity, or a marked block in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi.
+The always-on rule tells the agent to read a decision before changing code annotated with it. `/dld-init` installs it with `dld install-rule --agent <harness>`, which picks the file the harness loads: `.claude/rules/dld-workflow.md` for Claude Code (unless it already reads the block in `AGENTS.md`), `.agents/rules/dld-workflow.md` for Antigravity, or a marked block in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi.
 
 To add it by hand instead, copy [`templates/rules/dld-workflow.md`](templates/rules/dld-workflow.md) into one of those files.
 

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.1";
+var version = "1.0.0-rc.2";
 
 // src/core/errors.ts
 var EXIT_ERROR = 1;
@@ -9048,7 +9048,8 @@ var HARNESSES = [
     layout: CLAUDE_LAYOUT,
     rule: "claude-file",
     markers: [".claude", "CLAUDE.md"],
-    instructions: ["CLAUDE.md", "AGENTS.md"]
+    // @decision(DL-054) Any of the first three stops Claude Code from reading AGENTS.md.
+    instructions: ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]
   },
   {
     name: "antigravity",
@@ -9342,18 +9343,30 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   }
   const withBlock = new Set(blockFiles.map(resolved));
   const loads = (file) => withBlock.has(resolved(file));
-  const readsBlock = (harness) => loads(instructionFile(ctx, root, harness));
+  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 ownerOf = (channel) => HARNESSES.find((h) => h.rule === channel);
   const loadsBlock = (channel) => {
     const owner = ownerOf(channel);
     return owner !== void 0 && readsBlock(owner);
   };
-  const blind = harnesses.filter((h) => h.rule === "block" && !readsBlock(h));
-  if (blockFiles.length > 0 && blind.length > 0) {
-    const names = blind.map((h) => h.title).join(" and ");
+  if (blockFiles.length > 0) {
     plan.warnings.push(
-      `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${blind.length === 1 ? "reads" : "read"} ${AGENTS_MD}. To cover ${blind.length === 1 ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${AGENTS_MD}, then run dld install-rule.`
+      ...blindWarnings(
+        blockFiles,
+        harnesses.filter((h) => h.rule === "block" && !readsBlock(h)),
+        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];
@@ -9369,10 +9382,22 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   plan.warnings.push(...legacyBlockWarnings(read(CLAUDE_MD), ruleInstalled));
   return plan;
 }
-function instructionFile(ctx, root, harness) {
-  const { instructions } = harness;
-  return instructions.find((file) => ctx.fs.exists(join15(root, file))) ?? instructions.at(-1) ?? AGENTS_MD;
+function instructionFile(ctx, root, harness, planned = /* @__PURE__ */ new Set()) {
+  return harness.instructions.find((file) => planned.has(file) || ctx.fs.exists(join15(root, file)));
+}
+function blindWarnings(blockFiles, blind, reads) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const harness of blind) {
+    const file = reads(harness) ?? harness.instructions[0] ?? AGENTS_MD;
+    byFile.set(file, [...byFile.get(file) ?? [], harness]);
+  }
+  return [...byFile].map(([file, harnesses]) => {
+    const names = harnesses.map((h) => h.title).join(" and ");
+    const one = harnesses.length === 1;
+    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;
@@ -9399,7 +9424,7 @@ function loadsRule(ctx, root, harness) {
     return true;
   }
   const file = instructionFile(ctx, root, harness);
-  if (!ctx.fs.exists(join15(root, file))) return false;
+  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));
 }
 function sessionContext(ctx, root, harness, text = RULE_TEXT) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dld-kit",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.2",
   "description": "Decision-Linked Development: record, link, and audit development decisions alongside code",
   "license": "MIT",
   "author": {

package/skills/dld-adjust/SKILL.md

@@ -3,7 +3,7 @@ name: dld-adjust
 description: Adjust or update existing decision records. Handles permission gating for accepted decisions and correctly interprets adjustment requests.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-adjust/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-audit/SKILL.md

@@ -3,7 +3,7 @@ name: dld-audit
 description: Scan for drift between decisions and code. Finds orphaned annotations, stale references, and undocumented changes.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-audit/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-audit-auto/SKILL.md

@@ -3,7 +3,7 @@ name: dld-audit-auto
 description: Autonomous audit — detects drift, fixes issues, and opens a PR. Designed for scheduled/CI execution without human interaction.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-audit-auto/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-common/SKILL.md

@@ -3,7 +3,7 @@ name: dld-common
 description: The dld CLI shared by the DLD skills. Not intended for direct invocation — the other DLD skills run it.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-common/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

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.1";
+var version = "1.0.0-rc.2";
 
 // src/core/errors.ts
 var EXIT_ERROR = 1;
@@ -9048,7 +9048,8 @@ var HARNESSES = [
     layout: CLAUDE_LAYOUT,
     rule: "claude-file",
     markers: [".claude", "CLAUDE.md"],
-    instructions: ["CLAUDE.md", "AGENTS.md"]
+    // @decision(DL-054) Any of the first three stops Claude Code from reading AGENTS.md.
+    instructions: ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]
   },
   {
     name: "antigravity",
@@ -9342,18 +9343,30 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   }
   const withBlock = new Set(blockFiles.map(resolved));
   const loads = (file) => withBlock.has(resolved(file));
-  const readsBlock = (harness) => loads(instructionFile(ctx, root, harness));
+  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 ownerOf = (channel) => HARNESSES.find((h) => h.rule === channel);
   const loadsBlock = (channel) => {
     const owner = ownerOf(channel);
     return owner !== void 0 && readsBlock(owner);
   };
-  const blind = harnesses.filter((h) => h.rule === "block" && !readsBlock(h));
-  if (blockFiles.length > 0 && blind.length > 0) {
-    const names = blind.map((h) => h.title).join(" and ");
+  if (blockFiles.length > 0) {
     plan.warnings.push(
-      `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${blind.length === 1 ? "reads" : "read"} ${AGENTS_MD}. To cover ${blind.length === 1 ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${AGENTS_MD}, then run dld install-rule.`
+      ...blindWarnings(
+        blockFiles,
+        harnesses.filter((h) => h.rule === "block" && !readsBlock(h)),
+        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];
@@ -9369,10 +9382,22 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   plan.warnings.push(...legacyBlockWarnings(read(CLAUDE_MD), ruleInstalled));
   return plan;
 }
-function instructionFile(ctx, root, harness) {
-  const { instructions } = harness;
-  return instructions.find((file) => ctx.fs.exists(join15(root, file))) ?? instructions.at(-1) ?? AGENTS_MD;
+function instructionFile(ctx, root, harness, planned = /* @__PURE__ */ new Set()) {
+  return harness.instructions.find((file) => planned.has(file) || ctx.fs.exists(join15(root, file)));
+}
+function blindWarnings(blockFiles, blind, reads) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const harness of blind) {
+    const file = reads(harness) ?? harness.instructions[0] ?? AGENTS_MD;
+    byFile.set(file, [...byFile.get(file) ?? [], harness]);
+  }
+  return [...byFile].map(([file, harnesses]) => {
+    const names = harnesses.map((h) => h.title).join(" and ");
+    const one = harnesses.length === 1;
+    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;
@@ -9399,7 +9424,7 @@ function loadsRule(ctx, root, harness) {
     return true;
   }
   const file = instructionFile(ctx, root, harness);
-  if (!ctx.fs.exists(join15(root, file))) return false;
+  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));
 }
 function sessionContext(ctx, root, harness, text = RULE_TEXT) {

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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- 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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- 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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- 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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- 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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- 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

@@ -3,7 +3,7 @@ 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.
 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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-reindex/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

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.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-retrofit/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-snapshot/SKILL.md

@@ -3,7 +3,7 @@ name: dld-snapshot
 description: Generate SNAPSHOT.md (detailed decision reference) and OVERVIEW.md (narrative synthesis with diagrams) from the decision log.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-snapshot/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-status/SKILL.md

@@ -3,7 +3,7 @@ name: dld-status
 description: Quick overview of the decision log state — counts by status, recent decisions, and run tracking info.
 compatibility: No external dependencies.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.2"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-status/SKILL.md. Do not edit: updating the skills overwrites this file. -->