kataster 0.0.0-stage → 0.2.1

package/.claude/skills/groom-backlog/scripts/backlog-health.ts

@@ -0,0 +1,238 @@
+/**
+ * Mechanical health check of the open backlog – step 1 of `/groom-backlog`.
+ *
+ * Finds what nobody spots by reading 60 story files, and what `validate-stories.ts` deliberately does not check
+ * (that one answers "is this file well-formed?", this one answers "does this backlog still make sense?"):
+ *
+ *   FINDING  dependency cycle – the stories involved can never start
+ *   FINDING  a story depends on one that is dropped (`wont`) or does not exist
+ *   FINDING  priority inversion – a `must` waits for a story of lower priority
+ *   FINDING  a ready story is blocked by a story that is still draft/review
+ *   FINDING  a dead domain reference – an event or an ID in the body that events.yaml no longer has
+ *   FINDING  a story that is not done but already has tests for its scenarios (left in progress, or built elsewhere)
+ *   FINDING  an [OPEN] marker, or an open row in OPEN_QUESTIONS.md older than the threshold
+ *   FINDING  a story with a screen that has not decided its empty case, its rejection or its permission (G7/G8/G11)
+ *   INFO     depth of the dependency chain per story, and what is reachable at all
+ *
+ * Findings are material for the grooming conversation, not errors: this script never fails a build.
+ * Exit code is always 0 unless the stories cannot be read at all.
+ *
+ * Usage: node backlog-health.ts [BC-Name | ST-NNN ...]   (empty = every story that is not done)
+ */
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+
+const STALE_DAYS = 30;
+
+const args = process.argv.slice(2).map((a) => a.toUpperCase());
+const wantedIds = new Set(args.filter((a) => /^ST-\d+$/.test(a)));
+const wantedContexts = new Set(args.filter((a) => a.startsWith("BC-")));
+
+const { parsed, failures } = d.loadStories();
+if (!parsed.length) {
+  console.error("No stories in docs/stories/ – nothing to groom.");
+  process.exit(1);
+}
+for (const [path, why] of failures) console.log(`FINDING  ${d.rel(path)}: unreadable frontmatter – ${why}`);
+
+const byId = new Map(parsed.map((s) => [d.storyId(s), s]));
+const meta = (s: d.Story, key: string): unknown => s.meta[key];
+const str = (s: d.Story, key: string): string => (typeof meta(s, key) === "string" ? String(meta(s, key)) : "");
+const arr = (s: d.Story, key: string): string[] => (Array.isArray(meta(s, key)) ? (meta(s, key) as string[]) : []);
+const open = parsed.filter((s) => str(s, "status") !== "done");
+
+function selected(s: d.Story): boolean {
+  if (!wantedIds.size && !wantedContexts.size) return true;
+  return wantedIds.has(d.storyId(s)) || wantedContexts.has(str(s, "context").toUpperCase());
+}
+
+const scope = open.filter(selected);
+if (!scope.length) {
+  console.log(`No open stories match ${args.join(", ")}.`);
+  process.exit(0);
+}
+
+const findings: string[] = [];
+const info: string[] = [];
+const find = (id: string, msg: string): void => void findings.push(`${id}: ${msg}`);
+
+// --------------------------------------------------------------------------
+// Dependencies
+// --------------------------------------------------------------------------
+const PRIORITY_RANK: Record<string, number> = { must: 0, should: 1, could: 2, wont: 3 };
+const rank = (s: d.Story): number => PRIORITY_RANK[str(s, "priority")] ?? 9;
+
+/** The cycle through `id`, as a list of IDs, or null. Depth-first over depends_on. */
+function cycleThrough(id: string): string[] | null {
+  const seen = new Map<string, number>();
+  const stack: string[] = [];
+  const walk = (current: string): string[] | null => {
+    const at = seen.get(current);
+    if (at !== undefined) return at >= 0 ? [...stack.slice(at), current] : null;
+    seen.set(current, stack.length);
+    stack.push(current);
+    for (const next of arr(byId.get(current) ?? ({ meta: {} } as d.Story), "depends_on")) {
+      const found = walk(next);
+      if (found) return found;
+    }
+    stack.pop();
+    seen.set(current, -1);
+    return null;
+  };
+  return walk(id);
+}
+
+const reported = new Set<string>();
+for (const s of scope) {
+  const id = d.storyId(s);
+  const cycle = cycleThrough(id);
+  if (cycle && !cycle.some((c) => reported.has(c))) {
+    cycle.forEach((c) => reported.add(c));
+    find(id, `dependency cycle – ${cycle.join(" → ")}. None of these can ever start.`);
+  }
+}
+
+for (const s of scope) {
+  const id = d.storyId(s);
+  for (const dep of arr(s, "depends_on")) {
+    const target = byId.get(dep);
+    if (!target) {
+      find(id, `depends on ${dep}, which does not exist`);
+      continue;
+    }
+    const depStatus = str(target, "status");
+    if (str(target, "priority") === "wont") {
+      find(id, `depends on ${dep}, which is dropped (priority wont) – ${id} can never start`);
+    }
+    if (depStatus === "done") continue;
+    if (rank(target) > rank(s)) {
+      find(
+        id,
+        `priority inversion – ${str(s, "priority")} story waits for ${dep} (${str(target, "priority")}): ` +
+          `either ${dep} is more important than its priority says, or ${id} is less.`,
+      );
+    }
+    if (str(s, "status") === "ready" && ["draft", "review"].includes(depStatus)) {
+      find(id, `is ready but waits for ${dep}, which is still ${depStatus} – it cannot be implemented yet`);
+    }
+  }
+}
+
+/** How many stories have to be done before this one can start (dependencies that are not done). */
+function chainDepth(id: string, seen = new Set<string>()): number {
+  if (seen.has(id)) return 0;
+  seen.add(id);
+  const s = byId.get(id);
+  if (!s || str(s, "status") === "done") return 0;
+  const deps = arr(s, "depends_on").filter((dep) => str(byId.get(dep) ?? ({ meta: {} } as d.Story), "status") !== "done");
+  return deps.length ? 1 + Math.max(...deps.map((dep) => chainDepth(dep, seen))) : 0;
+}
+
+const deepest = scope
+  .map((s) => ({ id: d.storyId(s), title: str(s, "title"), depth: chainDepth(d.storyId(s)) }))
+  .sort((a, b) => b.depth - a.depth)
+  .slice(0, 5)
+  .filter((x) => x.depth > 1);
+for (const x of deepest) info.push(`${x.id} sits ${x.depth} stories deep in the dependency chain – "${x.title}"`);
+
+// --------------------------------------------------------------------------
+// Domain references that no longer exist
+// --------------------------------------------------------------------------
+const model = d.loadEventsModel();
+if (model) {
+  const known = d.indexModel(model);
+  const idRe = /\b(?:ACT|EXT|BC|AGG|EVT|CMD|POL|RM|HS|FLOW)-[A-Z][A-Za-z0-9]+\b/g;
+  for (const s of scope) {
+    const id = d.storyId(s);
+    const dead = new Set<string>();
+    for (const ev of arr(s, "events")) if (!known.has(ev)) dead.add(`${ev} (frontmatter)`);
+    for (const m of s.body.matchAll(idRe)) if (!known.has(m[0])) dead.add(m[0]);
+    if (dead.size) find(id, `refers to IDs that events.yaml no longer has: ${[...dead].join(", ")}`);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Already built, although the story is not done
+// --------------------------------------------------------------------------
+const titles = e.testTitles();
+for (const s of scope) {
+  if (str(s, "type") !== "story") continue;
+  const id = d.storyId(s);
+  const { covered, missing } = e.scenarioCoverage(s, titles);
+  if (covered.length && missing.length) {
+    find(id, `${covered.length} of ${covered.length + missing.length} scenarios already have a test – partly built`);
+  } else if (covered.length && !missing.length) {
+    find(id, `every scenario already has a test, although the story is ${str(s, "status")} – is it done?`);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Stories with a screen that have not decided their states (UX guidelines G7, G8, G11)
+// --------------------------------------------------------------------------
+// `validate-stories.ts` warns about these while a story is draft or review. Here every open story is checked,
+// including the `ready` ones approved under the older rules – that debt belongs in a grooming conversation, not
+// in the output of every single write. Grouped per guideline, because forty separate lines drown everything else.
+const perGuideline = new Map<string, string[]>();
+for (const s of scope) {
+  for (const w of d.completenessWarnings(s)) {
+    const guideline = /UX guideline (G\d+[a-z]?)/.exec(w)?.[1] ?? "G?";
+    perGuideline.set(guideline, [...(perGuideline.get(guideline) ?? []), d.storyId(s)]);
+  }
+}
+const GUIDELINE_GAP: Record<string, string> = {
+  G7: "no scenario for the empty case",
+  G8: "a rejection that never says what happens to what was typed",
+  G11: "a permission rejection without the \"is not offered\" half",
+};
+for (const [guideline, ids] of [...perGuideline].sort()) {
+  findings.push(
+    `worth a look – ${ids.length} stories with a screen may have ${GUIDELINE_GAP[guideline] ?? guideline} ` +
+      `(${guideline}); the wording check cannot tell whether the guideline applies, the ux-designer can: ${ids.join(", ")}`,
+  );
+}
+
+// --------------------------------------------------------------------------
+// Decisions that were parked
+// --------------------------------------------------------------------------
+for (const s of scope) {
+  const marks = (s.body.match(/\[OPEN\]/g) ?? []).length;
+  if (marks) find(d.storyId(s), `${marks} [OPEN] marker(s) – a decision is still missing`);
+}
+
+const questions = d.rel(`${d.STORIES_DIR}/OPEN_QUESTIONS.md`);
+const openRows: string[] = [];
+try {
+  const text = (await import("node:fs")).readFileSync(`${d.STORIES_DIR}/OPEN_QUESTIONS.md`, "utf8");
+  const today = Date.now();
+  for (const line of text.split("\n")) {
+    const cells = line.split("|").map((c) => c.trim());
+    if (cells.length < 6 || !/^\d{4}-\d{2}-\d{2}$/.test(cells[3] ?? "")) continue;
+    if (cells[4]) continue; // already answered
+    const days = Math.round((today - Date.parse(cells[3])) / 86_400_000);
+    if (days >= STALE_DAYS) openRows.push(`${cells[1]} – unanswered for ${days} days: ${cells[2].slice(0, 90)}…`);
+  }
+} catch {
+  /* no open questions file */
+}
+for (const row of openRows) findings.push(`${questions}: ${row}`);
+
+// --------------------------------------------------------------------------
+// Report
+// --------------------------------------------------------------------------
+const counts = new Map<string, number>();
+for (const s of scope) {
+  const key = `${str(s, "status")}/${str(s, "priority")}`;
+  counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+console.log(
+  `INFO     ${scope.length} open stories in scope` +
+    (args.length ? ` (${args.join(", ")})` : "") +
+    ` – ${[...counts].sort().map(([k, n]) => `${k}: ${n}`).join(", ")}`,
+);
+for (const line of info) console.log(`INFO     ${line}`);
+for (const line of findings) console.log(`FINDING  ${line}`);
+console.log(
+  findings.length
+    ? `\n${findings.length} finding(s) – material for the grooming conversation, not errors.`
+    : "\nBacklog health OK – nothing mechanical to challenge.",
+);

package/.claude/skills/implement/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: implement
+description: Engineering workflow – implements one story from docs/stories/ test-first on its own branch, verifies, has it reviewed by code-reviewer and acceptance-tester, refactors, and sets it `done` on the acceptance tester's verdict and hands the pull request to the user to merge.
+disable-model-invocation: true
+argument-hint: "[ST-NNN – empty = next ready story]"
+---
+
+# Implement a Story
+
+Story: the arguments from the invocation (empty → `node .claude/skills/implement/scripts/next-story.ts`; a story already `in-progress` is finished first).
+
+The main session writes the code; subagents only review. One checkpoint belongs to the user: the **merge** (step 7). Everything before it runs without asking – a `ready` story is good enough to build up to the pull request, and the acceptance tester accepts the story, not the user – unless the story turns out to be wrong (see *When the story is wrong*) or a seam is missing from the catalog (step 2).
+
+Engineering conventions: `docs/engineering/conventions.md` – read it if it exists; it describes the module layout, how commands and read models are built, and the **seam catalog**.
+
+Project profile: `.claude/project.json` – default branch, code roots, commands, preview provider, pull-request tool. Read it instead of assuming `main`, `npm` or GitHub.
+
+## 1. Prepare
+1. Working tree clean, on the default branch (`repo.defaultBranch`), up to date (`git pull`). Otherwise stop and tell the user.
+2. With a tracker (`backlog.provider` ≠ `local`), pull first (`/backlog-sync pull`) and check that the story has its
+   `external` key – an unlinked story never reaches `ready`, so stop and report instead of implementing a stale mirror.
+3. `node .claude/skills/implement/scripts/story-context.ts ST-NNN` – the context pack: story, exact test titles, dependencies, events/commands/rules/invariants, glossary, data model, ADRs. Read it completely; it is your source, not memory.
+4. `git switch -c st-NNN-<slug>` (slug from the file name), then `node .claude/skills/implement/scripts/story-status.ts ST-NNN in-progress` and commit `ST-NNN: start`.
+
+## 2. Test plan
+Call the `skill` tool for `tdd` (and `codebase-design` when a new module or interface is involved).
+Show one table and go on to step 3 without waiting:
+
+| Scenario (exact test title) | Seam | Test type | Test file |
+|---|---|---|---|
+
+- **Story**: one row per Gherkin scenario. **Tech task**: one row per checklist item that can be tested; the rest gets its evidence named (setting, document). **Spike**: no table – see *Spikes*.
+- Seams come from the seam catalog in the engineering conventions. A seam not in the catalog is a decision for the user – the one case where you stop here and ask.
+- Name anything the story leaves open. Don't guess – see *When the story is wrong*.
+
+Seams from the catalog are the "confirmed seams" the tdd skill requires; the user approved the catalog.
+
+## 3. Red → green, one scenario at a time
+- Per row: write the test (title exactly `ST-NNN: <scenario title>`), run it and see it fail for the right reason, write the minimal code to pass, run it green. Commit: `ST-NNN: <scenario title>`.
+- Domain IDs in the code: commands, events, read models and policies carry their ID from `events.yaml` (`CMD-ReportProblem`, `EVT-ProblemReported`, …). New code uses the words of `CONTEXT.md`; a new term goes into `CONTEXT.md` first (domain-model skill).
+- Never weaken or delete an existing test to get green. If a test from an earlier story blocks you, its story and this one contradict each other → *When the story is wrong*.
+- Hooks help on the way: formatting and lint after every write, the quick gate (type check + related tests) before you finish a turn.
+- In a monorepo, run the affected set for the packages you touched before the full gate:
+  `node .claude/skills/implement/scripts/affected.ts --changed <files>` (or `--base <defaultBranch>`), then
+  execute the printed command. It follows shared-library dependents; `verify.ts` still runs everything at the end.
+
+## 4. Verify
+`node .claude/skills/implement/scripts/verify.ts` (with `--e2e` when browser tests exist) must be green: lint incl. module boundaries, type check, tests, events and stories valid, scenario ↔ test and domain ID traceability. Language warnings: fix or justify.
+
+The full `--e2e` run happens **once, before the push**. During red → green run only the spec you are working on; after the refactor (step 6) run `verify.ts` without `--e2e` plus the specs the refactor touched – CI runs every browser test on the pull request anyway (check `e2e`).
+
+## 5. Review (in parallel, scaled to the story)
+Push the branch (`git push -u origin st-NNN-<slug>`) so a preview deployment exists, when the project has one
+(`review.preview` in `.claude/project.json`: `vercel`, `netlify`, … – use the provider's MCP or CLI, or the pull
+request's preview comment). Otherwise there is no preview and the reviewers work from the code.
+
+Pick the lane first – review effort follows the risk of the diff, not a fixed list:
+
+**Light lane** – when **all** of these hold: size **S**, `events: []`, no command, no migration, no input handling
+(no request handler, form action or route added or changed), no new dependency. Typical: static pages, texts, a
+link, layout.
+- Only `acceptance-tester` – task: story ID, base ref, the preview URL (if known), and: *also check the diff briefly against the engineering conventions (texts from the catalogs, the shared page frames, domain language) and list deviations as minors.* Writes `docs/reviews/ST-NNN-acceptance.md`.
+- No `code-reviewer`, no extra code or security pass.
+
+**Normal lane** – everything else. Start in **one** message:
+- `code-reviewer` – task: story ID, base ref, the context pack command. Writes `docs/reviews/ST-NNN-code-review.md`.
+- `acceptance-tester` – task: story ID, base ref, the preview URL (if known). Writes `docs/reviews/ST-NNN-acceptance.md`.
+- Only for size **L/XL** or a story that changes the command layer or other shared platform code: ask the `code-reviewer` for a second, bug-focused pass over the diff.
+- Only when the **diff** touches input handling, login/roles/session, uploads or files, or security headers/CSP: ask the `code-reviewer` for a security-focused pass.
+
+Say which lane you picked and why in one line.
+
+Tell the reviewers the follow-up hurdle below, so they grade findings with it in mind.
+
+## 6. Refactor
+- Fix all blockers and majors **inside this story**, and the minors you agree with; say which minors you skip and why. Where a finding offers options, apply the recommended one without asking; ask only when no option is recommended or a follow-up story is at stake.
+- **Follow-up hurdle** – a finding becomes a new story only if all of these hold:
+  1. it is a security or data-loss risk, or it blocks a *named* upcoming story;
+  2. it cannot be fixed in this story within about an hour;
+  3. no existing story can take it (check the stories that will first touch that code – prefer adding a checklist item there, via `requirements-engineer`, over a new story).
+  Otherwise it stays a line in the review file ("skipped minor" or "revisit when …") – no story. Say for each follow-up why it passes the hurdle.
+- Follow-ups that pass: delegate to `requirements-engineer` as new tech-task stories (`status: draft`, label `follow-up`), referencing the review file. They go through `/review-stories` like any story.
+- **Foundation just in time**: technical groundwork goes into the first story that needs it, not into a separate tech task ahead of the domain stories – a `must` tech task with met dependencies jumps ahead of every domain story in the backlog order.
+- Refactor only with green tests; the tests must not change unless they were wrong (then say so). Run
+  `affected.ts` for the touched packages, then `node .claude/skills/implement/scripts/verify.ts` again (without
+  `--e2e`) plus the browser specs the refactor touched – see step 4.
+
+## 7. Acceptance and merge → user checkpoint
+The **acceptance tester's verdict is the acceptance**: the story is `done` in the pull request, so the user only merges.
+1. After the refactor, check the verdict in `docs/reviews/ST-NNN-acceptance.md`. `accepted` or `accepted with remarks` → continue. `not accepted` → fix the gaps in the story and run the `acceptance-tester` again, until it accepts. Only when something goes badly wrong – the verdict stays `not accepted` after a second round, a scenario can't be met as written, the preview shows a defect the tester couldn't see – ask the user, the way *When the story is wrong* describes.
+2. `node .claude/skills/implement/scripts/story-status.ts ST-NNN done` – refuses unless every scenario has its test (story) or every checklist item is ticked (spike/tech task) and all dependencies are done. Commit `ST-NNN: done`, push.
+   - GitHub: the status change closes the linked issue.
+   - Jira: `story-status.ts` prints the transition it could not make (MCP is agent-only). Run `jira_get_transitions` +
+     `jira_transition_issue` on the printed key, then push the story body once (`/backlog-sync push`).
+3. Open a pull request: title `ST-NNN: <story title>`, body = the scenarios as a checklist, links to the story and both review files, the acceptance verdict, the preview URL, remaining minors, and anything the user must approve (a conventions change). (No `gh` CLI, or it isn't authenticated: push and give the user the compare URL `git push` prints.)
+4. **The user merges** – on the preview if they want to look first. Afterwards: back to the default branch and `git pull`.
+
+## 8. Wrap-up
+Summarize in a few lines: scenarios implemented, review findings fixed/skipped, follow-ups created, glossary/ADR changes. Then:
+- Suggest `/improve-codebase-architecture` after the foundation stories, when a bounded context is complete, or about every 8–10 done stories.
+- Name the next story (`node .claude/skills/implement/scripts/next-story.ts`) and tell the user to start it in a fresh session (`/new`, then `/implement`): every turn re-reads the whole session, so a second story in the same one costs several times the first.
+
+## Spikes
+A spike answers its **Question** within its **Timebox** – no test plan, no TDD for throwaway experiments.
+- Before starting, tell the user the timebox and what will be kept (skeleton code that becomes the application gets tests and passes verify).
+- Tick each checklist item in the story file as it is answered; write results where the item says (an ADR's consequences, `OPEN_QUESTIONS.md`). A new decision → ADR with `status: proposed` (architect skill); the user accepts.
+- Timebox exhausted → stop, document what is known, and ask the user how to continue.
+- Review: `code-reviewer` only for code that is kept; `acceptance-tester` checks the checklist evidence.
+
+## When the story is wrong
+Never guess. When a scenario contradicts another story, a rule or an ADR, can't be tested as written, or leaves a decision open:
+1. Stop implementing that part. Mark it `[OPEN]` in the story and add a row to `docs/stories/OPEN_QUESTIONS.md`.
+2. `node .claude/skills/implement/scripts/story-status.ts ST-NNN review` and tell the user. The fix goes through discovery: `requirements-engineer` revises the story, `/review-stories` approves it again. Work already done on the branch stays.
+3. New domain term → `CONTEXT.md` (domain-model skill). Architecture deviation → a `proposed` ADR (architect skill). An accepted ADR is never edited; the hooks block it.
+4. A `done` story is never reopened – a change to finished behaviour is a new story.
+
+## Foundation stories
+The first stories build what all others rely on, so they also set up the workflow's tooling:
+- A single quality command in the repository's task runner (e.g. `npm run verify`) that runs
+  `node .claude/skills/implement/scripts/verify.ts`. CI runs the same command.
+- Scripts for `lint` (including module-boundary rules), `typecheck`, `test` and, when there are browser tests,
+  `test:e2e`. Record them under `commands` in `.claude/project.json` – verify and the hooks read them there.
+- The application's lint and type-check configs exclude `.claude/` and `docs/`; the tooling has its own tsconfig.
+- The hooks use Prettier, ESLint, `tsc` and Vitest when they are installed in the app's `node_modules`. With a
+  different toolchain, adapt `.claude/hooks/stop-gate.ts` and `code-check.ts` – they are plain Node.
+- **After the foundation exists** write `docs/engineering/conventions.md` from what now exists (not before):
+  module layout, how a command runs (transaction, journal, authorization, version check), a read model, a
+  time-based rule, UI texts, test data builders and the fixed clock, and the **seam catalog** – which seam each
+  kind of code is tested at. The user approves it; then re-check the stories that depend on the foundation's results.

package/.claude/skills/implement/scripts/affected.ts

@@ -0,0 +1,245 @@
+/**
+ * Which packages are affected by a change, and the command that tests exactly them.
+ *
+ *   node .claude/skills/implement/scripts/affected.ts --changed apps/billing/src/index.ts
+ *   node .claude/skills/implement/scripts/affected.ts --base origin/main
+ *   node .claude/skills/implement/scripts/affected.ts --task lint --run
+ *   node .claude/skills/implement/scripts/affected.ts --json
+ *
+ * The package graph comes from `docs/architecture/repo-map.json` (manifests) plus the optional build-tool
+ * `toolGraph` (Turbo, Nx, Bazel). Dependents are followed transitively: touching a shared library selects the
+ * packages that depend on it. The command is emitted in the repository's own tool (Turbo filters, Nx
+ * run-many, Bazel, …); `--run` executes it.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { ROOT, readRepoMap, scanRepo, type RepoMap, type RepoPackage } from "../../../lib/repo.ts";
+
+const args = process.argv.slice(2);
+
+function usage(): void {
+  console.log(
+    [
+      "Usage: node .claude/skills/implement/scripts/affected.ts [options]",
+      "",
+      "  --changed <file>   a changed file (repeatable or comma-separated; default: git status)",
+      "  --base <ref>       use git diff against this ref (e.g. origin/main)",
+      "  --task <name>      task to run (default: test)",
+      "  --run              execute the emitted command",
+      "  --json             machine-readable result",
+    ].join("\n"),
+  );
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+const json = args.includes("--json");
+const run = args.includes("--run");
+
+const changed: string[] = [];
+let base = "";
+let task = "test";
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === "--changed") {
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) continue;
+    changed.push(...value.split(",").map((f) => f.trim()).filter(Boolean));
+    i += 1;
+  } else if (args[i] === "--base") {
+    const value = args[i + 1];
+    if (value && !value.startsWith("--")) {
+      base = value;
+      i += 1;
+    }
+  } else if (args[i] === "--task") {
+    const value = args[i + 1];
+    if (value && !value.startsWith("--")) {
+      task = value;
+      i += 1;
+    }
+  }
+}
+
+if (changed.length && base) {
+  console.error("Use either --changed or --base, not both.");
+  process.exit(1);
+}
+
+function git(args: string[]): string[] {
+  try {
+    return execFileSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function changedFiles(): string[] {
+  if (changed.length) return [...new Set(changed.map((f) => relative(ROOT, resolve(ROOT, f)).split("\\").join("/")))];
+  if (base) return git(["diff", "--name-only", base]);
+  return git(["status", "--porcelain", "--untracked-files=all"])
+    .map((line) => line.slice(3).trim().replace(/^.* -> /, ""))
+    .filter(Boolean);
+}
+
+function packageForFile(map: RepoMap, file: string): RepoPackage | undefined {
+  return map.packages
+    .filter((p) => p.path === "." || file === p.path || file.startsWith(`${p.path}/`))
+    .sort((a, b) => b.path.length - a.path.length)[0];
+}
+
+function dependentsOf(map: RepoMap): Map<string, Set<string>> {
+  const byName = new Map(map.packages.map((p) => [p.name, p]));
+  const dependents = new Map<string, Set<string>>();
+  const add = (from: string, to: string): void => {
+    if (!byName.has(from) || !byName.has(to) || from === to) return;
+    dependents.set(to, new Set([...(dependents.get(to) ?? []), from]));
+  };
+  for (const pkg of map.packages) for (const dep of pkg.internalDeps) add(pkg.name, dep);
+  for (const edge of map.toolGraph?.edges ?? []) add(edge.from, edge.to);
+  return dependents;
+}
+
+/** Turbo/pnpm/npm only run a task where the package defines the script; Nx/Bazel may infer targets. */
+function runnableForTask(map: RepoMap, packages: RepoPackage[], task: string): RepoPackage[] {
+  switch (map.tooling.kind) {
+    case "turbo":
+    case "pnpm":
+    case "workspaces":
+    case "none":
+      return packages.filter((p) => Boolean(p.scripts[task]));
+    default:
+      return packages;
+  }
+}
+
+function commandFor(map: RepoMap, packages: RepoPackage[], all: boolean): string {
+  const names = packages.map((p) => p.name);
+  const paths = packages.map((p) => p.path);
+  if (all) {
+    switch (map.tooling.kind) {
+      case "turbo": return `turbo run ${task}`;
+      case "nx": return `nx run-many -t ${task}`;
+      case "bazel": return `bazel ${task} //...`;
+      case "pnpm": return `pnpm -r ${task}`;
+      case "workspaces":
+        if (map.tooling.manager === "yarn") return `yarn workspaces run ${task}`;
+        if (map.tooling.manager === "bun") return `bun run --filter '*' ${task}`;
+        return `npm run ${task} --workspaces`;
+      case "go-work": return `go ${task} ./...`;
+      case "cargo-workspace": return `cargo ${task} --workspace`;
+      case "gradle": return `./gradlew ${task}`;
+      case "maven": return `mvn ${task}`;
+      default: return existsSync(join(ROOT, "package.json")) ? `npm run ${task}` : "";
+    }
+  }
+
+  switch (map.tooling.kind) {
+    case "turbo":
+      if (base) return `turbo run ${task} --filter='...[${base}]'`;
+      return names.length ? `turbo run ${task} ${names.map((n) => `--filter=${n}`).join(" ")}` : "";
+    case "nx": {
+      if (base) return `nx affected -t ${task} --base=${base}`;
+      const projects = packages.map(
+        (p) => map.toolGraph?.projectNames?.[p.name] ?? p.projectName ?? p.name.replace(/^@[^/]+\//, ""),
+      );
+      return projects.length ? `nx run-many -t ${task} -p ${projects.join(",")}` : "";
+    }
+    case "bazel":
+      return paths.length ? `bazel ${task} ${paths.map((p) => `//${p}/...`).join(" ")}` : "";
+    case "pnpm":
+      return names.length ? `pnpm ${names.map((n) => `--filter=${n}`).join(" ")} ${task}` : "";
+    case "workspaces":
+      if (map.tooling.manager === "yarn") return names.map((n) => `yarn workspace ${n} ${task}`).join(" && ");
+      if (map.tooling.manager === "bun") return names.length ? `bun run ${names.map((n) => `--filter=${n}`).join(" ")} ${task}` : "";
+      return names.length ? `npm run ${task} ${names.map((n) => `--workspace=${n}`).join(" ")}` : "";
+    case "go-work":
+      return paths.length ? `go ${task} ${paths.map((p) => `./${p}/...`).join(" ")}` : "";
+    case "cargo-workspace":
+      return names.length ? `cargo ${task} ${names.map((n) => `-p ${n}`).join(" ")}` : "";
+    case "gradle":
+      return paths.length ? `./gradlew ${paths.map((p) => `:${p.split("/").join(":")}:${task}`).join(" ")}` : "";
+    case "maven":
+      return paths.length ? `mvn -pl ${paths.join(",")} ${task}` : "";
+    default:
+      return packages.length === 1 && packages[0].scripts[task]
+        ? `npm --prefix ${packages[0].path} run ${task}`
+        : "";
+  }
+}
+
+const map = readRepoMap(ROOT) ?? scanRepo(ROOT, { toolGraph: false });
+const files = changedFiles();
+const changedPackages = new Map<string, RepoPackage>();
+const IGNORED_CHANGED = /^(docs|\.claude|\.opencode|\.github)\//;
+let all = false;
+for (const file of files) {
+  const pkg = packageForFile(map, file);
+  if (pkg) changedPackages.set(pkg.name, pkg);
+  else if (!IGNORED_CHANGED.test(file)) all = true; // root config or an unmapped file can affect everything
+}
+
+const dependents = dependentsOf(map);
+const affected = new Map(changedPackages);
+const queue = [...changedPackages.keys()];
+while (queue.length) {
+  const name = queue.shift()!;
+  for (const dependent of dependents.get(name) ?? []) {
+    if (affected.has(dependent)) continue;
+    const pkg = map.packages.find((p) => p.name === dependent);
+    if (pkg) {
+      affected.set(dependent, pkg);
+      queue.push(dependent);
+    }
+  }
+}
+
+const packages = (all ? map.packages : [...affected.values()]).sort((a, b) => a.path.localeCompare(b.path));
+const runnable = runnableForTask(map, packages, task);
+const command = commandFor(map, runnable, all);
+const source = map.toolGraph
+  ? `${map.toolGraph.source}:${map.toolGraph.task ?? "graph"}+manifests`
+  : "manifests";
+
+if (json) {
+  console.log(JSON.stringify({
+    changed: files,
+    changedPackages: [...changedPackages.values()].map((p) => p.path),
+    affected: packages.map((p) => ({ name: p.name, path: p.path })),
+    all,
+    task,
+    base: base || null,
+    source,
+    command,
+  }, null, 2));
+  process.exit(0);
+}
+
+console.log(`Changed files: ${files.length}`);
+if (!files.length) {
+  console.log("No changed files found – nothing to do.");
+  process.exit(0);
+}
+console.log(`Affected packages (${source}): ${packages.length}${all ? " (all – a root file changed)" : ""}`);
+for (const pkg of packages) console.log(`- ${pkg.path} (${pkg.name})${changedPackages.has(pkg.name) ? " – changed" : ""}`);
+if (runnable.length !== packages.length) {
+  console.log(`Only ${runnable.length} of them define a '${task}' task.`);
+}
+if (!packages.length) {
+  console.log("No package matched the changed files – run the full gate (verify.ts).");
+  process.exit(0);
+}
+console.log("");
+console.log(`Command:\n  ${command || "(no command for this tooling – run verify.ts)"}`);
+
+if (run) {
+  if (!command) process.exit(1);
+  const result = spawnSync(command, { cwd: ROOT, shell: true, stdio: "inherit" });
+  process.exit(result.status ?? 1);
+}

package/.claude/skills/implement/scripts/check-commands.ts

@@ -0,0 +1,37 @@
+/**
+ * Traceability between the event storming model and the code.
+ * Commands, events, read models etc. are referenced in the code by their ID from docs/domain/events.yaml
+ * (e.g. a command is registered as "CMD-ReportProblem", a journal entry has type "EVT-ProblemReported").
+ *
+ *   ERROR  an ID in the code that does not exist in events.yaml (renamed or invented)
+ *   INFO   which commands and read models are implemented
+ *
+ * Usage: node check-commands.ts [--verbose]
+ */
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+
+const model = d.loadEventsModel();
+if (model === null) {
+  console.error("docs/domain/events.yaml is missing or invalid.");
+  process.exit(1);
+}
+const idx = d.indexModel(model);
+const used = e.domainIdsInCode();
+const report = new d.Report();
+for (const [id, files] of used) {
+  if (!idx.has(id)) report.error(files.join(", "), `'${id}' does not exist in docs/domain/events.yaml`);
+}
+
+const coverage = (key: string): string => {
+  const all = (model[key] ?? []) as d.Obj[];
+  const done = all.filter((x) => used.has(x.id));
+  return `${done.length}/${all.length} ${key.replace("_", " ")} in code`;
+};
+console.log(`INFO     ${coverage("commands")} · ${coverage("read_models")} · ${coverage("policies")}`);
+if (process.argv.includes("--verbose")) {
+  for (const c of (model.commands ?? []) as d.Obj[]) console.log(`INFO     ${used.has(c.id) ? "✓" : " "} ${c.id}`);
+}
+for (const line of report.lines()) console.log(line);
+console.log(report.ok ? "Domain ID traceability OK." : `${report.errors.length} error(s).`);
+process.exit(report.ok ? 0 : 1);