kataster 0.3.1 → 0.6.0

package/.claude/skills/adopt/SKILL.md

@@ -2,7 +2,7 @@
 name: adopt
 description: Brownfield entry point – maps the repository, adopts it in slices (one domain plus at most one shared library), drafts the domain model with evidence, grills the user, documents each package where it lives and records the gap; it derives stories only when asked (--stories). Use when the workflow is dropped into a repository that already has code.
 disable-model-invocation: true
-argument-hint: "[scope, e.g. 'apps/billing' or 'the order process' – empty = map the repository and choose a slice; add --stories to derive stories now]"
+argument-hint: "[package path or concept scope (--paths/--route/--table/--event/--cluster/term) – empty = map the repository and choose a slice; add --stories to derive stories now]"
 ---
 
 # Adopt an Existing Repository
@@ -20,10 +20,12 @@ kebab-case slug for the adoption (`adoption-<scope>`) for the report file.
 1. Read `.claude/project.json`. If it is missing, tell the user to run `npx kataster init` first and stop.
 2. If the repository has no code yet, this is the wrong command: use `/bootstrap`.
 3. Read what already exists, before analysing anything: `CONTEXT.md`, `docs/product/vision.md`,
-   `docs/domain/events.yaml`, `docs/domain/context-map.md`, `docs/architecture/data-model.md`,
-   `docs/architecture/repo-map.md`, `docs/engineering/conventions.md`, `docs/adr/`, `README*`, existing `docs/`
-   and any `AGENTS.md`/`CLAUDE.md`. Existing documentation is **primary evidence** – it outranks your inference
-   from code. Contradictions between docs and code are findings, not something to resolve silently.
+   `docs/domain/events.yaml`, `docs/domain/context-map.md` (**target**), `docs/domain/context-map.as-is.md`
+   (**as-is**), `docs/architecture/data-model.md`, `docs/architecture/repo-map.md`,
+   `docs/engineering/conventions.md`, `docs/adr/`, `README*`, existing `docs/` and any `AGENTS.md`/`CLAUDE.md`.
+   Existing documentation is **primary evidence** – it outranks your inference from code. The target map is
+   read-only here: it says where the project wants to go, not what the code does. Contradictions between docs and
+   code are findings, not something to resolve silently.
 
 ## Phase 0 – Repository map (deterministic, no questions)
 
