domain-knowledge-kit 0.2.15 → 0.2.16

package/tools/dkk/claude/commands/dkk-review.md

@@ -0,0 +1,12 @@
+---
+description: Review the current change for DKK domain impact. Delegates to the dkk-domain-reviewer subagent in an isolated context.
+argument-hint: [pr-number | git-range]
+---
+
+Invoke the `dkk-domain-reviewer` subagent. Pass through `$ARGUMENTS` as the input scope:
+
+- If `$ARGUMENTS` is empty, instruct the subagent to review the working-tree diff (`git status` + `git diff`).
+- If `$ARGUMENTS` looks like a number or `#NNN`, instruct it to run `gh pr diff <number>` and review that PR.
+- Otherwise, treat `$ARGUMENTS` as a git range (e.g. `origin/main...HEAD`) and pass it through.
+
+Wait for the subagent's report. Display it verbatim to the user. Do not perform the review yourself.

package/tools/dkk/claude/commands/dkk-story.md

@@ -0,0 +1,12 @@
+---
+description: Generate a user story or epic from a DKK flow using the dkk-story-analyst skill.
+argument-hint: <flow-id-or-feature-name>
+---
+
+Invoke the `dkk-story-analyst` skill. The user's target is `$ARGUMENTS`.
+
+- If `$ARGUMENTS` is empty, ask the user which flow to draft a story for, or list available flows via `mcp__dkk__list` (filter `type: flow`).
+- If `$ARGUMENTS` looks like a flow id (`flow.<Name>` or bare `<Name>`), pass it through to `mcp__dkk__story`.
+- Otherwise, run `mcp__dkk__search` with `$ARGUMENTS` first to identify the matching flow or root command, then proceed.
+
+Follow the skill's workflow end to end, including clarifying questions and acceptance-criteria mapping.

package/tools/dkk/claude/hooks/post-edit-validate.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook — auto-validate after edits to domain YAML.
+ *
+ * When Claude Code edits or writes a file under `.dkk/domain/`, run
+ * `dkk validate` so any broken cross-references or schema violations
+ * surface back into the agent loop immediately, before the next step.
+ *
+ * Stays silent for unrelated edits (no-op, exit 0).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+let raw = "";
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath =
+    payload?.tool_input?.file_path ??
+    payload?.tool_input?.notebook_path ??
+    "";
+
+  // Only act on domain YAML edits.
+  const isDomainYaml = /\.dkk\/domain\/.*\.ya?ml$/.test(filePath);
+  if (!isDomainYaml) process.exit(0);
+
+  const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const cliEntry = resolve(repoRoot, "src/cli.ts");
+
+  const [cmd, args] = existsSync(cliEntry)
+    ? ["npx", ["tsx", cliEntry, "validate", "--json", "--minify"]]
+    : ["dkk", ["validate", "--json", "--minify"]];
+
+  const res = spawnSync(cmd, args, { cwd: repoRoot, encoding: "utf8" });
+  // If validate fails, surface the JSON output to the model via stderr (exit 2
+  // makes Claude Code feed stderr back as a tool-result correction signal).
+  if (res.status !== 0) {
+    process.stderr.write(
+      `dkk validate failed after edit to ${filePath}:\n${res.stdout || res.stderr || ""}\n`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+});

package/tools/dkk/claude/hooks/pre-edit-block-generated.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook — block writes to generated/derived directories.
+ *
+ * `.dkk/docs/` is regenerated from YAML by `dkk render`. Edits there are
+ * always lost on the next render, so we block the tool call up-front and
+ * tell the agent to edit the source YAML instead.
+ *
+ * Same treatment for `dist/` (TypeScript build output).
+ */
+let raw = "";
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = payload?.tool_input?.file_path ?? "";
+  if (!filePath) process.exit(0);
+
+  if (/\.dkk\/docs\//.test(filePath)) {
+    process.stderr.write(
+      `Blocked: ${filePath} is generated by \`dkk render\`. Edit the YAML under .dkk/domain/ and re-render instead.\n`,
+    );
+    process.exit(2);
+  }
+
+  if (/\/dist\//.test(filePath)) {
+    process.stderr.write(
+      `Blocked: ${filePath} is build output. Edit the source under src/ and run \`npm run build\`.\n`,
+    );
+    process.exit(2);
+  }
+
+  process.exit(0);
+});

