dld-kit 1.0.0-rc.1

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "dld-kit",
+  "version": "1.0.0-rc.1",
+  "description": "Decision-Linked Development: record, link, and audit development decisions alongside code",
+  "license": "MIT",
+  "author": {
+    "name": "Jimmy Utterström",
+    "url": "https://github.com/jimutt"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jimutt/dld-kit.git"
+  },
+  "homepage": "https://github.com/jimutt/dld-kit#readme",
+  "keywords": [
+    "dld",
+    "decision-records",
+    "agent-skills",
+    "cli",
+    "pi-package"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "dld": "dist/dld.mjs"
+  },
+  "files": [
+    "dist/dld.mjs",
+    "skills/",
+    "templates/skills/",
+    "templates/rules/"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "generate": "bun scripts/generate.ts",
+    "check:generated": "bun scripts/generate.ts --check",
+    "prepack": "npm run build",
+    "version": "npm run generate && git add skills .claude/skills .claude/rules claude-plugin .claude-plugin plugin.json .agents/plugins .github/plugin",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.src.json",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "npm run check:generated && npm run test:unit && npm run test:cli",
+    "test:unit": "bun test src",
+    "test:coverage": "bun test --coverage src",
+    "test:cli": "npm run build && bun test tests/cli",
+    "check:pack": "node scripts/check-pack.mjs",
+    "check:installers": "node scripts/check-installers.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.14",
+    "@types/bun": "1.4.2",
+    "@types/node": "20.19.43",
+    "esbuild": "0.28.2",
+    "typescript": "7.0.2",
+    "yaml": "2.9.1"
+  }
+}

package/skills/dld-adjust/SKILL.md