@@ -33,10 +35,10 @@ Run:
 node .claude/skills/adopt/scripts/repo-map.ts
 ```
 
-It scans manifests and git history and writes:
+It scans manifests, source files and git history and writes:
 
-- `docs/architecture/repo-map.json` – packages, paths, kinds, internal dependencies, consumers, adoption ranking,
-  and the build tool's own graph when it answers (Turbo, Nx, Bazel)
+- `docs/architecture/repo-map.json` – packages, paths, kinds, roles, internal dependencies, consumers, adoption
+  ranking, concept-slice suggestions, and the build tool's own graph when it answers (Turbo, Nx, Bazel)
 - `docs/architecture/repo-map.md` – the same as a readable map (never edit it by hand)
 - the generated repository block in `AGENTS.md` – tooling, layout, commands, adopted slices
 - `.claude/project.json` → `repo.tooling` – Nx, Turborepo, Bazel, pnpm/npm/yarn workspaces, Go, Cargo, Gradle, Maven
@@ -44,20 +46,47 @@ It scans manifests and git history and writes:
 Read the map yourself. **Do not hand-scan the repository for packages**; if the map is stale, run it again.
 The map is facts, not domain: it says where code lives and what depends on what, never what a word means.
 
+Pay attention to two readings the map adds for layered repositories:
+
+- **Layer packages** – generic names such as `services`, `repositories` or `utils` that host many concepts. They
+  are layers, not domains; do not adopt “the services package” as if it were one bounded context.
+- **Concept slices** – clusters that share a file stem or a table across layers (`ordersController`,
+  `orderService`, `orderRepository`, `orders` table). They are slice *suggestions*, not confirmed boundaries.
+
 ## Phase 1 – Choose the slice (one round, at most three questions)
 
-The map suggests a first slice. Ask, each with a recommended answer:
+The scope is either a package path, a **concept scope** or a mix. A concept scope can be:
+
+- a glob set: `--paths "src/api/order*,src/services/order*,db/migrations/*order*"`
+- an entry point: `--route "POST /orders"`, `--table orders`, `--event EVT-OrderPlaced`
+- a suggestion from the map: `--cluster order`
+- a free term: `--term order`
+
+Resolve a non-package scope deterministically before asking:
+
+```bash
+node .claude/skills/adopt/scripts/slice.ts --cluster order
+node .claude/skills/adopt/scripts/slice.ts --table orders
+node .claude/skills/adopt/scripts/slice.ts --route "POST /orders"
+```
+
+The resolver follows imports in both directions, adds same-concept files from other layers and prints the
+candidate files with reasons. **It is evidence, not a verdict** – show the candidates and let the user confirm the
+scope. If the resolver finds nothing, widen it with `--paths` or `--term`; do not invent a boundary.
+
+Ask, each with a recommended answer:
 
-1. **Slice**: the suggested domain plus its most-used shared library, or a different one? Recommended: the
-   suggestion from `repo-map.md` – it weighs recent churn, fan-in and kind, not size.
+1. **Slice**: the suggested concept or domain plus its most-used shared library, or a different one? Recommended:
+   the suggestion from `repo-map.md` – in a layered repository, prefer the concept slice over the package.
 2. **Intent**: a domain model for future work, a map for onboarding, or a backlog for a rewrite? Recommended:
    the domain model first; the other two follow from it.
 3. **Language**: confirm `languages.ui` and `languages.artifacts` from the profile. Recommended: what the code
    and UI already use.
 
-Hard rule: **one domain plus at most one shared library per session.** A simple repository without monorepo
-tooling is one slice – then the whole repository is in scope. Never "the whole monorepo"; a shallow map of 80
-packages is worse than a confirmed model of two.
+Hard rule: **one concept or domain plus at most one shared library per session.** The scope may cross packages
+and layers – a domain is not a package. A simple repository without monorepo tooling is one slice only when its
+code is not layered; otherwise use the resolver. Never "the whole monorepo"; a shallow map of 80 packages is worse
+than a confirmed model of two.
 
 Create `docs/domain/adoption-report.md` with the answers under `## Scope`; fill the rest as you go. If earlier
 slices are already adopted, name the next one and what changed since it was adopted (`git log --since=<date>`).
@@ -67,8 +96,9 @@ slices are already adopted, name the next one and what changed since it was adop
 Call the `skill` tool for `grilling`, `domain-model` and `architect` first: grilling sets how you ask,
 domain-model sets what you are looking for, architect decides what becomes an ADR.
 
-Dispatch `repo-analyst` subagents **in one message**, each with the slice path, the repository map path and one
-lens. They are read-only.
+Dispatch `repo-analyst` subagents **in one message**, each with the confirmed scope (the package path or the
+resolved file list), the repository map path and one lens. They are read-only. For a concept slice, say which
+files are in scope and which layer they belong to; do not let an analyst widen the scope on its own.
 
 - **Monorepo / several packages**: three analysts.
   | Lens | What it looks for |
@@ -89,25 +119,46 @@ Merge the reports into one picture. Write the artifacts **as a draft**, every un
 - **`CONTEXT.md`** – only the slice's terms, grouped by guessed bounded context, competing spellings under
   `_Avoid_`, `[OPEN]` where the meaning is unclear. Do not touch terms of other slices.
 - **`docs/domain/events.yaml`** – 10–25 candidate events/commands/actors/read models/policies/flows for this