package/tools/dkk/claude/hooks/session-start-prime.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook — pipe `dkk prime` output into Claude Code's context.
+ *
+ * The hook prints the agent context document (item types, retrieval/update
+ * workflows, current domain summary) to stdout, which Claude Code surfaces
+ * as additional context for the session. Any errors fall through silently
+ * so a missing domain model never blocks session start.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const cliEntry = resolve(repoRoot, "src/cli.ts");
+
+let cmd, args;
+if (existsSync(cliEntry)) {
+  // Local DKK development: run via tsx.
+  cmd = "npx";
+  args = ["tsx", cliEntry, "prime"];
+} else {
+  // Downstream consumer: rely on the published `dkk` binary.
+  cmd = "dkk";
+  args = ["prime"];
+}
+
+const res = spawnSync(cmd, args, { cwd: repoRoot, encoding: "utf8" });
+if (res.status === 0 && res.stdout) {
+  process.stdout.write(res.stdout);
+}
+// Always exit 0 — never block session start over a missing/empty model.
+process.exit(0);

package/tools/dkk/claude/hooks/stop-validate.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — final validation gate before the agent ends a turn.
+ *
+ * Runs `dkk validate`. If the domain model is invalid, returns exit code 2
+ * with the JSON error report on stderr. Claude Code feeds that back so the
+ * agent must fix the broken model before declaring the work complete.
+ *
+ * `stop_hook_active` is honoured to prevent infinite loops if Claude tries
+ * to stop again after the hook already fired once.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+let raw = "";
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  if (payload?.stop_hook_active) {
+    process.exit(0);
+  }
+
+  const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const cliEntry = resolve(repoRoot, "src/cli.ts");
+
+  // No domain model? Nothing to gate on.
+  if (!existsSync(resolve(repoRoot, ".dkk/domain"))) process.exit(0);
+
+  const [cmd, args] = existsSync(cliEntry)
+    ? ["npx", ["tsx", cliEntry, "validate", "--json", "--minify"]]
+    : ["dkk", ["validate", "--json", "--minify"]];
+
+  const res = spawnSync(cmd, args, { cwd: repoRoot, encoding: "utf8" });
+  if (res.status !== 0) {
+    process.stderr.write(
+      `Domain validation failed — fix these before ending the turn:\n${res.stdout || res.stderr || ""}\n`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+});

