dld-kit 1.0.0-rc.1

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

@@ -0,0 +1,159 @@
+---
+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.
+---
+
+# /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
+
+{{dld-setup}}
+
+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
+{{dld}} 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
+{{dld}} 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
+{{dld}} 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
+{{dld}} 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/templates/skills/dld-audit-auto/SKILL.md

@@ -0,0 +1,169 @@
+---
+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.
+---
+
+# /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
+
+{{dld-setup}}
+
+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
+{{dld}} 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 `{{dld}} 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
+{{dld}} regenerate-index
+```
+
+## Step 5: Update audit state
+
+```bash
+{{dld}} 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/templates/skills/dld-common/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: dld-common
+description: The dld CLI shared by the DLD skills. Not intended for direct invocation — the other DLD skills run it.
+internal: true
+compatibility: Requires Node.js 20+ and git.
+---
+
+# 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.
+
+`{{dld}} --help` lists the commands, where `<skill-dir>` is the absolute path of this skill's directory.

package/templates/skills/dld-decide/SKILL.md

@@ -0,0 +1,116 @@
+---
+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.
+---
+
+# /dld-decide — Record a Decision
+
+You are helping the developer record a development decision. This should be a focused, low-ceremony conversation — not an interrogation.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user rather than waiting for freeform replies.
+
+## Commands
+
+{{dld-setup}}
+
+This skill uses: `next-id`, `create-decision`, `update-status`, `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
+
+1. Read `dld.config.yaml` to understand the project structure (flat vs namespaced, decisions directory, namespaces list)
+2. Read `decisions/PRACTICES.md` if it exists — be aware of project conventions when helping structure the decision
+3. For namespaced projects, also read `decisions/records/<namespace>/PRACTICES.md` if it exists for the relevant namespace
+
+## Conversation flow
+
+### 1. Collect the decision
+
+If the user provided context with the skill invocation, use it. Otherwise ask:
+
+> What decision are you recording? Tell me what you decided, why, and what code it affects.
+
+Listen for:
+- **What** was decided (the decision itself)
+- **Why** (the rationale — what problem it solves, what alternatives were considered)
+- **What it affects** (code areas, components, modules)
+
+### 2. Ask clarifying questions (if needed)
+
+Only ask follow-up questions if the rationale or scope is genuinely unclear. Maximum 3-5 questions total. Don't interrogate — if the developer gave enough context, move on.
+
+Good reasons to ask:
+- The rationale is missing or unclear
+- There might be alternatives worth noting
+- The scope of affected code isn't clear
+- There are obvious consequences worth recording
+
+### 3. Check for related decisions
+
+Scan existing decision files for potential relationships:
+- Decisions that reference the same code paths
+- Decisions with overlapping tags
+- Decisions that this one might supersede or amend
+
+If you find related decisions, mention them and ask whether this decision **supersedes** (fully replaces) or **amends** (partially modifies) any of them. A superseded decision gets marked as `superseded` and is no longer active. An amended decision stays `accepted` — the amendment changes part of its scope while the rest remains in effect.
+
+### 4. Determine namespace (namespaced projects only)
+
+If the project is namespaced, determine which namespace this decision belongs to. Infer from the code references if possible, otherwise ask.
+
+### 5. Assign ID
+
+Run `next-id`:
+```bash
+{{dld}} next-id
+```
+
+This outputs the next available ID (e.g., `DL-004`).
+
+### 6. Create the decision record
+
+Compose the markdown body with the relevant sections (Context, Decision, Rationale, Consequences). Omit sections that aren't relevant, but always include Context and Decision.
+
+Then run `create-decision`, piping the body via `printf` with `\n` for newlines (do **not** use literal newlines in the body argument — use `\n` escape sequences so the entire command stays on one logical line):
+```bash
+printf "## Context\n\nWhat prompted this decision.\n\n## Decision\n\nWhat was decided.\n\n## Rationale\n\nWhy this choice.\n\n## Consequences\n\nWhat becomes easier or harder." | {{dld}} create-decision \
+  --id "DL-NNN" \
+  --title "Short descriptive title" \
+  --namespace "billing" \
+  --tags "tag1, tag2" \
+  --supersedes "DL-003, DL-007" \
+  --amends "DL-005" \
+  --body-stdin
+```
+
+Flags `--namespace`, `--tags`, `--supersedes`, `--amends` are optional. The command creates the file with YAML frontmatter and the body content, and outputs the file path.
+
+> **Note:** If the body contains literal `%` characters, escape them as `%%` (printf format string requirement).
+
+If this decision supersedes others, also update their status:
+```bash
+{{dld}} update-status DL-003 superseded
+```
+
+**Do not** update the status of amended decisions — they stay `accepted`.
+
+### 7. Regenerate INDEX.md
+
+```bash
+{{dld}} regenerate-index
+```
+
+### 8. Suggest next steps
+
+> Decision **DL-NNN** recorded as `proposed`.
+>
+> Next steps:
+> - `/dld-adjust` — refine the decision before implementing
+> - `/dld-implement DL-NNN` — implement this decision
+> - `/dld-decide` — record another decision