-  slice. Every uncertainty becomes a hotspot (`HS-n`, `status: open`).
-- **`docs/domain/context-map.md`** – the boundaries the module structure suggests, marked as a proposal.
+  slice. Every uncertainty becomes a hotspot (`HS-n`, `status: open`). Every aggregate carries a status:
+  `as-is` with `evidence` (table, service method, path) when the code shows a factual consistency boundary, or
+  `unresolved` plus an open hotspot when the boundary is unclear. **Never `target` for a boundary inferred from
+  code** – a target is a decision the user makes, not a reading of the repository.
+- **`docs/domain/context-map.as-is.md`** – the boundaries the module structure actually shows, with evidence.
+  Create it from `.claude/skills/adopt/templates/context-map.as-is.md` on the first slice (replace
+  `{{project}}`, `{{date}}` and `{{commit}}`) and add one `### BC-… – <name>` section per recovered context
+  (the gap register links those headings). **Never write
+  `docs/domain/context-map.md`** – that is the target map, owned by `/bootstrap`, `/shape`, `/feature`,
+  `/event-storming` and `/improve-codebase-architecture`. If no target exists yet, leave it absent; the gap
+  register shows “target not decided”.
 - **`docs/architecture/data-model.md`** – the **as-is** model for the slice, derived from schema and code.
 - **`docs/engineering/conventions.md`** – fill what the slice actually does: module layout, how a command runs,
   read models, "now", texts, test data, seam catalog. Include how the monorepo tooling is used.
 - **`docs/product/vision.md`** – only if missing or empty, reconstruct and mark `[OPEN]`.
 - **`docs/adr/`** – de-facto decisions worth recording, `status: proposed`. Only the user accepts.