package/tools/dkk/claude/settings.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(dkk list:*)",
+      "Bash(dkk show:*)",
+      "Bash(dkk summary:*)",
+      "Bash(dkk search:*)",
+      "Bash(dkk related:*)",
+      "Bash(dkk graph:*)",
+      "Bash(dkk locate:*)",
+      "Bash(dkk story:*)",
+      "Bash(dkk validate:*)",
+      "Bash(dkk stats:*)",
+      "Bash(dkk prime:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-prime.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-edit-block-generated.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-validate.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validate.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/tools/dkk/claude/skills/dkk-adr-author/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: dkk-adr-author
+description: Draft a new Architecture Decision Record grounded in the local Domain Knowledge Pack. Use when the user wants to record an architectural decision, capture a trade-off, document a tech choice, or formalize a discussion as an ADR.
+---
+
+# ADR Author
+
+Use this skill whenever the user wants to **record an architectural decision, draft an ADR, or capture a trade-off** in a project that has a Domain Knowledge Pack (`.dkk/`).
+
+> **The DKK model is the single source of truth.** Every ADR must link to the domain items it constrains, bidirectionally. Skipping that link is the most common failure mode this skill prevents.
+
+## Preferred tools
+
+1. `mcp__dkk__search` (with `type: adr`) — find related existing ADRs
+2. `mcp__dkk__show` — read those ADRs in full
+3. `mcp__dkk__search` and `mcp__dkk__related` — identify which domain items the decision affects
+4. `mcp__dkk__locate` — get absolute paths to edit the linked items
+5. `mcp__dkk__validate` — final correctness check
+6. `dkk new adr "<title>"` (Bash) — scaffold the file with the right number and frontmatter
+7. `dkk render` (Bash) — refresh docs and search index after the ADR is finished
+
+Use the equivalent `dkk` shell commands only if the MCP server is unavailable.
+
+## Workflow
+
+1. **Search prior ADRs first.** Call `mcp__dkk__search` with the topic and `type: adr`. Read every related ADR via `mcp__dkk__show`. If a *current* ADR already covers the decision, do not create a new one — update the existing record (with `superseded_by` if direction has changed). If a *deprecated* ADR is relevant, surface its rationale to the user; do not relitigate without acknowledging it.
+2. **Identify affected domain items.** From the user's description, search the model and use `mcp__dkk__related` to find aggregates, events, commands, policies, and read models the decision constrains. Confirm the list with the user.
+3. **Clarify the decision.** Ask **2–5 targeted questions** before drafting. Derive each question and its options from the search results and the user's stated motivation. Skip questions only when the decision is fully specified and uncontroversial. Examples (only if relevant):
+   - What problem prompted the decision? (constraint / incident / new requirement / cleanup)
+   - What alternatives were considered, and why were they rejected?
+   - Which domain items are constrained by this decision?
+   - What is the status — Proposed (needs review), Accepted (in effect), or Deprecated (recording history)?
+   - Does this supersede a prior ADR? If yes, which one?
+4. **Scaffold via the CLI.** Run `dkk new adr "<title>"` — this auto-increments the number and creates the file with valid frontmatter and the canonical section structure. Do not hand-create the file.
+5. **Fill the body.** The canonical sections are *Context*, *Decision*, *Consequences*, and *Alternatives Considered*. Use precise domain terminology — match every name to the items returned by `mcp__dkk__search` and `mcp__dkk__show`.
+6. **Set the bidirectional links.** Both sides must agree:
+   - In the ADR frontmatter, set `domain_refs:` to the list of affected item ids (e.g. `ordering.OrderPlaced`, `actor.Customer`).
+   - On every linked domain item's YAML, append the new ADR id to its `adr_refs:` list. Use `mcp__dkk__locate` to find each file.
+7. **Run quality gates.** The post-edit hook runs `mcp__dkk__validate` automatically; before declaring the work done, also run `dkk render` to refresh `.dkk/docs/` and rebuild the search index.
+
+## Status discipline
+
+- **Proposed** — newly drafted, awaiting team review. The decision is not in effect yet.
+- **Accepted** — the decision is in effect; new code must comply.
+- **Deprecated** — no longer in effect, but kept as project memory. If a successor exists, set `superseded_by: adr-NNNN` in the frontmatter.
+
+Never delete an ADR. Even superseded ones are institutional memory.
+
+## Don'ts
+
+- Don't draft an ADR that doesn't reference at least one domain item (the bidirectional link is what makes ADRs queryable).
+- Don't invent domain terms in the ADR body — every name must exist in the model.
+- Don't hand-edit the ADR filename or number; let `dkk new adr` assign it.
+- Don't skip searching for prior ADRs — relitigating a decided question without referencing the prior ADR is the worst failure mode.

