kataster 0.3.1 → 0.6.0

package/.claude/lib/discovery.ts

@@ -15,7 +15,8 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { parse as parseYaml, YAMLError } from "yaml";
-import { isManagedLabel, labelPrefix, loadBacklogConfig } from "./config.ts";
+import { isManagedLabel, labelPrefix, loadBacklogConfig, loadResearchConfig } from "./config.ts";
+import * as research from "./research.ts";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Obj = Record<string, any>;
@@ -44,13 +45,49 @@ const KIND_LABEL: Record<string, string> = {
  * `superseded`: never built as written – its work was done elsewhere (a direct change, another story) or a new planning
  * replaces it. The file stays as the record other documents link to; it is final and counts toward no progress (user,
  * 2026-10-25).
+ *
+ * `ready-for-human-review` is set by the linter gate: a story whose spec passes every mechanical check waits there
+ * until the user approves it as `ready`. Engineering only picks up `ready` stories.
+ */
+export const STATUSES = ["draft", "review", "ready-for-human-review", "ready", "in-progress", "done", "superseded"] as const;
+/** Statuses that require a finished story: no [OPEN] markers and a consistent spec. */
+export const COMMITTED = new Set(["ready-for-human-review", "ready", "in-progress", "done"]);
+/** Statuses handed to engineering or the tracker: the tracker link is required from `ready` on, not before. */
+const HANDOFF = new Set(["ready", "in-progress", "done"]);
+/**
+ * 1 command + 1 aggregate, at most 4 scenarios: one happy path and up to three edge/error cases. Each scenario is a
+ * red → green cycle in /implement; more than four means the story merges commands or restates UX guidelines.
+ */
+export const MAX_SCENARIOS = 4;
+/**
+ * Story types.
+ *
+ *   domain     – full DDD/TDD path: exactly one command on one aggregate, Gherkin traceability, reviews
+ *   chore/task – fast lane: UI tweaks, refactorings, dependencies, setup; no Gherkin matching, no formal reviews
+ *   tech-task  – deliberate technical groundwork with a checklist
+ *   spike      – a timeboxed question
+ *   story      – the legacy name of `domain`; still valid, reported as a warning
  */
-export const STATUSES = ["draft", "review", "ready", "in-progress", "done", "superseded"] as const;
-/** Statuses that require a finished story: size set, no [OPEN] markers. */
-export const COMMITTED = new Set(["ready", "in-progress", "done"]);
-export const MAX_SCENARIOS = 10;
+export const DOMAIN_TYPES = new Set(["domain", "story"]);
+export const FAST_TYPES = new Set(["chore", "task"]);
+export const LEGACY_TYPES: Record<string, string> = { story: "domain" };
 const PRIORITIES = ["must", "should", "could", "wont"];
 
+/**
+ * Aggregate status.
+ *
+ *   target     – the boundary the project wants (the default; a missing field means target)
+ *   as-is      – the factual consistency boundary recovered from code, with evidence
+ *   unresolved – the boundary is unclear; it needs an open hotspot and grilling, and no story on it can be ready
+ */
+export const AGGREGATE_STATUSES = ["target", "as-is", "unresolved"] as const;
+export type AggregateStatus = (typeof AGGREGATE_STATUSES)[number];
+
+export function aggregateStatus(aggregate: Obj | undefined): AggregateStatus {
+  const value = aggregate?.status;
+  return value === "as-is" || value === "unresolved" ? value : "target";
+}
+
 // --------------------------------------------------------------------------
 // Report
 // --------------------------------------------------------------------------
@@ -82,6 +119,13 @@ const list = (v: unknown): string[] => (Array.isArray(v) ? v : []);
 const items = (model: Obj, key: string): Obj[] => list(model[key]) as unknown as Obj[];
 const prefix = (id: string): string => id.split("-", 1)[0];
 
+/** Domain story: full DDD/TDD path. `story` is the legacy name of `domain`. */
+export const isDomain = (meta: Obj): boolean => DOMAIN_TYPES.has(String(meta.type));
+/** Fast lane: chore or task – no Gherkin matching, no formal subagent reviews. */
+export const isFastLane = (meta: Obj): boolean => FAST_TYPES.has(String(meta.type));
+/** A story with a frontend part: the explicit `ui: true` flag, or the legacy `ui` label. */
+export const isUi = (meta: Obj): boolean => meta.ui === true || list(meta.labels).includes("ui");
+
 /** Resolves symlinks where possible so paths from hooks and from ROOT compare equal. */
 export function realPath(p: string): string {
   try {
@@ -277,6 +321,25 @@ export function validateEvents(report: Report): Obj | null {
   for (const h of items(m, "hotspots")) ref(h.id, "refs", h.refs, allButFlow);
   for (const f of items(m, "flows")) ref(f.id, "sequence", f.sequence, allButFlow);
 
+  // Aggregate status: as-is is a factual boundary and needs evidence; unresolved needs an open question.
+  const openHotspotRefs = new Set(
+    items(m, "hotspots")
+      .filter((h) => (h.status ?? "open") === "open")
+      .flatMap((h) => list(h.refs)),
+  );
+  for (const a of items(m, "aggregates")) {
+    const status = aggregateStatus(a);
+    if (status === "as-is" && !list(a.evidence).length) {
+      report.error(
+        where,
+        `${a.id}: status 'as-is' needs evidence – name the table, service method or path that marks the consistency boundary`,
+      );
+    }
+    if (status === "unresolved" && !openHotspotRefs.has(a.id)) {
+      report.warn(where, `${a.id}: status 'unresolved' without an open hotspot – add HS-… with refs: [${a.id}]`);
+    }
+  }
+
   // Heuristic warnings (non-blocking)
   const produced = new Set(items(m, "commands").flatMap((c) => list(c.produces)));
   const policyCmds = new Set(items(m, "policies").flatMap((p) => list(p.then)));
@@ -404,6 +467,17 @@ export function renderEventStorming(model: Obj): string {
     out.push("");
   }
 
+  // Aggregate status: target, as-is (factual, with evidence) or unresolved (needs grilling).
+  if (it("aggregates").length) {
+    out.push("## Aggregates", "", "| Aggregate | Context | Status | Evidence |", "|---|---|---|---|");
+    for (const a of it("aggregates")) {
+      const context = a.context ? idx.get(a.context)?.name ?? a.context : "–";
+      const evidence = list(a.evidence).map((e) => String(e).replaceAll("|", "\\|")).join("<br>") || "–";
+      out.push(`| ${a.name} (\`${a.id}\`) | ${context} | ${aggregateStatus(a)} | ${evidence} |`);
+    }
+    out.push("");
+  }
+
   // Hotspots
   const hs = it("hotspots").filter((h) => (h.status ?? "open") === "open");
   if (hs.length) {
@@ -489,8 +563,8 @@ export const SCENARIO_RE = /^\s*(?:Scenario Outline|Scenario Template|Scenario|E
 
 function checkBody(r: Report, where: string, meta: Obj, body: string): void {
   const secs = sections(body);
-  const type = meta.type;
-  if (type === "story") {
+  const type = String(meta.type);
+  if (isDomain(meta)) {
     const s = section(secs, "story");
     if (s === null) {
       r.error(where, "section '## Story' is missing");
@@ -499,7 +573,9 @@ function checkBody(r: Report, where: string, meta: Obj, body: string): void {
     }
   }
   if (type === "spike" && section(secs, "question") === null) r.error(where, "spike needs a '## Question' section");
-  if (type === "tech-task" && section(secs, "task") === null) r.error(where, "tech task needs a '## Task' section");
+  if (type === "tech-task" || type === "task" || type === "chore") {
+    if (section(secs, "task") === null) r.error(where, `${type} needs a '## Task' section`);
+  }
 
   const ac = section(secs, "acceptance criteria");
   if (ac === null) {
@@ -511,12 +587,11 @@ function checkBody(r: Report, where: string, meta: Obj, body: string): void {
   const titles = scenarios.map((sc) => sc.split("\n")[0].trim().toLowerCase());
   const dupes = titles.filter((t, n) => t && titles.indexOf(t) !== n);
   if (dupes.length) r.error(where, `scenario titles must be unique within the story: ${[...new Set(dupes)].join(", ")}`);
-  if (type === "story") {
+  if (isDomain(meta)) {
     if (scenarios.length < 2) r.error(where, "at least 2 Gherkin scenarios required (happy path + error/edge case)");
     scenarios.forEach((sc, n) => {
-      if (!/^\s*When\b/m.test(sc) || !/^\s*Then\b/m.test(sc)) {
-        r.error(where, `scenario ${n + 1}: 'When' and 'Then' are required`);
-      }
+      const missing = ["Given", "When", "Then"].filter((step) => !new RegExp(`^\\s*${step}\\b`, "m").test(sc));
+      if (missing.length) r.error(where, `scenario ${n + 1}: ${missing.join(", ")} required (Gherkin Given/When/Then)`);
     });
   } else if (!scenarios.length && !/^\s*[-*]\s*\[[ xX]\]/m.test(ac)) {
     r.error(where, "give acceptance criteria as scenarios or a checklist ('- [ ] …')");
@@ -554,8 +629,8 @@ export function scenarioTitlesIn(body: string): string[] {
  * and stays the authority.
  */
 export function completenessWarnings(story: Story): string[] {
-  if (story.meta.type !== "story") return []; // spikes and tech tasks carry checklists, not screens
-  if (!list(story.meta.labels).includes("ui")) return [];
+  if (!isDomain(story.meta)) return []; // fast lane, spikes and tech tasks carry checklists, not screens
+  if (!isUi(story.meta)) return [];
   const ac = section(sections(story.body), "acceptance criteria") ?? "";
   if (!ac.trim()) return [];
   const titles = scenarioTitlesIn(story.body);
@@ -609,6 +684,7 @@ export function validateStories(report: Report, only: string | null = null, leni
   const stories = new Map<string, Story>();
   for (const s of parsed) if (storyId(s)) stories.set(storyId(s), s);
   const backlog = loadBacklogConfig();
+  const researchCfg = loadResearchConfig();
 
   for (const s of parsed) {
     const r = isMine(s.path) ? report : new Report();
@@ -638,24 +714,113 @@ export function validateStories(report: Report, only: string | null = null, leni
         else r.error(where, msg);
       }
     }
-    const status = m.status;
-    if (COMMITTED.has(status) && !m.size) r.error(where, `size is missing – lead-dev must estimate before '${status}'`);
-    if (m.size === "XL") {
-      const msg = "size XL – split the story";
-      if (COMMITTED.has(status)) r.error(where, msg);
-      else r.warn(where, msg);
+    const status = String(m.status);
+    const type = String(m.type);
+    // The strict 1-command rules apply to the new `domain` type. `story` is the legacy name and stays valid
+    // (warnings only), so an upgrade does not turn an existing backlog red.
+    const strict = type === "domain";
+    if (LEGACY_TYPES[type]) {
+      r.warn(where, `type '${type}' is the legacy name of '${LEGACY_TYPES[type]}' – use '${LEGACY_TYPES[type]}'`);
+    }
+    if (!isDomain(m) && !isFastLane(m) && type !== "spike" && type !== "tech-task") {
+      r.error(where, `unknown type '${type}' (domain, chore, task, tech-task, spike)`);
+    }
+    if (strict) {
+      if (!m.context) r.error(where, "domain story needs a bounded context ('context: BC-…')");
+      if (!m.aggregate) r.error(where, "domain story needs exactly one aggregate ('aggregate: AGG-…')");
+      if (!m.command) r.error(where, "domain story needs exactly one command ('command: CMD-…')");
+    }
+    if (isDomain(m) && !strict) {
+      if (!m.aggregate || !m.command) {
+        r.warn(where, "legacy story without aggregate/command – the 1-command rule cannot be checked; migrate it to type: domain");
+      }
+    }
+    if (idx !== null) {
+      const ctx = m.context;
+      if (typeof ctx === "string" && ctx && (!idx.has(ctx) || prefix(ctx) !== "BC")) {
+        r.error(where, `context '${ctx}' does not exist in events.yaml`);
+      }
+      for (const ev of list(m.events)) {
+        if (!idx.has(ev) || prefix(ev) !== "EVT") r.error(where, `event '${ev}' does not exist in events.yaml`);
+      }
+      if (m.aggregate !== undefined) {
+        if (typeof m.aggregate !== "string" || !idx.has(m.aggregate) || prefix(m.aggregate) !== "AGG") {
+          r.error(where, `aggregate '${fmt(m.aggregate)}' does not exist in events.yaml`);
+        }
+      }
+      if (m.command !== undefined) {
+        if (typeof m.command !== "string" || !idx.has(m.command) || prefix(m.command) !== "CMD") {
+          r.error(where, `command '${fmt(m.command)}' does not exist in events.yaml`);
+        }
+      }
+      // The 1-command rule: one story = one command + its events on one aggregate.
+      const cmd = typeof m.command === "string" ? idx.get(m.command) : undefined;
+      if (cmd && typeof m.aggregate === "string" && cmd.aggregate && cmd.aggregate !== m.aggregate) {
+        r.error(where, `command '${m.command}' belongs to aggregate '${cmd.aggregate}', not '${m.aggregate}'`);
+      }
+      if (strict && cmd) {
+        const produced = list(cmd.produces);
+        const linked = list(m.events);
+        if (!produced.length) {
+          r.error(where, `command '${m.command}' produces no event in events.yaml`);
+        } else {
+          const missing = produced.filter((ev) => !linked.includes(ev));
+          const extra = linked.filter((ev) => !produced.includes(ev));
+          if (missing.length || extra.length) {
+            r.error(
+              where,
+              `events must be exactly what command '${m.command}' produces (${produced.join(", ")})` +
+                (missing.length ? ` – missing: ${missing.join(", ")}` : "") +
+                (extra.length ? ` – not produced: ${extra.join(", ")}` : ""),
+            );
+          }
+        }
+      }
+      const aggregate = typeof m.aggregate === "string" ? idx.get(m.aggregate) : undefined;
+      if (aggregate && aggregateStatus(aggregate) === "unresolved") {
+        const msg =
+          `aggregate '${m.aggregate}' is unresolved – the consistency boundary is not settled; ` +
+          "resolve its hotspot in grilling before the story can be ready";
+        if (COMMITTED.has(status)) r.error(where, msg);
+        else r.warn(where, msg);
+      }
+    } else if (isDomain(m)) {
+      // Without a readable model the required fields are checked above; the cross-check cannot run.
+      r.warn(where, "events.yaml is missing or invalid – the aggregate/command cross-check was skipped");
     }
-    // Every scenario is a red → green cycle in /implement; past ten the story is too big or restates UX
-    // guideline patterns (user, 2026-10-26). `ready` ones were approved under the older rules.
+    for (const dep of list(m.depends_on)) {
+      if (dep === id) {
+        r.error(where, "depends on itself");
+      } else if (!stories.has(dep)) {
+        const msg = `depends_on '${dep}' does not exist`;
+        if (lenientDeps) r.warn(where, msg);
+        else r.error(where, msg);
+      }
+    }
+    // Research is evidence, not a specification. A gated story must cite at least one source before the linter
+    // gate; the hard check runs on the status transition (engineering.ts). Expiry belongs to verify.ts.
+    const sourceRefs = research.sourceRefs(m);
+    for (const ref of sourceRefs) {
+      if (!research.isValidSourceRef(ref)) {
+        r.warn(where, `source '${ref}' is neither an http(s) URL nor a docs/research/<topic>.md reference`);
+      } else if (research.isLocalResearchRef(ref) && !existsSync(research.researchPath(ref))) {
+        r.warn(where, `research source '${ref}' does not exist – collect it with /research or remove the reference`);
+      }
+    }
+    if ((status === "draft" || status === "review") && sourceRefs.length === 0) {
+      const trigger = research.researchGateRequired(m, researchCfg);
+      if (trigger) r.warn(where, `${trigger} requires at least one 'sources:' entry before ready-for-human-review`);
+    }
+
+    if (m.size === "XL") r.warn(where, "size XL – split the story");
+    // Every scenario is a red → green cycle in /implement; past four the story merges commands or restates UX
+    // guideline patterns. Domain stories must obey it; legacy `story` files get a warning until migrated.
     const scenarioTotal = scenarioTitlesIn(s.body).length;
-    if (m.type === "story" && scenarioTotal > MAX_SCENARIOS && (status === "draft" || status === "review")) {
-      const msg = `${scenarioTotal} scenarios, at most ${MAX_SCENARIOS} – split the story, or reference the UX guideline (G-number) instead of restating its pattern as scenarios`;
-      if (status === "review") r.error(where, msg);
+    if (isDomain(m) && scenarioTotal > MAX_SCENARIOS && (status === "draft" || status === "review" || status === "ready-for-human-review")) {
+      const msg = `${scenarioTotal} scenarios, at most ${MAX_SCENARIOS} – split the story (one command, one aggregate), or reference the UX guideline (G-number) instead of restating its pattern as scenarios`;
+      if (strict && status !== "draft") r.error(where, msg);
       else r.warn(where, msg);
     }
-    if (m.type === "story" && COMMITTED.has(status) && !list(m.events).length) {
-      r.warn(where, "no domain events linked – traceability is missing");
-    }
 
     // In tracker mode the Markdown file is a mirror. A story that is handed to engineering must carry its
     // external key, otherwise the next pull cannot match it and the tracker is not the source of truth any more.
@@ -668,7 +833,7 @@ export function validateStories(report: Report, only: string | null = null, leni
           r.error(where, "external.key is missing");
         }
       }
-      if (COMMITTED.has(status) && !(ext && typeof ext === "object" && typeof ext.key === "string" && ext.key)) {
+      if (HANDOFF.has(status) && !(ext && typeof ext === "object" && typeof ext.key === "string" && ext.key)) {
         r.error(where, `not linked to the ${backlog.provider} backlog – run /backlog-sync push before '${status}'`);
       }
       const prefix = labelPrefix(backlog);
@@ -680,7 +845,9 @@ export function validateStories(report: Report, only: string | null = null, leni
     checkBody(r, where, m, s.body);
     // Completeness is checked while a story is being written; `ready` ones were approved under the older rules
     // and are challenged in `/groom-backlog` instead (user, 2026-10-01).
-    if (status === "draft" || status === "review") for (const w of completenessWarnings(s)) r.warn(where, w);
+    if (status === "draft" || status === "review" || status === "ready-for-human-review") {
+      for (const w of completenessWarnings(s)) r.warn(where, w);
+    }
   }
 
   // Cycles in depends_on
@@ -710,6 +877,7 @@ export function validateStories(report: Report, only: string | null = null, leni
 const STATUS_TITLES: [string, string][] = [
   ["in-progress", "In Progress"],
   ["ready", "Ready"],
+  ["ready-for-human-review", "Ready for Human Review"],
   ["review", "In Review"],
   ["draft", "Draft"],
   ["done", "Done"],
@@ -763,14 +931,14 @@ export function renderBacklog(stories: Story[], model: Obj | null): string {
     );
   }
   if (!stories.length) {
-    out.push("_No stories yet. Derive them from the event storming with `@requirements-engineer`._", "");
+    out.push("_No stories yet. Derive them from the event storming as a spec engineer (main session)._", "");
     return out.join("\n");
   }
 
   const counts = STATUS_TITLES.map(([st, title]) => [title, stories.filter((s) => s.meta.status === st).length] as const);
   // Progress is measured in domain stories and their scenarios, not in the total number of stories (CLAUDE.md).
   // A superseded story was never built as one – its work counts where it was done.
-  const domain = stories.filter((s) => s.meta.type === "story" && s.meta.status !== "superseded");
+  const domain = stories.filter((s) => isDomain(s.meta) && s.meta.status !== "superseded");
   const scenarioCount = (s: Story) =>
     (section(sections(s.body), "acceptance criteria") ?? "")
       .split("\n")

package/.claude/lib/engineering.ts

@@ -13,6 +13,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, join } from "node:path";
 import * as d from "./discovery.ts";
+import * as research from "./research.ts";
 
 const list = (v: unknown): string[] => (Array.isArray(v) ? v : []);
 
@@ -66,13 +67,15 @@ export const testTitle = (id: string, scenario: string): string => `${id}: ${sce
 // Status workflow
 // --------------------------------------------------------------------------
 /**
- * Allowed single steps. Discovery owns draft/review/ready; engineering moves ready → in-progress → done
- * and sends a story back to review when it turns out to be wrong. `done` is final: changes to finished
- * behaviour become a new story.
+ * Allowed single steps. Discovery owns draft/review/ready-for-human-review; the linter sets the review state, the
+ * user approves `ready`. Engineering moves ready → in-progress → done and sends a story back to review when it turns
+ * out to be wrong. `done` is final: changes to finished behaviour become a new story.
  */
 const TRANSITIONS: Record<string, string[]> = {
   draft: ["review", "superseded"],
-  review: ["draft", "ready", "superseded"],
+  review: ["draft", "ready-for-human-review", "superseded"],
+  // The linter gate passed; only the user turns this into `ready`.
+  "ready-for-human-review": ["draft", "review", "ready", "superseded"],
   ready: ["review", "in-progress", "superseded"],
   "in-progress": ["review", "done"],
   done: [],
@@ -106,7 +109,7 @@ export function transitionErrors(story: d.Story, from: string, to: string, stori
     errs.push(
       from === "done" || from === "superseded"
         ? `a ${from} story is never reopened – capture the change as a new story`
-        : `status '${from}' cannot become '${to}' (workflow: draft → review → ready → in-progress → done, back to review when a story is wrong; superseded from any status before in-progress)`,
+        : `status '${from}' cannot become '${to}' (workflow: draft → review → ready-for-human-review → ready → in-progress → done, back to review when a story is wrong; superseded from any status before in-progress)`,
     );
     return errs;
   }
@@ -114,8 +117,17 @@ export function transitionErrors(story: d.Story, from: string, to: string, stori
     const open = list(story.meta.depends_on).filter((dep) => stories.get(dep)?.meta.status !== "done");
     if (open.length) errs.push(`depends on stories that are not done yet: ${open.join(", ")}`);
   }
+  // The research gate is deterministic and applies at the status change, never retroactively: an existing `ready`
+  // or `done` story is not re-opened because the gate learned about its risk after approval.
+  if (to === "ready-for-human-review" || to === "ready") {
+    errs.push(...research.researchGateErrors(story.meta));
+  }
+  // The linter gate and the user's approval are two separate steps; skipping one defeats the workflow.
+  if (to === "ready" && from !== "ready-for-human-review") {
+    errs.push("'ready' needs 'ready-for-human-review' first – run the spec linter and let the user approve");
+  }
   if (to === "done") {
-    if (story.meta.type === "story") {
+    if (d.isDomain(story.meta)) {
       const cov = scenarioCoverage(story);
       if (cov.missing.length) {
         errs.push(`scenarios without a test titled '${d.storyId(story)}: <scenario title>': ${cov.missing.map((m) => `"${m}"`).join(", ")}`);

package/.claude/lib/gaps.ts

@@ -0,0 +1,179 @@
+/**
+ * The gap register: the bridge between the as-is domain recovered from code and the target model.
+ *
+ * Every aggregate with `status: as-is` or `status: unresolved` gets one generated row. The row links the
+ * aggregate in `events.yaml`, the as-is context map and the target context map, so a reader sees both sides of
+ * the gap in one place. Decisions and manual gaps stay outside the managed block and survive a refresh.
+ *
+ * `docs/domain/context-map.md` is the target map; `docs/domain/context-map.as-is.md` is written by `/adopt`.
+ * Missing files are not an error: a project that has not adopted anything yet has no gap register either.
+ *
+ * Node >= 22.18, erasable TypeScript only. No runtime dependency.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import * as d from "./discovery.ts";
+
+export const GAP_REGISTER_FILE = "docs/domain/gap-register.md";
+export const GAP_BEGIN = "<!-- kataster:gap-register:begin -->";
+export const GAP_END = "<!-- kataster:gap-register:end -->";
+export const AS_IS_CONTEXT_MAP = "docs/domain/context-map.as-is.md";
+export const TARGET_CONTEXT_MAP = "docs/domain/context-map.md";
+
+const list = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
+
+export interface ContextEntry {
+  id: string;
+  heading: string;
+  anchor: string;
+}
+
+export interface GapRegisterResult {
+  path: string;
+  status: "created" | "updated" | "unchanged" | "kept";
+}
+
+const cell = (value: unknown): string =>
+  String(value ?? "").replaceAll("|", "\\|").replaceAll("\n", "<br>") || "–";
+
+/** GitHub-style heading anchor, close enough for the context maps the skills write. */
+export function headingAnchor(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+    .trim()
+    .replace(/\s/g, "-");
+}
+
+/**
+ * Reads `BC-…` headings from a context map. The heading may carry the display name after a dash:
+ * `### BC-Order – Order` and `## BC-Order` both work.
+ */
+export function contextEntries(path: string): Map<string, ContextEntry> {
+  const out = new Map<string, ContextEntry>();
+  if (!existsSync(path)) return out;
+  const text = readFileSync(path, "utf8");
+  for (const line of text.split("\n")) {
+    const match = /^(#{2,4})\s+(BC-[A-Za-z0-9]+)(?:\s+[–-]\s+(.+?))?\s*$/.exec(line);
+    if (!match) continue;
+    const heading = line.replace(/^#{2,4}\s+/, "").trim();
+    out.set(match[2], { id: match[2], heading, anchor: headingAnchor(heading) });
+  }
+  return out;
+}
+
+function contextLink(file: string, entries: Map<string, ContextEntry>, id: string | undefined): string {
+  if (!id) return "–";
+  const entry = entries.get(id);
+  // No heading means the context is not documented on this side yet – that is the gap, not a broken link.
+  return entry ? `[${entry.id}](${basename(file)}#${entry.anchor})` : "–";
+}
+
+/** The generated rows. Kept separate from the rest of the file so refresh and --check share one renderer. */
+export function renderGapBlock(model: d.Obj | null): string {
+  const aggregates = model ? ((model.aggregates ?? []) as d.Obj[]) : [];
+  const asIs = contextEntries(join(d.ROOT, AS_IS_CONTEXT_MAP));
+  const target = contextEntries(join(d.ROOT, TARGET_CONTEXT_MAP));
+  const openHotspots = model
+    ? ((model.hotspots ?? []) as d.Obj[]).filter((h) => (h.status ?? "open") === "open")
+    : [];
+  const hotspotFor = (id: string): string | undefined =>
+    openHotspots.find((h) => list(h.refs).includes(id))?.id;
+
+  const rows: string[] = [
+    GAP_BEGIN,
+    "<!-- Generated from docs/domain/events.yaml by gap-register.ts. Do not edit inside this block. -->",
+    "| Gap | Kind | Aggregate | As-is | Target | Evidence | Next step |",
+    "|---|---|---|---|---|---|---|",
+  ];
+
+  for (const aggregate of aggregates) {
+    const id = String(aggregate.id ?? "");
+    const status = d.aggregateStatus(aggregate);
+    if (status !== "as-is" && status !== "unresolved") continue;
+    const slug = id.replace(/^AGG-/, "");
+    const context = typeof aggregate.context === "string" ? aggregate.context : undefined;
+    const hotspot = status === "unresolved" ? hotspotFor(id) : undefined;
+    const targetLink = contextLink(TARGET_CONTEXT_MAP, target, context);
+    const asIsLink = contextLink(AS_IS_CONTEXT_MAP, asIs, context);
+    const evidence = list(aggregate.evidence).map(cell).join("<br>") || "–";
+    const next =
+      status === "unresolved"
+        ? hotspot
+          ? `Grill the boundary (${hotspot}); no story on it can be ready`
+          : "Grill the boundary; add an open hotspot first"
+        : targetLink === "–"
+          ? "Decide the target boundary"
+          : "Confirm the target boundary or keep it as-is";
+    rows.push(
+      `| GAP-AGG-${cell(slug)} | ${status === "as-is" ? "as-is boundary" : "unresolved boundary"} | ` +
+        `[${id}](events.yaml) | ${asIsLink} | ${targetLink} | ${evidence} | ${next} |`,
+    );
+  }
+
+  if (rows.length === 4) rows.push("| – | – | – | – | – | – | no as-is or unresolved aggregate yet |");
+  rows.push(GAP_END);
+  return rows.join("\n");
+}
+
+function emptyRegister(block: string): string {
+  return [
+    "# Gap register",
+    "",
+    "> Generated rows come from `docs/domain/events.yaml`; decisions and manual gaps live outside the managed block.",
+    `> As-is map: [${basename(AS_IS_CONTEXT_MAP)}](${basename(AS_IS_CONTEXT_MAP)}) · Target map: [${basename(TARGET_CONTEXT_MAP)}](${basename(TARGET_CONTEXT_MAP)}).`,
+    "",
+    block,
+    "",
+    "## Decisions",
+    "",
+    "- none yet",
+    "",
+  ].join("\n");
+}
+
+function replaceBlock(existing: string, block: string): string | null {
+  const start = existing.indexOf(GAP_BEGIN);
+  const stop = existing.indexOf(GAP_END);
+  if (start === -1 || stop === -1 || stop <= start) return null;
+  return `${existing.slice(0, start)}${block}${existing.slice(stop + GAP_END.length)}`.replace(/\n{3,}/g, "\n\n");
+}
+
+/**
+ * Writes or refreshes the managed block. With `onlyIfExists`, a missing register stays missing (used by the
+ * PostToolUse hook, so a greenfield project is not given an empty artifact).
+ */
+export function writeGapRegister(options: { onlyIfExists?: boolean } = {}): GapRegisterResult | null {
+  const path = join(d.ROOT, GAP_REGISTER_FILE);
+  const model = d.loadEventsModel();
+  const block = renderGapBlock(model);
+
+  if (!existsSync(path)) {
+    if (options.onlyIfExists) return null;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, emptyRegister(block), "utf8");
+    return { path, status: "created" };
+  }
+
+  const existing = readFileSync(path, "utf8");
+  const next = replaceBlock(existing, block);
+  if (next === null) return { path, status: "kept" };
+  if (next === existing) return { path, status: "unchanged" };
+  writeFileSync(path, next, "utf8");
+  return { path, status: "updated" };
+}
+
+export function checkGapRegister(): { ok: boolean; reason: string } {
+  const path = join(d.ROOT, GAP_REGISTER_FILE);
+  if (!existsSync(path)) return { ok: true, reason: "no gap register yet – /adopt creates it" };
+  const existing = readFileSync(path, "utf8");
+  const start = existing.indexOf(GAP_BEGIN);
+  const stop = existing.indexOf(GAP_END);
+  if (start === -1 || stop === -1 || stop <= start) {
+    return { ok: true, reason: "the gap register has no managed block – treated as hand-written" };
+  }
+  const block = renderGapBlock(d.loadEventsModel());
+  return replaceBlock(existing, block) === existing
+    ? { ok: true, reason: "up to date" }
+    : { ok: false, reason: "stale – run node .claude/skills/adopt/scripts/gap-register.ts" };
+}

package/.claude/lib/glob.ts

@@ -0,0 +1,39 @@
+/**
+ * Repository-relative glob matching shared by the architecture rules and the slice resolver.
+ * No dependencies, no project knowledge.
+ */
+import { sep } from "node:path";
+
+export function toPosixPath(path: string): string {
+  return path.split(sep).join("/");
+}
+
+export function globToRegExp(glob: string): RegExp {
+  const pattern = toPosixPath(glob);
+  let out = "^";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i];
+    if (c === "*") {
+      if (pattern[i + 1] === "*") {
+        i += 1;
+        if (pattern[i + 1] === "/") {
+          i += 1;
+          out += "(?:.*/)?";
+        } else {
+          out += ".*";
+        }
+      } else {
+        out += "[^/]*";
+      }
+    } else if (c === "?") {
+      out += "[^/]";
+    } else {
+      out += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`${out}$`);
+}
+
+export function matchesAny(path: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => globToRegExp(pattern).test(path));
+}