-- **Package docs** – for the domain and the shared library (in a monorepo):
-  ```bash
-  node .claude/skills/adopt/scripts/package-doc.ts apps/billing
-  node .claude/skills/adopt/scripts/package-doc.ts libs/shared-kernel
-  ```
-  A single-package repository has no package file: its root `AGENTS.md` is the package doc (`package-doc.ts .`
-  deliberately refuses). The script writes `<package>/AGENTS.md` (source of truth) and `<package>/CLAUDE.md`
-  (`@AGENTS.md`, for Claude Code's on-demand nested loading). It generates the facts block; **you** fill the prose
-  during the grilling:
+- **Domain docs** – choose the mechanism by scope, not by habit:
+  - **Real domain package** (the code lives in one package): write `<package>/AGENTS.md` + `<package>/CLAUDE.md`
+    with `package-doc.ts`:
+    ```bash
+    node .claude/skills/adopt/scripts/package-doc.ts apps/billing
+    node .claude/skills/adopt/scripts/package-doc.ts libs/shared-kernel
+    ```
+  - **Cross-cutting concept slice** (the domain is spread over `api/`, `services/`, `repositories/`, …): write a
+    path-scoped document under `.claude/rules/` instead, so both harnesses load it when a matching file is
+    touched:
+    ```bash
+    node .claude/skills/adopt/scripts/slice-doc.ts order \
+      --context BC-Order \
+      --paths "src/api/order*,src/services/order*,src/repositories/order*" \
+      --title "Order"
+    ```
+    Do **not** also write a package `AGENTS.md` for the same concept – one mechanism per scope.
+  A single-package repository without layers has no package file: its root `AGENTS.md` is the package doc
+  (`package-doc.ts .` deliberately refuses). The package script writes `<package>/AGENTS.md` (source of truth) and
+  `<package>/CLAUDE.md` (`@AGENTS.md`, for Claude Code's on-demand nested loading). It generates the facts block;
+  **you** fill the prose during the grilling:
   - domain/service: Purpose, Key entities, External interfaces, Typical pitfalls, Boundaries
   - shared library: Purpose, Public API, Consumers, Compatibility rules, Typical pitfalls, Boundaries
-  Keep each file under ~80 lines. This file is loaded only when someone works in that package.
+  Keep each file under ~80 lines. This file is loaded only when someone works in that package or path.
 - **Root `AGENTS.md`** – the generated block comes from the map. Below it, add only structure, commands, hard
   conventions and links. Keep at most ten bullets under `## Hard conventions`, each naming where it is enforced
   (`lint`, a test, `.claude/rules/<file>.md`, `docs/engineering/checks.yaml`) – a rule without an enforcement
@@ -138,7 +189,9 @@ skill says: numbered questions, each with a recommended answer, whole frontier p
 Questions brownfield needs, roughly in this order:
 
 1. **Terms** – one question per cluster of competing spellings, worst first.
-2. **Boundaries** – which package owns which state; where a shared library ends and a domain begins.
+2. **Boundaries** – which package owns which state; where a shared library ends and a domain begins. For every
+   aggregate: is this the factual consistency boundary (`as-is`), is it unclear (`unresolved` + hotspot), or is
+   this the boundary we want (`target`, a decision)? Prefer `as-is`/`unresolved` over an invented aggregate.
 3. **Lifecycle** – states the schema allows, transitions it does not block.
 4. **Invariants** – what the code checks only in the UI; what must always hold.
 5. **Missing behaviour** – what has no trace: never needed, or a gap?
@@ -209,11 +262,22 @@ backlog. Write the table into `docs/domain/adoption-report.md`; open questions g
 `docs/stories/OPEN_QUESTIONS.md` or a hotspot. This keeps the model reviewable without committing to work the
 user has not prioritised.
 
+Run the gap register after the grilling and before the report:
+
+```bash
+node .claude/skills/adopt/scripts/gap-register.ts
+```
+
+Every `as-is` aggregate gets a generated row with its evidence and its as-is/target context links; every
+`unresolved` aggregate gets a row that names its open hotspot. Add the decisions outside the managed block.
+
 Only when the invocation contains `--stories`, or the user explicitly asks after seeing the table:
 
-- delegate to `requirements-engineer` with the **selected** gaps only, the confirmed IDs from `events.yaml`, the
-  label `adoption:<slug>`, and `ui` for stories with a frontend part;
-- new stories start as `status: draft`; the ones the user wants first go through `/review-stories`.
+- write the stories yourself as the spec engineer (the `user-stories` skill is the method) with the **selected**
+  gaps only, the confirmed IDs from `events.yaml`, `type: domain` with one `command` and its `aggregate`, `ui: true`
+  for stories with a frontend part, and the label `adoption:<slug>`;
+- new stories start as `status: draft`; the ones the user wants first go through the spec linter and
+  `/review-stories`.
 
 **Do not write stories for behaviour that already works** – that turns the backlog into a description of the
 past. Existing behaviour is covered by its tests, and the domain model is the map. If an earlier run created
@@ -231,7 +295,8 @@ Date: YYYY-MM-DD · Commit: <sha> · Slice: <paths> · Analysts: <n> lenses
 ## Repository map (tooling, packages, why this slice)
 ## What the repository is (facts)
 ## Confirmed domain model
-- contexts, aggregates, glossary changes
+- contexts, aggregates (with status), glossary changes
+- as-is context map and the target links the gap register found
 ## Package documentation written
 - <path>/AGENTS.md + CLAUDE.md – what was confirmed and what stays [OPEN]
 ## Contradictions found and how they were resolved
@@ -246,7 +311,11 @@ Date: YYYY-MM-DD · Commit: <sha> · Slice: <paths> · Analysts: <n> lenses
 Mark the slice adopted so the next session sees the progress:
 
 ```bash
+# a real domain package
 node .claude/skills/adopt/scripts/repo-map.ts --adopt apps/billing
+
+# a concept slice across layers
+node .claude/skills/adopt/scripts/repo-map.ts --adopt-slice order
 ```
 
 Then run `node .claude/skills/event-storming/scripts/validate-events.ts` and
@@ -268,8 +337,16 @@ checks created, gap candidates (and stories only if requested), ADRs proposed. T
 
 - **Never change production code in `/adopt`.** Tests and tooling are allowed only as the safety net above.
 - **Never present an inference as a fact.** Confidence and evidence, or a hotspot.
+- **Aggregates are honest.** `as-is` needs evidence; `unresolved` needs an open hotspot; `target` is a user
+  decision. An invented aggregate is worse than an unresolved one – it makes the story look ready when it is not.
+- **Adopt writes as-is, never target.** `docs/domain/context-map.as-is.md` and the `as-is` aggregates describe
+  the repository. The target map (`docs/domain/context-map.md`) and `target` aggregates are decisions made in
+  `/bootstrap`, `/shape` or `/feature` – do not “fix” them while adopting.
 - **The user owns the language.** You may propose a better word; you may not rename the domain on your own.
-- **Adopt in slices.** One domain plus at most one shared library. Never the whole monorepo in one pass.
+- **Slice by concept, not by package.** In a layered repository a domain runs through `api/`, `services/` and
+  `repositories/`. Use the concept clusters and the resolver; never treat a generic `services`/`utils` package as
+  a domain just because it has a manifest.
+- **Adopt in slices.** One concept or domain plus at most one shared library. Never the whole monorepo in one pass.
 - **The root `AGENTS.md` stays free of domain.** Structure, commands, hard conventions and links only.
 - **Package docs are short and on demand.** `<package>/AGENTS.md` + `<package>/CLAUDE.md`, under ~80 lines.
 - **Directory docs before glob rules.** `.claude/rules/` is for patterns a directory cannot express. Both

package/.claude/skills/adopt/scripts/gap-register.ts

@@ -0,0 +1,61 @@
+/**
+ * Writes or checks `docs/domain/gap-register.md` – one generated row per as-is or unresolved aggregate.
+ *
+ *   node .claude/skills/adopt/scripts/gap-register.ts          # create or refresh the managed block
+ *   node .claude/skills/adopt/scripts/gap-register.ts --check  # exit 1 when the block is stale (advisory in verify)
+ *   node .claude/skills/adopt/scripts/gap-register.ts --json
+ *
+ * Decisions and manual gaps live outside the managed block; a hand-written file without markers is left alone.
+ * A missing register is not an error: a project that has not adopted anything yet has no gap register.
+ */
+import { checkGapRegister, writeGapRegister } from "../../../lib/gaps.ts";
+import { rel, ROOT } from "../../../lib/discovery.ts";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(
+    [
+      "Usage: node .claude/skills/adopt/scripts/gap-register.ts [--check|--json]",
+      "",
+      "  (no option)  create or refresh docs/domain/gap-register.md",
+      "  --check      exit 1 when the generated block is stale",
+      "  --json       machine-readable result",
+    ].join("\n"),
+  );
+  process.exit(0);
+}
+
+if (args.includes("--check")) {
+  const result = checkGapRegister();
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log(`OK – gap register: ${result.reason}.`);
+  } else {
+    console.error(`Gap register: ${result.reason}.`);
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+try {
+  const result = writeGapRegister();
+  if (result === null) {
+    console.log("No gap register written.");
+    process.exit(0);
+  }
+  const path = rel(result.path);
+  if (result.status === "created") console.log(`Created ${path}.`);
+  else if (result.status === "updated") console.log(`Refreshed the generated block in ${path}.`);
+  else if (result.status === "unchanged") console.log(`Kept ${path}: already up to date.`);
+  else if (result.status === "kept") console.log(`Kept ${path}: it has no generated markers, so it is treated as hand-written.`);
+  if (args.includes("--json")) console.log(JSON.stringify({ ...result, path: rel(result.path) }, null, 2));
+  console.log(
+    `As-is and target context maps: ${rel(join(ROOT, "docs", "domain", "context-map.as-is.md"))} / ` +
+      `${rel(join(ROOT, "docs", "domain", "context-map.md"))}.`,
+  );
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/.claude/skills/adopt/scripts/repo-map.ts

@@ -9,7 +9,7 @@
  * The map is generated from manifests and git history. It is not a domain model: it says where code lives,
  * how packages depend on each other and which slice to adopt first. Domain meaning comes from the grilling.
  */
-import { ROOT, findPackage, markAdopted, packageCounts, proposeSlices, readRepoMap, scanRepo, stableMap, updateProjectTooling, writeRepoMap, writeRootBlock } from "../../../lib/repo.ts";
+import { ROOT, findPackage, markAdopted, markSliceAdopted, packageCounts, proposeSlices, readRepoMap, scanRepo, stableMap, updateProjectTooling, writeRepoMap, writeRootBlock } from "../../../lib/repo.ts";
 import { graphLabel, graphToolLabel } from "../../../lib/toolgraph.ts";
 
 const args = process.argv.slice(2);
@@ -24,6 +24,7 @@ function usage(): void {
       "  --json          print the map as JSON without writing",
       "  --check         exit 1 when the checked-in map no longer matches the repository",
       "  --adopt <path>  mark a package as adopted (after the grilling)",
+      "  --adopt-slice <name>  mark a concept slice as adopted",
       "  --no-tool-graph skip the build-tool graph query (Turbo/Nx/Bazel); manifest graph only",
     ].join("\n"),
   );
@@ -53,6 +54,24 @@ if (adoptIndex !== -1) {
   process.exit(0);
 }
 
+const adoptSliceIndex = args.indexOf("--adopt-slice");
+if (adoptSliceIndex !== -1) {
+  const name = args[adoptSliceIndex + 1];
+  if (!name) {
+    console.error("--adopt-slice needs a concept name, e.g. order");
+    process.exit(1);
+  }
+  try {
+    markSliceAdopted(root, name);
+    console.log(`Adopted concept slice: ${name}`);
+    console.log("The root AGENTS.md block now lists it as adopted.");
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 const map = scanRepo(root, {
   // --check stays fast and environment-independent; the graph is enrichment, not part of the stable map.
   toolGraph: !args.includes("--check") && !args.includes("--no-tool-graph"),
@@ -67,6 +86,13 @@ if (previous) {
       pkg.adoptedAt = old.adoptedAt;
     }
   }
+  for (const slice of map.slices ?? []) {
+    const old = previous.slices?.find((entry) => entry.name === slice.name);
+    if (old?.adopted) {
+      slice.adopted = true;
+      slice.adoptedAt = old.adoptedAt;
+    }
+  }
 }
 
 if (args.includes("--json")) {
@@ -114,10 +140,16 @@ console.log(`Packages: ${map.packages.length} (${packageCounts(map)})`);
 if (profileUpdated) console.log("Updated .claude/project.json → repo.tooling");
 if (agentsUpdated) console.log("Updated the generated repository block in AGENTS.md");
 
+if (proposal.cluster) {
+  console.log("");
+  console.log(`Suggested concept slice: ${proposal.cluster.name} (${proposal.cluster.layers.join(", ") || "one layer"})`);
+  console.log(`  Start with: node .claude/skills/adopt/scripts/slice.ts --cluster ${proposal.cluster.name}`);
+  console.log(`  Mark it adopted after the grilling: node .claude/skills/adopt/scripts/repo-map.ts --adopt-slice ${proposal.cluster.name}`);
+}
 if (proposal.domain) {
   console.log("");
   const label = proposal.domain.path === "." ? "root package" : proposal.domain.path;
-  console.log(`Suggested first slice: ${label} (${proposal.domain.name})`);
+  console.log(`Suggested package slice: ${label} (${proposal.domain.name})`);
   if (proposal.library) console.log(`  with shared library: ${proposal.library.path} (${proposal.library.name})`);
   console.log(`Mark it adopted after the grilling: node .claude/skills/adopt/scripts/repo-map.ts --adopt ${proposal.domain.path}`);
 }

package/.claude/skills/adopt/scripts/slice-doc.ts

@@ -0,0 +1,117 @@
+/**
+ * Writes a path-scoped domain document for a concept slice that crosses packages or layers.
+ *
+ *   node .claude/skills/adopt/scripts/slice-doc.ts order \
+ *     --context BC-Order \
+ *     --paths "src/api/order*,src/services/order*,src/repositories/order*" \
+ *     --title "Order"
+ *
+ * The file lands in `.claude/rules/<slug>.md` with `paths:` frontmatter. Claude Code scopes it natively;
+ * OpenCode's plugin attaches it when a matching file is read or written. A real domain package still gets
+ * `<package>/AGENTS.md` through package-doc.ts – this command is for the cross-cutting case, not a duplicate.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { relPath } from "../../../lib/architecture.ts";
+import { ROOT } from "../../../lib/repo.ts";
+
+const args = process.argv.slice(2);
+
+function usage(): void {
+  console.log(
+    [
+      "Usage: node .claude/skills/adopt/scripts/slice-doc.ts <slug> --paths <glob> [--paths <glob>] [--context BC-…] [--title <title>]",
+      "",
+      "Creates .claude/rules/<slug>.md for a concept slice that crosses packages or layers.",
+    ].join("\n"),
+  );
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+const slug = args.find((arg) => !arg.startsWith("--"));
+const paths: string[] = [];
+let context = "";
+let title = "";
+for (let i = 0; i < args.length; i += 1) {
+  const take = (): string | undefined => {
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) return undefined;
+    i += 1;
+    return value;
+  };
+  if (args[i] === "--paths") {
+    const value = take();
+    if (value) paths.push(...value.split(",").map((p) => p.trim()).filter(Boolean));
+  } else if (args[i] === "--context") {
+    context = take() ?? context;
+  } else if (args[i] === "--title") {
+    title = take() ?? title;
+  }
+}
+
+if (!slug || !/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+  console.error("The slug must be kebab-case (a-z, 0-9, -).");
+  process.exit(1);
+}
+if (!paths.length) {
+  console.error("At least one --paths glob is required.");
+  process.exit(1);
+}
+
+const path = join(ROOT, ".claude", "rules", `${slug}.md`);
+if (existsSync(path)) {
+  console.error(`${relPath(ROOT, path)} already exists – edit it instead of overwriting.`);
+  process.exit(1);
+}
+
+const heading = title || slug.replaceAll("-", " ").replace(/^\w/, (c) => c.toUpperCase());
+const frontmatter = `paths:\n${paths.map((p) => `  - ${JSON.stringify(p)}`).join("\n")}`;
+const contextLine = context ? ` (${context})` : "";
+const content = [
+  "---",
+  frontmatter,
+  "---",
+  "",
+  `# ${heading}${contextLine}`,
+  "",
+  `> Concept slice across layers. Recovered by \`/adopt\`; the target boundary lives in \`docs/domain/context-map.md\`.`,
+  "",
+  "## Purpose",
+  "",
+  "[OPEN] Why does this concept exist? One or two sentences, in the domain's words.",
+  "",
+  "## Key terms",
+  "",
+  "[OPEN] The terms from `CONTEXT.md` this slice owns or changes; aggregate IDs from `docs/domain/events.yaml`.",
+  "",
+  "## As-is boundary",
+  "",
+  "[OPEN] Tables, service methods, entry points and paths that hold this slice together today. Evidence, not guesses.",
+  "",
+  "## Boundaries",
+  "",
+  "- May change: [OPEN]",
+  "- Must not change: [OPEN]",
+  "- Cross-context communication: only through published contracts or events.",
+  "",
+  "## Typical pitfalls",
+  "",
+  "[OPEN] What breaks here? From tests, incidents and git history – not guesses.",
+  "",
+  "## Read next",
+  "",
+  "- `docs/architecture/repo-map.md`",
+  "- `CONTEXT.md`",
+  "- `docs/domain/events.yaml`",
+  "- `docs/domain/context-map.md` and `docs/domain/context-map.as-is.md`",
+  "",
+].join("\n");
+
+mkdirSync(dirname(path), { recursive: true });
+writeFileSync(path, content, "utf8");
+console.log(`Created ${relPath(ROOT, path)}.`);
+console.log("Fill the [OPEN] sections during the grilling – do not invent domain meaning.");

package/.claude/skills/adopt/scripts/slice.ts

@@ -0,0 +1,163 @@
+/**
+ * Resolves a concept scope to candidate files across all layers.
+ *
+ *   node .claude/skills/adopt/scripts/slice.ts --paths "src/api/order*,src/services/order*,db/migrations/*order*"
+ *   node .claude/skills/adopt/scripts/slice.ts --route "POST /orders"
+ *   node .claude/skills/adopt/scripts/slice.ts --table orders
+ *   node .claude/skills/adopt/scripts/slice.ts --event EVT-OrderPlaced
+ *   node .claude/skills/adopt/scripts/slice.ts --cluster order
+ *   node .claude/skills/adopt/scripts/slice.ts --term order
+ *
+ * The resolver follows imports in both directions, adds same-concept files from other layers and prints the
+ * candidate set with reasons. It is evidence, not a verdict: `/adopt` confirms the scope with the user.
+ */
+import { readRepoMap } from "../../../lib/repo.ts";
+import { resolveSlice, type EventLookup, type ResolveOptions } from "../../../lib/slices.ts";
+import * as d from "../../../lib/discovery.ts";
+
+const args = process.argv.slice(2);
+
+function usage(): void {
+  console.log(
+    [
+      "Usage: node .claude/skills/adopt/scripts/slice.ts <scope> [options]",
+      "",
+      "Scope (at least one):",
+      "  --paths <glob>    a file glob (repeatable or comma-separated)",
+      "  --route <route>   an entry point, e.g. 'POST /orders' or '/orders'",
+      "  --table <name>    a table name from schema or code",
+      "  --event <id>      an event, command or aggregate ID from events.yaml",
+      "  --cluster <name>  a concept slice from the repository map",
+      "  --term <word>     a domain term from file names or code",
+      "",
+      "Options:",
+      "  --max-files <n>   cap the candidate set (default 200)",
+      "  --depth <n>       import/reverse-import hops (default 2)",
+      "  --json            machine-readable result",
+    ].join("\n"),
+  );
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+const options: ResolveOptions = { paths: [] };
+let eventId = "";
+for (let i = 0; i < args.length; i += 1) {
+  const take = (): string | undefined => {
+    const v = args[i + 1];
+    if (!v || v.startsWith("--")) return undefined;
+    i += 1;
+    return v;
+  };
+  switch (args[i]) {
+    case "--paths": {
+      const v = take();
+      if (v) options.paths!.push(...v.split(",").map((p) => p.trim()).filter(Boolean));
+      break;
+    }
+    case "--route":
+      options.route = take() ?? options.route;
+      break;
+    case "--table":
+      options.table = take() ?? options.table;
+      break;
+    case "--event":
+      eventId = take() ?? eventId;
+      break;
+    case "--cluster":
+      options.cluster = take() ?? options.cluster;
+      break;
+    case "--term":
+      options.term = take() ?? options.term;
+      break;
+    case "--max-files": {
+      const v = Number(take());
+      if (Number.isFinite(v) && v > 0) options.maxFiles = v;
+      break;
+    }
+    case "--depth": {
+      const v = Number(take());
+      if (Number.isFinite(v) && v >= 0) options.depth = v;
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+if (eventId) {
+  const model = d.loadEventsModel();
+  if (model === null) {
+    console.error("--event needs a readable docs/domain/events.yaml.");
+    process.exit(1);
+  }
+  const idx = d.indexModel(model);
+  const item = idx.get(eventId) ?? [...idx.entries()].find(([id]) => id.toLowerCase() === eventId.toLowerCase())?.[1];
+  if (!item) {
+    console.error(`'${eventId}' is not in events.yaml.`);
+    process.exit(1);
+  }
+  const list = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
+  const terms = new Set<string>();
+  if (typeof item.name === "string") terms.add(item.name);
+  if (typeof item.aggregate === "string") {
+    terms.add(item.aggregate);
+    const aggregate = idx.get(item.aggregate);
+    if (typeof aggregate?.name === "string") terms.add(aggregate.name);
+  }
+  for (const command of (model.commands ?? []) as d.Obj[]) {
+    if (!list(command.produces).includes(item.id)) continue;
+    terms.add(String(command.id));
+    if (typeof command.name === "string") terms.add(command.name);
+  }
+  const lookup: EventLookup = { id: item.id, terms: [...terms] };
+  options.event = lookup;
+}
+
+const map = readRepoMap(d.ROOT);
+if (!map) {
+  console.error("No docs/architecture/repo-map.json yet – run `node .claude/skills/adopt/scripts/repo-map.ts` first.");
+  process.exit(1);
+}
+
+const hasScope =
+  Boolean(options.paths?.length) ||
+  Boolean(options.route || options.table || options.event || options.cluster || options.term);
+if (!hasScope) {
+  usage();
+  process.exit(1);
+}
+
+const result = resolveSlice(d.ROOT, map, options);
+if (args.includes("--json")) {
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.seeds.length ? 0 : 1);
+}
+
+console.log(`Scope: ${result.query}`);
+if (result.seeds.length) {
+  console.log(`\nSeeds (${result.seeds.length}):`);
+  for (const seed of result.seeds) console.log(`- ${seed.file} – ${seed.reasons.join("; ")}`);
+} else {
+  console.log("\nNo seed file found.");
+}
+
+if (result.files.length) {
+  console.log(`\nCandidate files (${result.files.length}):`);
+  for (const [layer, files] of Object.entries(result.byLayer)) {
+    console.log(`\n## ${layer}`);
+    for (const file of files) {
+      const entry = result.files.find((candidate) => candidate.file === file);
+      console.log(`- ${file} – ${entry?.reasons.join("; ") ?? ""}`);
+    }
+  }
+}
+
+for (const warning of result.warnings) console.log(`\nWARNING ${warning}`);
+if (result.files.length) {
+  console.log("\nThis is a candidate scope, not a verdict. Confirm it with the user before dispatching the analysts.");
+}
+process.exit(result.seeds.length ? 0 : 1);