package/tools/dkk/claude/skills/dkk-flow-implementer/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: dkk-flow-implementer
+description: Guide a developer through framework-agnostic implementation of a DKK flow. Use when the user asks to implement, build, or code a flow or feature that maps to a flow in the local Domain Knowledge Pack.
+---
+
+# Flow Implementer
+
+Use this skill whenever the user asks to **implement, build, or code a flow / feature** in a project that has a Domain Knowledge Pack (`.dkk/`).
+
+> **Source of truth is local.** Do not look for or reference external trackers (Jira, GitHub Issues, Linear, Trello, etc.) for requirements. The local DKK model — accessed through the MCP `dkk` server or the `dkk` CLI — is authoritative.
+
+## Preferred tools
+
+Call MCP tools rather than shelling out, in this order of preference:
+
+1. `mcp__dkk__story` — full flow context (actors, ordered steps, policies, BDD examples, ADRs, downstream effects) in one call
+2. `mcp__dkk__list` — to discover available flows when the user hasn't named one
+3. `mcp__dkk__search` — to locate a flow when the user gives a feature name instead of an id
+4. `mcp__dkk__related` — to extend blast radius beyond the immediate flow
+5. `mcp__dkk__show` — to read the full definition of a specific item
+6. `mcp__dkk__validate` — final correctness check after edits
+
+Fall back to the equivalent `dkk` shell commands only if the MCP server is unavailable.
+
+## Workflow
+
+1. **Identify the flow.** If the user gave an id, normalize it (`flow.<Name>` or bare `<Name>`). Otherwise call `mcp__dkk__list` filtered by `type: flow`, or `mcp__dkk__search` on the feature name to find a candidate flow or root command.
+2. **Retrieve full context.** Call `mcp__dkk__story` with the flow id. Read the actors, ordered steps, triggered policies, BDD examples, ADRs, and downstream effects.
+3. **Clarify scope.** Ask **1–7 clarifying questions** before generating any checklist. Derive every question, its options, and your recommended default from the actual story output and the project's conventions — never use a fixed list. Each question must offer concrete options with one marked as recommended. **Skip the questions entirely** for trivial flows (≤2 steps, no cross-context effects, no ambiguity). Questions should target implementation behavior and UX, e.g.:
+   - What should the user see immediately after this command succeeds?
+   - How should validation errors surface (inline / toast / page-level)?
+   - Optimistic UI or wait-for-confirmation?
+   - Concurrency: can two users trigger this simultaneously?
+   - Is there an undo path, or one-way?
+4. **Present architectural constraints.** List every ADR returned in the story output (`adr-NNNN — title — status`). Ask the user to acknowledge these before implementation begins. If the agent identifies any ADR conflict with the user's stated approach, surface it before proceeding.
+5. **Generate a framework-agnostic checklist.** Group by domain role:
+   - **Aggregates** — entities, state transitions, invariants
+   - **Commands** — handlers, preconditions, validations
+   - **Events** — what to publish on success
+   - **Policies** — reactive logic triggered by events
+   - **Read models** — projections to update on events
+6. **Walk through interactively.** Ask the user which checklist item they want to tackle first. Guide on the **domain logic** — invariants, policies, transitions — not framework boilerplate. Only emit framework-specific code if the user explicitly asks or `AGENTS.md` / `CLAUDE.md` directs otherwise.
+7. **Use the canonical nouns.** Whatever names appear in the `mcp__dkk__story` output are the only allowed names. Do not rename `OrderBasket` to `ShoppingCart`.
+8. **Validate and render after structural changes.** When the user's implementation requires new or modified domain items, use the DKK CLI commands (`dkk add`, `dkk rename`, `dkk rm`) for structural changes and edit YAML directly only for content. The post-edit hook will run `mcp__dkk__validate` automatically; before declaring the work done, also run `dkk render` to refresh docs and the search index.
+
+## Interaction rules
+
+- Do not generate full boilerplate up front. Wait for the user to request code for a specific checklist item.
+- Confirm with the user before moving to the next checklist item.
+- If the user asks for a framework-specific implementation, defer to `AGENTS.md` or `CLAUDE.md` conventions.
+- Never invent domain terms. If a needed concept is missing from the model, surface it as a gap and propose adding it via `dkk add` rather than coding around it.