package/templates/skills/dld-implement/SKILL.md

@@ -0,0 +1,213 @@
+---
+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.
+---
+
+# /dld-implement — Implement Decisions
+
+You are implementing one or more `proposed` decisions by making code changes, adding `@decision` annotations, and updating the decision records.
+
+## Commands
+
+{{dld-setup}}
+
+This skill uses: `update-status`, `verify-annotations`, `regenerate-index`.
+
+## Prerequisites
+
+1. Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+2. Parse the user's input to identify which decision(s) to implement:
+   - Specific IDs: `DL-005`, `DL-005 DL-006`
+   - By tag: `tag:payment-gateway`
+   - **No arguments:** If the user runs `/dld-implement` without specifying decisions, find all decisions with `status: proposed` in the records subdirectory (`decisions/records/`) and implement all of them.
+3. Read each referenced decision file. Verify they exist and have `status: proposed`. If a decision is already `accepted`, tell the user and skip it. If it doesn't exist, report the error.
+
+## Read project context
+
+1. Read `dld.config.yaml` for project structure
+2. Read `decisions/PRACTICES.md` if it exists — **this is where practices guidance is most important**. Apply the project's testing approach, code style, error handling patterns, and architecture conventions when writing code.
+3. For namespaced projects, also read `decisions/records/<namespace>/PRACTICES.md` for namespace-specific practices
+
+## Implementation
+
+### Batch vs. single implementation
+
+When multiple decisions are requested, decide whether to implement them individually or as a batch:
+
+- **Batch together** decisions that are tightly coupled — they touch the same code, share types, or depend on each other so heavily that implementing one without the others would produce incomplete or throwaway code (e.g., a data model + its validation + its state machine).
+- **Implement separately** decisions that are independent — they touch different areas of the codebase and can stand on their own.
+
+When batching, implement all the code together, add annotations for all decisions, then update each decision record and status individually in step 4.
+
+### 1. Understand the decision(s)
+
+Read each decision record carefully. Understand:
+- What was decided
+- The rationale and constraints
+- The code areas referenced
+- Any superseded or amended decisions (read those too for context on what changed)
+
+### 2. Make code changes
+
+Implement the decision(s) by modifying the codebase. Follow the practices manifest if one exists.
+
+**Refining decisions during implementation:** While implementing, you may discover details that weren't anticipated during planning — a specific threshold value, an edge case handling approach, or a refinement to the original design. Since the decision is still in `proposed` status, it is **mutable** and can be updated:
+
+- **Small refinements** (implementation details, specific values, edge cases that don't change the decision's intent) — update the decision record inline. Amend the Decision, Rationale, or Consequences sections as needed. This is expected and encouraged.
+- **Major discoveries** (a fundamentally different approach is needed, or an entirely new design concern surfaces) — stop and suggest the user run `/dld-decide` to record a separate decision. If the new discovery invalidates the current decision, it may need to be superseded instead.
+
+The boundary: if the discovery changes the *intent* of the decision, it's a new decision. If it refines the *implementation details*, update the current one.
+
+### 3. Add `@decision` annotations
+
+**This step is mandatory.** Every implemented decision MUST have at least one `@decision(DL-NNN)` annotation in the source code. Updating the decision record's `references` field alone is not sufficient. The annotation in code is what triggers AI agents to look up the decision before modifying the annotated code.
+
+Add `@decision(DL-NNN)` annotations to the code you modified or created. Place annotations in comments near the relevant code.
+
+**Where to annotate:**
+- Functions, methods, or classes that embody the decision
+- Configuration or constants that were chosen based on the decision
+- Key logic branches where the decision's rationale matters
+
+**Annotation format** (adapt comment syntax to the language):
+```typescript
+// @decision(DL-012)
+function calculateVAT(order: Order): Money {
+  // ...
+}
+```
+
+```python
+# @decision(DL-012)
+def calculate_vat(order: Order) -> Money:
+    ...
+```
+
+**Guidelines:**
+- Annotate at the declaration level, not every line
+- One annotation per decision per code location
+- Multiple decisions can annotate the same code: `// @decision(DL-012) @decision(DL-015)`
+- Use the `annotation_prefix` from `dld.config.yaml` (default: `@decision`)
+
+**Keep annotations lean — the decision record is the single source of truth.**
+
+The point of `@decision(DL-NNN)` is to keep the rich context (rationale, constraints, alternatives, consequences) in the decision record, *not* scattered through the code. The annotation is a pointer, not a summary. Do not let implementing a decision turn into a comment-writing exercise.
+
+- **Default to the bare annotation.** `// @decision(DL-012)` on its own is the norm and is usually all you need.
+- **Do not restate the decision's context.** Don't paraphrase the rationale, the alternatives considered, or the "why" in comments. That duplicates the record, creates a second source of truth, and drifts the moment the decision is adjusted.
+- **Avoid "because" comments paired with the annotation.** `// @decision(DL-012)` already means "the reasoning lives in DL-012." Writing `// We use X because Y (see DL-012)` defeats the purpose — drop the "because Y."
+- **Only add a further comment when the *code itself* is genuinely non-obvious** — a subtle invariant, a non-intuitive workaround, a non-local ordering dependency. Such a comment should explain *what the code is doing*, never *why the decision was made* (that's the record's job).
+
+When in doubt, leave it out — a reader who wants the "why" follows the annotation to the decision record.
+
+### 4. Update decision records
+
+For each implemented decision:
+
+1. **Update the `references` field** in the decision record's YAML frontmatter. Edit the file directly — add the code paths and symbols that were annotated. Example:
+   ```yaml
+   references:
+     - path: src/billing/vat.ts
+       symbol: calculateVAT
+     - path: src/billing/vat.test.ts
+   ```
+
+2. **Update status** from `proposed` to `accepted`:
+   ```bash
+   {{dld}} update-status DL-NNN accepted
+   ```
+
+### 5. Verify annotations
+
+After updating all decision records, run `verify-annotations` to confirm every implemented decision has at least one `@decision` annotation in the codebase:
+
+```bash
+{{dld}} verify-annotations DL-005 DL-006
+```
+
+Pass all the decision IDs that were implemented. If any are missing annotations, the command will report them and exit with an error. Go back and add the missing annotations before proceeding.
+
+### 6. Review code changes
+
+Check `dld.config.yaml` for the `implement_review` key. If it is set to `false`, skip this step entirely. If it is `true` or absent (default: enabled), proceed.
+
+Launch a subagent to review all code changes for correctness and security. Use the `Agent` tool (also called `AgentTool`) with a prompt constructed from the template below, replacing all `{{placeholders}}` with actual values:
+
+```
+You are reviewing code changes for the {{project_name}} project before committing. The changes implement {{decision_count}} decisions ({{decision_range}}) covering:
+
+{{decision_summaries}}
+
+The project uses:
+{{tech_stack_summary}}
+
+Review these files for:
+- Correctness (logic errors, edge cases)
+- Security (SQL injection, directory traversal, XSS, etc.)
+- Consistency with existing patterns and conventions
+- Type safety issues
+- Missing error handling
+- Any code that could be simplified
+
+Files to review (read all of them):
+{{file_list}}
+
+Also read the practices doc at {{practices_path}}
+
+Focus on the changes made for these decisions; report pre-existing issues only where the new code interacts with them. Before reporting consistency findings, examine similar existing code in the repo to learn its conventions.
+
+Do NOT make any changes. Only report findings. Be concise — focus on actual issues, not style preferences ({{linter_name}} handles style).
+
+Report each finding in this format:
+
+### [SEVERITY] Short title
+- Location: `path/to/file.ext:42`
+- Description: what is wrong and why it matters
+- Recommendation: specific, actionable fix
+
+Group findings by severity:
+- Critical (must fix): incorrect behavior, data loss, or an exploitable vulnerability
+- Moderate (should fix): bugs in edge cases, missing error handling that can plausibly trigger
+- Minor (nice to have): simplifications and small improvements
+```
+
+**Filling in the placeholders:**
+- `{{project_name}}` — from `dld.config.yaml` or the repo directory name
+- `{{decision_count}}` and `{{decision_range}}` — count and IDs of the decisions just implemented (e.g., "3 decisions (DL-005 – DL-007)")
+- `{{decision_summaries}}` — one-line summary of each decision's title and intent
+- `{{tech_stack_summary}}` — languages, frameworks, and key libraries from the project (infer from `dld.config.yaml`, `package.json`, or equivalent)
+- `{{file_list}}` — all files you created or modified during steps 2–4
+- `{{practices_path}}` — path to `decisions/PRACTICES.md` (or namespace-specific practices if applicable). Omit the line if no practices file exists.
+- `{{linter_name}}` — the project's linter (e.g., ESLint, Ruff). If unknown, use "the project linter"
+
+**Launching the subagent is requested by the user.** Some agent harnesses carry a standing instruction not to spawn subagents unless the user asked for one. That condition is met here: the user asked by running this skill in a project whose `implement_review` setting is enabled. The request does not need to be repeated in conversation, and this step is not an unprompted fan-out — it is one review agent, at a fixed point, that the project opted into.
+
+**If the subagent genuinely cannot run** — the tool is unavailable, or the user denies the call — do not silently skip the review. Do it inline instead, and make it a deliberate pass rather than a recollection: re-read each changed file from disk and work through the checklist above against what is actually written. Then state in your final report that the review ran inline rather than in a subagent, and why. An inline review is the author checking their own work; it is weaker than a fresh-context review at catching assumptions baked in while implementing, and the user needs to know which one they got.
+
+**Acting on findings:**
+- **Critical** — fix before proceeding
+- **Moderate** — fix unless you disagree with the finding (use your judgment)
+- **Minor** — skip unless trivial to address
+
+**Note:** The review subagent operates with limited context and may flag false positives or misunderstand project-specific patterns. Use your own judgment — you have fuller context from having just written the code. If you're uncertain whether a finding warrants a fix, ask the user before making changes.
+
+If you made fixes, re-run `verify-annotations` from step 5 to ensure annotations are still intact.
+
+### 7. Regenerate INDEX.md
+
+```bash
+{{dld}} regenerate-index
+```
+
+### 8. Suggest next steps
+
+> Implemented and accepted: **DL-NNN** (<title>)
+>
+> Code changes:
+> - `src/billing/vat.ts` — modified `calculateVAT` (annotated with `@decision(DL-NNN)`)
+> - `src/billing/vat.test.ts` — added tests
+>
+> Next steps:
+> - `/dld-decide` — record another decision
+> - `/dld-audit` — check for drift between decisions and code