@@ -0,0 +1,142 @@
+---
+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"
+---
+<!-- Generated by dld-kit from templates/skills/dld-adjust/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-adjust — Adjust a Decision
+
+You are helping the developer adjust one or more existing decision records. Your job is to apply their requested changes accurately and minimally.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.
+
+This skill uses: `regenerate-index`.
+
+## Prerequisites
+
+Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+
+## Read project context
+
+This skill is typically invoked mid-session after `/dld-plan`, `/dld-decide`, or during `/dld-implement`, so the project context and decision content are likely already in your conversation context. Only read these if you don't already have the information:
+
+1. `dld.config.yaml` — project structure (flat vs namespaced, decisions directory)
+2. The target decision file(s) — decision records (`DL-*.md`) live in the `records/` subdirectory under the decisions directory
+
+## Step 1: Identify the decision(s)
+
+The user may specify decision IDs explicitly (e.g., `/dld-adjust DL-005`), but often they won't — this skill is typically used right after `/dld-plan`, `/dld-decide`, or during `/dld-implement`, so the decisions are already part of the current conversation context.
+
+- **Explicit IDs provided** — use those directly.
+- **No IDs provided** — infer which decision(s) the user is referring to from the conversation context. If decisions were recently created or discussed in this session, assume those are the target. If it's still ambiguous, ask using `AskUserQuestion`.
+
+Find and read each decision file. If a decision ID is not found, report the error and continue with any remaining valid IDs.
+
+## Step 2: Determine if confirmation is needed
+
+For each decision, check whether editing requires user confirmation:
+
+### Proposed decisions (`status: proposed`)
+
+Edit freely. No confirmation needed — proposed decisions are mutable by convention.
+
+### Accepted decisions (`status: accepted`)
+
+Check if the decision file has been committed and pushed to the remote:
+
+```bash
+# Get the last commit hash for the decision file
+LAST_COMMIT=$(git log --format=%H -1 -- <path-to-decision-file>)
+
+# Check if that commit exists on any remote branch
+git branch -r --contains "$LAST_COMMIT" 2>/dev/null
+```
+
+- **Not yet pushed** (commit not on any remote branch, file is uncommitted, or file is untracked) — edit freely. It is still local work-in-progress.
+- **Pushed to remote** — this decision has been published. Use `AskUserQuestion` to present options:
+  1. **Edit anyway** — modify the accepted decision directly (breaks immutability convention)
+  2. **Supersede instead** — record a new decision via `/dld-decide` that supersedes this one
+  3. **Cancel** — do nothing
+
+If the user chooses to supersede, direct them to `/dld-decide` and stop. If they cancel, stop. Only proceed with editing if they explicitly choose to edit anyway.
+
+### Deprecated or superseded decisions
+
+These are historical records. Ask for confirmation before editing — modifying historical decisions is unusual.
+
+## Step 3: Collect the adjustment request
+
+If the user provided the adjustment alongside the skill invocation (e.g., `/dld-adjust DL-005 remove the mention of Java records`), use that directly.
+
+Otherwise, ask what changes they want to make.
+
+Read the current decision content so you understand the full context of what you are working with.
+
+## Step 4: Apply the changes
+
+### CRITICAL — How to interpret adjustment requests
+
+AI agents consistently misinterpret adjustment requests. Follow these rules exactly:
+
+**"Remove X" means DELETE the content about X.**
+Do NOT replace it with "We decided not to use X" or "We chose against X" or any other negative phrasing. Simply remove the sentences, bullet points, or paragraphs that mention X. The goal is a clean decision record that reads as if X was never discussed.
+
+**"Change X to Y" means REPLACE the content.**
+Find where X is described and replace it with Y. Do not add explanatory text about the change.
+
+**"Add X" means INSERT new content.**
+Add the new content in the appropriate section. Do not add meta-commentary about it being an addition.
+
+**General principle:** The decision record should always read as a clean, coherent document. Never add editorial notes like "Updated on...", "Previously we...", "This was changed from...", or "We decided against...". The record captures the current state of the decision, not a changelog of edits.
+
+**Examples of WRONG vs RIGHT:**
+
+User says: *"Remove the mention of Java records from DL-005"*
+
+- WRONG: Replacing "We will use Java records for DTOs" with "We decided not to use Java records for DTOs"
+- RIGHT: Deleting the sentence "We will use Java records for DTOs" entirely (and any related sentences about Java records)
+
+User says: *"Change the retry count from 3 to 5"*
+
+- WRONG: Adding "Originally 3 retries, changed to 5 retries because..."
+- RIGHT: Replacing "3 retries" with "5 retries" wherever it appears in the decision
+
+User says: *"Remove the part about caching"*
+
+- WRONG: "We considered caching but decided it is not relevant to this decision"
+- RIGHT: Delete all sentences and paragraphs about caching. Adjust surrounding text so the document flows naturally.
+
+### Applying edits
+
+1. Read the full decision file
+2. Apply the requested changes to the markdown body (and frontmatter fields like title or tags if affected)
+3. Write the updated file
+4. Show the user a brief summary of what changed
+
+If multiple decisions are being adjusted, process them one at a time.
+
+## Step 5: Regenerate INDEX.md
+
+If any decision titles or metadata changed:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+```
+
+## Step 6: Suggest next steps
+
+> Adjusted **DL-NNN**: [brief description of what changed]
+>
+> Next steps:
+> - `/dld-lookup DL-NNN` — review the updated decision
+> - `/dld-implement DL-NNN` — implement if the decision is proposed
+> - `/dld-snapshot` — regenerate overview docs to reflect the update

package/skills/dld-audit/SKILL.md

@@ -0,0 +1,162 @@
+---
+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"
+---
+<!-- Generated by dld-kit from templates/skills/dld-audit/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-audit — Audit Decision-Code Drift
+
+You are scanning the codebase for drift between decision records and code annotations. This helps catch situations where code evolved but decisions weren't updated.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.
+
+This skill uses: `find-annotations`, `find-missing-amends`, `update-audit-state`.
+
+## Prerequisites
+
+Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+
+## Audit Steps
+
+### 1. Collect all annotations in code
+
+Run `find-annotations`:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" find-annotations
+```
+
+This outputs lines in the format `<file>:<line>:<DL-NNN>`, one per annotation occurrence.
+
+### 2. Collect all decision records
+
+Read all `DL-*.md` files in the records subdirectory (`decisions/records/`). For each, note:
+- The ID
+- The status
+- The code references listed in the frontmatter
+
+### 3. Check for issues
+
+Perform these drift checks:
+
+#### a) Orphaned annotations
+
+Annotations in code that reference non-existent decision IDs. These indicate decisions that were deleted or IDs that were mistyped.
+
+#### b) Annotations referencing non-accepted decisions
+
+Annotations referencing decisions with status `deprecated` or `superseded`. Code is still tied to a decision that's no longer active.
+
+#### b2) Annotations referencing amended decisions
+
+Annotations referencing decisions that have been amended by a newer decision (check all decisions for `amends` fields that reference this ID). This is **informational, not an error** — the original decision is still active, but the developer should be aware of the amendment. Surface these as notes, not issues.
+
+#### c) Stale references in decisions
+
+Decision records whose `references` list code paths that no longer exist in the repository. Use file existence checks.
+
+#### d) Unreferenced code changes (if previous audit exists)
+
+If `decisions/.dld-state.yaml` exists and has an `audit.commit_hash`, find files that:
+1. Contain `@decision` annotations
+2. Were modified since the last audit commit
+
+First, verify the commit is reachable:
+```bash
+git cat-file -t <commit_hash> 2>/dev/null
+```
+
+If the commit is unreachable (e.g., after a rebase or shallow clone), skip this check and note it in the report:
+> **Note:** Previous audit commit `<hash>` is not reachable in current history. Skipping changed-file detection. This can happen after a rebase or shallow clone.
+
+If the commit is reachable:
+```bash
+git diff --name-only <commit_hash>..HEAD
+```
+
+Cross-reference this list with annotated files. Files that changed but whose associated decisions weren't updated may indicate undocumented drift.
+
+#### e) Missing amendment relationships
+
+**This check is mandatory — do not skip it.** Run `find-missing-amends` to get initial candidates:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" find-missing-amends
+```
+
+This outputs lines in the format `<source-id>:<referenced-id>` — decisions whose body references another decision ID that isn't listed in their `supersedes` or `amends` fields. Not every candidate is a missing amendment — some are just informational references (e.g., "this is similar to DL-005").
+
+By default the command only emits candidates whose source decision file changed since the last audit (recorded in `.dld-state.yaml`), so references the agent has already evaluated and judged informational don't keep resurfacing. To force a full rescan — useful for cold starts or manual deep audits — pass `--all`:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" find-missing-amends --all
+```
+
+For each candidate, read the source decision's body and evaluate whether the reference describes a partial modification of the referenced decision. Look for language like: "supersedes the X portions of", "changes the Y behavior from DL-Z", "replaces the approach in DL-Z for...", "modifies how DL-Z handles...". If so, flag it as a missing amendment.
+
+#### f) Decisions without annotations
+
+`accepted` decisions that have code references in their frontmatter but no corresponding `@decision` annotations found in the code. The references claim code is linked, but the annotations are missing.
+
+### 4. Report findings
+
+Present findings grouped by severity:
+
+```
+## Audit Report
+
+### Issues Found
+
+#### Orphaned Annotations
+- `src/billing/vat.ts:42` references `DL-099` — decision does not exist
+
+#### Stale References
+- **DL-012** references `src/billing/old-vat.ts` — file does not exist
+
+#### Deprecated/Superseded References
+- `src/auth/login.ts:15` references `DL-003` (status: superseded by DL-012)
+
+#### Amended Decisions (informational)
+- `src/billing/vat.ts:42` references `DL-003` — amended by DL-012. Verify code aligns with the amendment.
+
+#### Modified Annotated Files (since last audit)
+- `src/billing/vat.ts` — modified, contains `@decision(DL-012)`. Review if decision needs updating.
+
+### Summary
+- **X** orphaned annotations
+- **Y** stale references
+- **Z** annotated files modified since last audit
+
+### Suggested Remediation
+- Fix orphaned annotation at `src/billing/vat.ts:42` — update to correct ID or remove
+- Update DL-012 references — remove `src/billing/old-vat.ts`
+- Review `src/billing/vat.ts` changes — consider `/dld-decide` if behavior changed
+```
+
+If no issues are found:
+```
+## Audit Report
+
+No drift detected. All annotations reference valid, accepted decisions. All decision references point to existing code.
+```
+
+### 5. Update audit state
+
+After the audit completes (regardless of findings):
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" update-audit-state
+```
+
+### 6. Suggest next steps
+
+> Audit complete. **N** issue(s) found.
+>
+> Next steps:
+> - Fix any orphaned or stale references identified above
+> - `/dld-decide` — record new decisions for undocumented changes
+> - `/dld-snapshot` — regenerate the spec projection
+> - `/dld-status` — view overall decision log state

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

@@ -0,0 +1,172 @@
+---
+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"
+---
+<!-- Generated by dld-kit from templates/skills/dld-audit-auto/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-audit-auto — Autonomous Audit & Fix
+
+You are running an autonomous audit of the decision-code relationship. Unlike the interactive `/dld-audit`, you **detect issues and fix them** without asking for human input. Your output is a branch with fixes and a PR for review.
+
+**This skill is designed for unattended execution** — scheduled runs, CI pipelines, or autonomous agent sessions. Do not ask questions or wait for user input.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`.
+
+This skill uses: `find-annotations`, `find-missing-amends`, `regenerate-index`, `update-audit-state`.
+
+## Prerequisites
+
+1. Check that `dld.config.yaml` exists at the repo root. If not, exit with a clear error message.
+2. Verify the working tree is clean (`git status --porcelain` should be empty). If not, exit — do not mix audit fixes with uncommitted work.
+
+## Step 1: Create audit branch
+
+```bash
+git checkout -b dld/audit-$(date +%Y%m%d-%H%M%S)
+```
+
+## Step 2: Run the full audit
+
+Perform all the same checks as `/dld-audit`:
+
+### a) Collect annotations and decision records
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" find-annotations
+```
+
+Read all `DL-*.md` files in the records subdirectory (`decisions/records/`). Note each decision's ID, status, and code references.
+
+### b) Detect issues
+
+Check for all drift categories:
+
+1. **Orphaned annotations** — annotations referencing non-existent decision IDs
+2. **Annotations referencing non-accepted decisions** — code tied to deprecated or superseded decisions
+3. **Stale references in decisions** — frontmatter references to files that no longer exist
+4. **Unreferenced code changes** — annotated files modified since last audit (if previous audit state exists)
+5. **Decisions without annotations** — accepted decisions with code references but no corresponding annotations in code
+6. **Missing amendment relationships** — decisions whose body references modifying part of a previous decision but have an empty `amends` field
+
+For check (4), if `decisions/.dld-state.yaml` exists with an `audit.commit_hash`, first verify reachability:
+```bash
+git cat-file -t <commit_hash> 2>/dev/null
+```
+If unreachable (e.g., after rebase or shallow clone), skip check (4) and note it in the PR description. If reachable, use `git diff --name-only <commit_hash>..HEAD` to find changed files and cross-reference with annotated files.
+
+## Step 3: Fix issues
+
+Apply fixes for each issue category. Use judgment on what can be safely fixed automatically vs. what should only be flagged in the PR description.
+
+### Hard rule: never edit the body of an accepted decision
+
+The narrative body of an accepted decision (Context, Decision, Rationale, Consequences, and any other prose sections) is **immutable**. An audit must never rewrite, refine, "clean up", or otherwise modify it.
+
+The only changes an audit may make to an accepted decision are housekeeping updates to specific frontmatter fields — `references`, `amends`, `superseded_by`, and similar relational metadata — plus adding or fixing `@decision` annotations in code.
+
+If drift suggests the substance of an accepted decision is no longer accurate, or that code has evolved beyond what the decision describes, **do not modify the original record**. Instead, create a **new decision** (status `accepted`, since the code already exists) that captures the new rationale and uses `supersedes` or `amends` to link back to the prior one. The original stays as-is to preserve the historical record of why things were done that way at the time.
+
+### Auto-fixable (apply these directly):
+
+**Orphaned annotations** — If the annotation has an obvious typo (e.g., `DL-01` where `DL-001` exists), fix it. If the referenced ID is completely unknown, remove the annotation and note the removal in the commit message.
+
+**Stale references in decisions** — Remove file paths from the decision's `references` field that no longer exist. If the file was renamed/moved (detectable via `git log --follow --diff-filter=R`), update the path instead of removing.
+
+**Annotations referencing superseded decisions** — Update the annotation to reference the superseding decision (read the `supersedes` field of the newer decision to find the chain). For deprecated decisions, remove the annotation.
+
+**Annotations referencing amended decisions** — Do **not** rewrite or remove these annotations. The original decision is still active. Instead, note the amendment relationship in the PR description so reviewers can verify the code aligns with the amendment.
+
+**Missing amendment relationships** — Run `node "<skill-dir>/../dld-common/scripts/dld.mjs" find-missing-amends` to get candidates. The command only emits candidates whose source decision changed since the last audit, so re-runs stay focused on new work. For each candidate, read the source decision's body and determine if it describes a partial modification. If so, add the referenced ID to the `amends` field. Flag prominently in the PR for review, since this is an inferred relationship.
+
+**Decisions without annotations** — If an accepted decision has code references but no annotations, and the referenced files exist, add the missing `@decision(DL-NNN)` annotations to the referenced code locations.
+
+### Best-effort fixes (apply, but flag prominently for review):
+
+**Unreferenced code changes** — Annotated files that were modified since the last audit without a corresponding decision update. These represent changes made outside the DLD process. Try to resolve them:
+
+1. **Check commit messages** — Read the commits that modified the file (`git log --oneline <last_audit_hash>..HEAD -- <file>`). Look for context about what changed and why.
+2. **Look up referenced tickets** — If commit messages reference a ticket (e.g., Jira, Linear, GitHub issue), try to look it up using available tools (MCP servers, `gh` CLI, etc.) to gather additional context about the change.
+3. **Assess the impact** — Read the current code and the associated decision(s). Determine whether:
+   - The existing decision is still accurate (the change was compatible — no action needed)
+   - The change introduced new or different behavior/rationale that is not fully captured by the existing decision (a **new decision** is needed)
+4. **Create a new decision when needed** — Per the hard rule above, never edit the body of the existing accepted decision to absorb the new behavior. Instead, create a new decision using the standard scripts, mark it `accepted` (the code already exists), and link it to the prior decision via `supersedes` or `amends` as appropriate. Add `@decision` annotations to the new/changed code pointing at the new decision.
+
+**Important:** These best-effort fixes are inferred, not authoritative. In the PR description, clearly mark each one under a **"Inferred Decisions — Review Required"** section. Explain what changed, what context was found (commit messages, tickets), and what new decision was created. Reviewers should prioritize checking these for accuracy.
+
+## Step 4: Regenerate INDEX.md
+
+If any decision records were modified:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+```
+
+## Step 5: Update audit state
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" update-audit-state
+```
+
+## Step 6: Commit, push, and open PR
+
+If there are changes (fixes were applied or audit state was updated):
+
+```bash
+git add -A
+```
+
+Commit with a descriptive message summarizing the fixes:
+
+```bash
+git commit -m "fix: resolve DLD audit drift
+
+- [list each fix applied]
+- Audit state updated"
+```
+
+Push and open a PR:
+
+```bash
+git push -u origin HEAD
+```
+
+Create a PR with the following structure:
+
+```markdown
+## DLD Audit — Automated Drift Fixes
+
+**Audit date:** YYYY-MM-DD
+**Issues found:** N
+**Auto-fixed:** M
+**Needs review:** K
+
+### Fixes Applied
+
+- [Description of each fix, grouped by category]
+
+### Inferred Decisions — Review Required
+
+These decisions were created or updated based on code changes made outside the DLD process. The rationale was inferred from commit messages and available ticket context. **Please verify accuracy.**
+
+- **DL-NNN: [Title]** (new/updated) — [What changed in the code, what context was found, what was inferred]
+
+### Audit Summary
+
+| Check | Result |
+|-------|--------|
+| Orphaned annotations | N found, M fixed |
+| Stale references | N found, M fixed |
+| Superseded/deprecated refs | N found, M fixed |
+| Missing annotations | N found, M added |
+| Modified annotated files | N flagged for review |
+```
+
+If no issues were found (only audit state updated), still commit and push the state update but **do not open a PR**. Instead, exit with a message:
+
+```
+Audit complete. No drift detected. Audit state updated.
+```

package/skills/dld-common/SKILL.md

@@ -0,0 +1,14 @@
+---
+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"
+---
+<!-- Generated by dld-kit from templates/skills/dld-common/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# DLD Common
+
+This skill ships `scripts/dld.mjs`, the bundled `dld` command-line tool the other DLD skills run for mechanical operations: assigning IDs, creating records, updating status, regenerating the index, scanning annotations, and reindexing. Do not invoke this skill directly.
+
+`node "<skill-dir>/scripts/dld.mjs" --help` lists the commands, where `<skill-dir>` is the absolute path of this skill's directory.