package/tools/dkk/claude/skills/dkk-story-analyst/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: dkk-story-analyst
+description: Generate, split, or reshape user stories and epics from the local Domain Knowledge Pack. Use when the user asks to write, draft, refine, or split a user story or epic for a feature that maps to a DKK flow or command.
+---
+
+# Story Analyst
+
+Use this skill whenever the user asks to **write, draft, generate, refine, or split a user story or epic** in a project that has a Domain Knowledge Pack (`.dkk/`).
+
+> **"User stories" and "epics" here are behavioral requirements derived from the local DDD/Event-Storming model in `.dkk/`.** Do not consult external trackers (Jira, GitHub Issues, Linear, Trello, etc.). The MCP `dkk` server (or the `dkk` CLI as fallback) is the only source of truth.
+
+## Preferred tools
+
+1. `mcp__dkk__story` — aggregate a flow's full context (actors, steps, policies, BDD examples, ADRs, downstream effects) in one call
+2. `mcp__dkk__list` filtered by `type: flow` — discover available flows
+3. `mcp__dkk__search` — locate a flow or command from a feature name
+4. `mcp__dkk__show` — fall back when no flow exists, to read a command directly
+5. `mcp__dkk__related` — to gather neighbours when working from a command instead of a flow
+
+Use the corresponding `dkk` shell commands only if the MCP server is unavailable.
+
+## Workflow
+
+1. **Identify the flow.** Normalize the id (`flow.<Name>` or bare `<Name>`). If the user gave a feature name instead, call `mcp__dkk__search` to locate a matching flow or root command.
+2. **Retrieve context.** Call `mcp__dkk__story` with the flow id. The response contains actors, ordered steps, triggered policies, BDD examples, ADRs, and downstream effects.
+3. **Clarify scope.** Ask **1–7 clarifying questions** before drafting. Derive every question, its options, and your recommended default from the actual story output and the project's conventions — never use a fixed list. Each question must offer concrete options with one marked as recommended. **Skip the questions entirely** for trivial flows (≤2 steps, 1 actor, no ambiguity). Target product behavior and story scope, e.g.:
+   - Which user-facing outcome matters most?
+   - Confirmation/feedback on success — how should it surface?
+   - On failure or rejection, what does the user experience?
+   - Optional steps that can be skipped, or strictly linear?
+   - Happy path only, or include edge cases?
+4. **Map to story format.**
+   - **As a** `<Actor from "Actors" section>`
+   - **I want to** `<Command description from Steps>`
+   - **So that** `<Flow description>`
+5. **Write acceptance criteria** from the policies and BDD examples in the output:
+   - Policies → Given/When/Then: *When [triggering event] → Then [consequent command]*
+   - BDD examples on commands and events are pre-written scenarios — use them directly or expand
+6. **Add an Architectural Constraints section** listing every ADR (`adr-NNNN — title — status`). Developers must respect these.
+7. **Add an Implementation Notes section** from the downstream effects: read models to update, secondary policies that fire.
+
+## Noun enforcement (mandatory)
+
+Use only the terminology in the `mcp__dkk__story` output. Do not:
+
+- Invent entity, command, or event names not present
+- Rename domain terms (if DKK says `OrderBasket`, the story says `OrderBasket`)
+- Reference bounded contexts not mentioned in the step refs
+- Pull names from external APIs or trackers
+
+If unsure whether a term is canonical, run `mcp__dkk__search` to verify.
+
+## Epic vs. story decision rules
+
+After retrieving the flow context:
+
+- **Single story** when the flow has ≤3 command steps and spans ≤1 bounded context.
+- **Epic with story slices** when the flow has >3 command steps **or** spans >1 bounded context. Slice by:
+  1. Group consecutive steps that share the same context prefix (all `ordering.*` steps → Story 1)
+  2. Each policy trigger becomes its own story ("As a system, when X happens, I want Y to be triggered, so that Z")
+  3. Each slice that produces an event consumed by a read model must include updating that read model in its scope or acceptance criteria
+
+When recommending an epic breakdown, present the slice boundaries and explain which downstream effects belong to each slice based on the model.
+
+## Story reshaping
+
+When asked to refine, split, or revise an existing story:
+
+1. Call `mcp__dkk__story` for the relevant flow to get current domain truth
+2. Compare the story's terminology to the output
+3. Flag mismatches: invented terms, missing actors, acceptance criteria that contradict policies
+4. Suggest corrections using exact DKK terminology
+5. Ensure the reshaped story still covers all downstream effects
+
+## Fallback: no flow exists
+
+If no flow has been modeled for the requested feature:
+
+1. Locate the most relevant command: `mcp__dkk__search` with `type: command`
+2. Get its full definition: `mcp__dkk__show`
+3. Get its neighbours: `mcp__dkk__related` with `depth: 2`
+4. Assemble the story from:
+   - Command `actor` → "As a..."
+   - Command `description` → "I want to..."
+   - Command `preconditions`, `rejections`, `examples` → acceptance criteria
+   - Neighbouring policies and read models → downstream effects
+5. Note in the story that no formal flow has been modeled, and recommend the team define one.
+
+## Output format
+
+```markdown
+## [Story Title]
+
+**As a** [Actor], **I want to** [action], **so that** [business value].
+
+### Acceptance Criteria
+
+- **Given** [precondition], **When** [command/event], **Then** [outcome]
+- (repeat for each policy rule and BDD example)
+
+### Architectural Constraints
+
+- [adr-NNNN]: [title] ([status])
+
+### Implementation Notes
+
+- [Downstream read models, secondary policy triggers, cross-context effects]
+```

package/tools/dkk/schema/actors.schema.json

@@ -37,7 +37,7 @@
           },
           "adr_refs": {
             "type": "array",
-            "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+            "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
             "uniqueItems": true,
             "description": "Related ADR identifiers"
           }

package/tools/dkk/schema/adr-frontmatter.schema.json

@@ -34,16 +34,16 @@
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
-        "description": "Domain item reference in context.Name format (e.g. ordering.OrderPlaced)"
+        "pattern": "^([a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
+        "description": "Domain item reference in context.Name format (e.g. ordering.OrderPlaced, or service:context.Name for federated refs)"
       },
       "uniqueItems": true,
       "description": "Domain items related to this decision"
     },
     "superseded_by": {
       "type": "string",
-      "pattern": "^adr-\\d{4}$",
-      "description": "ID of the ADR that supersedes this one"
+      "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$",
+      "description": "ID of the ADR that supersedes this one (optionally service-qualified for peer ADRs)"
     }
   },
   "required": ["id", "title", "status", "date"],

package/tools/dkk/schema/aggregate.schema.json

@@ -48,7 +48,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/command.schema.json

@@ -66,7 +66,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/event.schema.json

@@ -56,7 +56,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/federation.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "federation.schema.json",
+  "title": "Federation Manifest",
+  "description": "Peer service manifest for multi-repo federation (.dkk/federation.yml). Each peer points at a filesystem path or a git URL+branch; the peer's `.dkk/` directory is loaded read-only alongside the local model.",
+  "type": "object",
+  "properties": {
+    "peers": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/peer" },
+      "description": "Peer services whose .dkk/ should be loaded alongside the local model."
+    }
+  },
+  "required": ["peers"],
+  "additionalProperties": false,
+  "definitions": {
+    "peer": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Kebab-case peer service name (must match the peer's own service.yml)."
+        },
+        "source": {
+          "oneOf": [
+            { "$ref": "#/definitions/localSource" },
+            { "$ref": "#/definitions/gitSource" }
+          ]
+        }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": false
+    },
+    "localSource": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "local" },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute or repo-root-relative path to the peer's repository root."
+        }
+      },
+      "required": ["type", "path"],
+      "additionalProperties": false
+    },
+    "gitSource": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "git" },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Git URL (https or ssh)."
+        },
+        "branch": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Branch to track."
+        },
+        "path": {
+          "type": "string",
+          "description": "Optional sub-path inside the peer repo where .dkk/ lives (default: repo root)."
+        }
+      },
+      "required": ["type", "url", "branch"],
+      "additionalProperties": false
+    }
+  }
+}

package/tools/dkk/schema/glossary.schema.json

@@ -23,7 +23,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers (e.g. adr-0001)"
     }

package/tools/dkk/schema/index.schema.json

@@ -46,8 +46,8 @@
               "properties": {
                 "ref": {
                   "type": "string",
-                  "pattern": "^[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
-                  "description": "Domain item reference (context.Name)"
+                  "pattern": "^([a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
+                  "description": "Domain item reference (context.Name, or service:context.Name for federated refs)"
                 },
                 "type": {
                   "type": "string",

package/tools/dkk/schema/policy.schema.json

@@ -43,7 +43,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/read-model.schema.json

@@ -43,7 +43,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }