kataster 0.3.1 → 0.6.0

package/guide/brownfield.md

@@ -9,6 +9,9 @@ npx kataster init --brownfield
 /adopt                      # map the repository, then choose a slice
 /adopt apps/billing         # adopt one package
 /adopt libs/shared-kernel   # adopt a shared library
+/adopt --cluster order      # adopt a concept across api/, services/, repositories/
+/adopt --table orders       # start from a table and resolve the layers behind it
+/adopt --route "POST /orders"  # start from an entry point
 ```
 
 ## Adopt in slices, not in one pass
@@ -20,15 +23,21 @@ A monorepo with eighty packages cannot be understood in one session. `/adopt` th
 2. **One slice** – one domain plus at most one shared library. Deep evidence, grilling, package docs, checks.
    Then the next slice in a later session.
 
-The map is generated from manifests and git history:
+The map is generated from manifests, source files and git history:
 
-- `docs/architecture/repo-map.json` – packages, paths, kinds, internal dependencies, consumers, adoption ranking
+- `docs/architecture/repo-map.json` – packages, paths, kinds, roles, internal dependencies, consumers, adoption
+  ranking, concept-slice suggestions
 - `docs/architecture/repo-map.md` – the same as a readable map, plus dependency edges and a suggested first slice
 - the **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
 
 The map is facts, not domain. It says where code lives, never what a word means.
 
+In a layered repository (`api/`, `services/`, `repositories/`, `utils/`) a package is not a domain. The map marks
+generic packages as **layer packages** and clusters files by shared concept stems and tables. A domain such as
+“order” shows up as an `order` slice across all layers; `slice.ts` resolves the candidate files from a cluster, a
+table, a route, an event ID, a glob or a term. The resolver is evidence – you confirm the scope.
+
 ## What `/adopt` does
 
 ### 1. Chooses the slice with you
@@ -56,18 +65,26 @@ A monorepo gets three lenses:
 A small repository without monorepo tooling gets the five classic lenses: structure and stack, domain language,
 data and integrations, behaviour and tests, history and decisions.
 
+For a concept slice, the analysts receive the confirmed file list from `slice.ts`, not only a package path. They
+report facts inside that scope; widening the slice is the user's decision, not theirs.
+
 Each analyst returns facts with `path:line`, candidate vocabulary, candidate events/commands/read models,
 contradictions, and questions with a recommended answer. Confidence is `high`, `medium` or `low`.
 
 ### 4. Drafts the slice
 
 - `CONTEXT.md` – the slice's terms, competing spellings under `_Avoid_`
-- `docs/domain/events.yaml` – 10–25 candidate events, commands, actors, read models, flows, hotspots
-- `docs/domain/context-map.md`, `docs/architecture/data-model.md` (as-is)
+- `docs/domain/events.yaml` – 10–25 candidate events, commands, actors, read models, flows, hotspots. Each
+  aggregate is `as-is` with evidence (table, service method, path) or `unresolved` with an open hotspot – never
+  an invented `target`
+- `docs/domain/context-map.as-is.md` (recovered boundaries, with evidence) and
+  `docs/architecture/data-model.md` (as-is). The target map `docs/domain/context-map.md` is read, never written
+  here; if it does not exist yet, the gap register says “target not decided”.
 - `docs/engineering/conventions.md` – how the code actually works today, including the monorepo tooling
 - `docs/adr/` – de-facto decisions worth recording (`status: proposed`)
-- **package docs** – `<package>/AGENTS.md` plus `<package>/CLAUDE.md`, written by
-  `node .claude/skills/adopt/scripts/package-doc.ts <path>`
+- **domain docs, by scope** – a real domain package gets `<package>/AGENTS.md` plus `<package>/CLAUDE.md` from
+  `package-doc.ts <path>`; a cross-cutting concept slice gets `.claude/rules/<context>.md` with `paths:` from
+  `slice-doc.ts <slug> --context BC-… --paths "…"`. One mechanism per scope, never both.
 
 Everything uncertain is marked. The draft is a proposal, not a verdict.
 
@@ -92,19 +109,25 @@ baseline of existing violations; only new violations fail. A hook that is red on
 `/adopt` may add characterization tests and tooling. It never changes production code, and it never writes a test
 that fails on existing behaviour – that would be a story.
 
+The same net carries into `/implement`: `characterize.ts --story ST-NNN` names the affected source files and the
+tests it can find. A path with no test for the behaviour that is about to change gets a characterization test
+first – current behaviour pinned, green on unchanged code, committed separately, then the story's red → green loop.
+If the current behaviour contradicts the story, the story goes back to `review`; the test is not bent to fit.
+
 ### 7. Records the gap – stories only on request
 
 | Class | Default |
 |---|---|
-| Exists and is intended | Documentation (data model, context map) – no action |
+| Exists and is intended | Documentation (data model, as-is context map) – no action |
 | Exists but contradicts the model | Candidate in the gap register |
 | Missing | Candidate in the gap register |
 | Dead | Candidate: removal or an explicit "leave it" |
 
-**The first adoption pass creates no stories.** It records the gap in `docs/domain/adoption-report.md` (and open
-questions in `OPEN_QUESTIONS.md`), so the model can be reviewed before anyone commits to work. Only
-`/adopt <scope> --stories` (or an explicit "turn these into stories") delegates the selected gaps to
-`requirements-engineer`.
+**The first adoption pass creates no stories.** It records the gap in `docs/domain/adoption-report.md` and
+`docs/domain/gap-register.md` (one generated row per `as-is`/`unresolved` aggregate, with the as-is and target
+context links), and open questions in `OPEN_QUESTIONS.md`, so the model can be reviewed before anyone commits to
+work. Only `/adopt <scope> --stories` (or an explicit "turn these into stories") turns the selected gaps into
+stories in the main session (spec engineer, spec linter gate).
 
 **Behaviour that already works does not become a story.** That turns the backlog into a description of the past.
 
@@ -114,11 +137,14 @@ questions in `OPEN_QUESTIONS.md`), so the model can be reviewed before anyone co
 and checks, gaps, what was deliberately left alone, open hotspots, next slice.
 
 ```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
 ```
 
 The next session sees the progress in `AGENTS.md` and the map, and starts the next slice with
-`/adopt <path>`.
+`/adopt <scope>`.
 
 ## What lives where
 
@@ -134,6 +160,9 @@ The next session sees the progress in `AGENTS.md` and the map, and starts the ne
 | `docs/engineering/checks.yaml` | on check | what runs at edit time and at Stop/CI |
 | `docs/architecture/repo-map.md` | on demand | generated map: packages, edges, consumers, ranking |
 | `CONTEXT.md` | every session | the domain language |
+| `docs/domain/context-map.md` | on demand | **target** contexts and relationships |
+| `docs/domain/context-map.as-is.md` | on demand | **as-is** snapshot recovered by `/adopt`, with evidence |
+| `docs/domain/gap-register.md` | on demand | generated as-is ↔ target rows and the user's decisions |
 
 Nested `AGENTS.md` is loaded on demand by OpenCode; Claude Code loads the nested `CLAUDE.md` when it reads or
 edits a file there. That is why every package gets both files.

package/guide/concepts.md

@@ -14,6 +14,14 @@ Two rules make it work:
   user something you could find yourself.
 - **Do not act until the frontier is empty** and the user confirms a shared understanding.
 
+When a frontier question rests on an **external fact** – a standard, a library capability, a regulatory requirement,
+a security or privacy rule – the agent researches it before the round. The `researcher` is read-only and returns
+findings with source, tier, retrieval date and confidence; the main session writes them to
+`docs/research/<topic>.md` with an expiry. The finding is evidence, not a decision: the recommendation cites it
+(`➡️ … (RFC 9700 §2.1.1; F1 in docs/research/oauth-pkce.md)`), and only a confirmed finding becomes a testable
+criterion. A trigger is not a mandate – if the model, an ADR or a valid research file already answers it, nothing
+runs.
+
 `/grill-me` is the pure form. `/grill-with-docs` adds the glossary and ADRs. Every discovery command embeds it.
 
 ## The artifacts
@@ -22,13 +30,16 @@ Two rules make it work:
 |---|---|---|
 | `CONTEXT.md` | Glossary – the ubiquitous language. One canonical word per concept, alternatives under `_Avoid_` | user, maintained by the agent |
 | `docs/domain/events.yaml` | Event storming model: actors, contexts, aggregates, events, commands, policies, read models, hotspots, flows | user, written by the agent |
-| `docs/domain/context-map.md` | Bounded contexts and their relationships (DDD patterns) | domain-architect |
+| `docs/domain/context-map.md` | **Target** bounded contexts and their relationships (DDD patterns) | domain-architect, `/bootstrap`, `/shape`, `/feature`, `/improve-codebase-architecture` |
+| `docs/domain/context-map.as-is.md` | **As-is** snapshot recovered from code, with evidence | `/adopt` only |
+| `docs/domain/gap-register.md` | Generated rows for every `as-is`/`unresolved` aggregate, linking as-is and target; decisions outside the block | `/adopt`, user |
 | `docs/architecture/data-model.md` | Logical, stack-neutral model per aggregate; lifecycle and ER diagrams | domain-architect |
 | `docs/engineering/conventions.md` | How code is built here, including the seam catalog | user |
 | `docs/adr/` | Architecture decisions. `proposed` until the user accepts; accepted ones are superseded, never edited | user |
-| `docs/stories/` | The backlog. One Markdown file per story; `BACKLOG.md` is generated. With a tracker, this is the local mirror | requirements-engineer, PO, lead-dev; `/backlog-sync` with a tracker |
+| `docs/stories/` | The backlog. One Markdown file per story; `BACKLOG.md` is generated. With a tracker, this is the local mirror | main session as spec engineer; spec linter; `/backlog-sync` with a tracker |
 | `docs/product/vision.md` | Problem, user groups, goals, non-goals, success criteria | user |
 | `docs/product/ux-guidelines.md` | The interface yardstick, as numbered rules with date and reason | ux-designer, approved by user |
+| `docs/research/<topic>.md` | Evidence for a cross-cutting question: findings with source, tier, confidence and an expiry. Evidence, not a specification | researcher (read-only); main session writes; user confirms findings |
 | `docs/prototypes/<slug>/` | Throwaway prototypes on their own branch; only the README stays on the default branch | ux-designer; verdict in the story and the guidelines |
 
 ## Events, commands, aggregates
@@ -46,15 +57,21 @@ The code carries the same IDs, which is what makes traceability checkable.
 
 ## Stories
 
-A story is a vertical slice of observable behaviour: `draft → review → ready → in-progress → done` (plus
-`superseded`).
+A story is a vertical slice of observable behaviour: `draft → review → ready-for-human-review → ready →
+in-progress → done` (plus `superseded`).
 
+- **The linter is the gate.** `lint-story.ts` checks the spec deterministically. Green → `ready-for-human-review`;
+  the user approves `ready`.
 - **Discovery ends at `ready`.** Engineering moves `ready → in-progress → done`.
+- **1-command rule.** One domain story = one command + its events on one aggregate, at most 4 scenarios. A second
+  command is a second story.
+- **Fast lane.** `type: chore`/`task` for UI tweaks, refactors, dependencies and setup – no Gherkin matching, no
+  formal reviews.
 - **A story that turns out wrong goes back to `review`** with an `[OPEN]` and a row in `OPEN_QUESTIONS.md` – never
   guessed into shape during implementation.
 - **`done` is final.** A change to finished behaviour is a new story.
-- **At most 10 scenarios.** Each is one red → green cycle. More means split.
-- **A scenario title becomes a test title**: `ST-NNN: <scenario title>`. `verify.ts` checks the link.
+- **A scenario title becomes a test title**: `ST-NNN: <scenario title>`. `verify.ts` checks the link for domain
+  stories.
 
 ### Stories from tickets
 

package/guide/greenfield.md

@@ -62,12 +62,13 @@ Two kinds of work, kept apart:
 - **The first vertical slice** – the smallest set of stories that delivers one real end-to-end path from the
   vision, each with Gherkin scenarios.
 
-At most 10 scenarios per story; no implementation plan inside a domain story; every story links its `events`.
+One story = one command on one aggregate, at most 4 scenarios; no implementation plan inside a domain story; every domain story links `aggregate`, `command` and its `events`.
 
 ## Phase 6 – Review
 
-`/review-stories` – one lead-dev pass over value, buildability and UX. The user approves every `ready`. With a tracker,
-pull before the review and push the approved stories afterwards (`/backlog-sync`).
+`/review-stories` – the spec linter checks frontmatter, aggregate/command/events, Gherkin and the scenario limit.
+Green → `ready-for-human-review`; you approve every `ready`. With a tracker, pull before the review and push the
+approved stories afterwards (`/backlog-sync`).
 
 ## Phase 7 – Build
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kataster",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "description": "Agent workflow for domain-driven discovery and delivery – drop it into a greenfield or brownfield repository and build the domain by grilling.",
   "keywords": [
     "agents",

package/src/cli.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { Installer, VERSION } from "./install.mjs";
@@ -12,6 +12,8 @@ const HELP = `Kataster ${VERSION} – agent workflow for domain-driven discovery
 Usage:
   kataster init [dir]      Install the workflow into a repository (default: .)
   kataster upgrade [dir]   Update the workflow, keep project content and local changes
+  kataster lint-story [ST-NNN|file]
+                           Deterministic spec linter for stories (no LLM); empty = all stories
   kataster doctor [dir]    Check the installation
   kataster --version
   kataster --help
@@ -99,8 +101,8 @@ Useful commands afterwards:
   /grill-me /grill-with-docs   sharpen a plan and write the docs as you go
   /event-storming              explore a process or the whole domain
   /feature <idea>              add a feature through grilling, storming, stories
-  /review-stories              one lead-dev pass before a story is ready
-  /implement [ST-NNN]          test-first implementation of one story
+  /review-stories              linter gate + human approval before a story is ready
+  /implement [ST-NNN]          test-first implementation of one story (--fast for chore/task)
   /backlog-sync                pull/push the backlog mirror (Jira or GitHub Issues)
   /retro                       retrospective on a session
 `);
@@ -219,6 +221,36 @@ async function upgrade(options) {
   console.log("\nUpgrade complete. Project content (CONTEXT.md, docs/domain, docs/stories, ADRs) was not touched.");
 }
 
+/** Nearest directory that has the story linter installed (the repository of the given file, or an ancestor). */
+function findInstallRoot(start) {
+  let dir = resolve(start);
+  if (dir.endsWith(".md")) dir = dirname(dir);
+  for (;;) {
+    if (existsSync(join(dir, ".claude", "skills", "user-stories", "scripts", "lint-story.ts"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * `kataster lint-story [ST-NNN|file]` – delegates to the installed spec linter. Deterministic: the same checks
+ * the hook, `/review-stories` and `verify.ts` run, without an LLM.
+ */
+function lintStory(options) {
+  const arg = options._[1];
+  const root = findInstallRoot(arg && arg.endsWith(".md") ? arg : (arg && /^ST-/i.test(arg) ? process.cwd() : (arg || process.cwd())));
+  if (!root) {
+    throw new Error("No Kataster installation found (missing .claude/skills/user-stories/scripts/lint-story.ts) – run `kataster init` first.");
+  }
+  const script = join(root, ".claude", "skills", "user-stories", "scripts", "lint-story.ts");
+  const args = [script];
+  if (arg) args.push(arg.endsWith(".md") ? resolve(arg) : arg);
+  if (options.json) args.push("--json");
+  const r = spawnSync(process.execPath, args, { cwd: root, stdio: "inherit" });
+  process.exitCode = r.status ?? 1;
+}
+
 function doctor(options) {
   const root = resolve(options._[1] ?? ".");
   const checks = [];
@@ -230,6 +262,11 @@ function doctor(options) {
   add("Install manifest", Boolean(manifest), manifest ? `version ${manifest.version}` : "missing – run init");
   const leftovers = existsSync(join(root, ".laguardia")) || existsSync(join(root, ".opencode", "plugins", "laguardia"));
   add("No leftovers from the old name", !leftovers, leftovers ? "run upgrade to migrate them" : "");
+  const retired = [
+    ".claude/agents/product-owner.md", ".claude/agents/requirements-engineer.md", ".claude/agents/lead-dev.md",
+    ".opencode/agents/product-owner.md", ".opencode/agents/requirements-engineer.md", ".opencode/agents/lead-dev.md",
+  ].filter((file) => existsSync(join(root, file)));
+  add("No retired role-play agents", retired.length === 0, retired.join(", ") || "clean");
   const profile = readJson(join(root, ".claude", "project.json"));
   add("Project profile", Boolean(profile?.name), profile?.name ?? "missing");
 
@@ -238,7 +275,7 @@ function doctor(options) {
   add("Backlog provider", ["local", "github", "jira"].includes(provider), provider);
   if (provider === "jira") {
     add("Backlog: Jira project", Boolean(backlog.jira?.project), backlog.jira?.project || "backlog.jira.project is missing");
-    const statuses = ["draft", "review", "ready", "in-progress", "done", "superseded"];
+    const statuses = ["draft", "review", "ready-for-human-review", "ready", "in-progress", "done", "superseded"];
     const missingStatuses = statuses.filter((status) => !backlog.jira?.statusMap?.[status]);
     add("Backlog: Jira status map", missingStatuses.length === 0, missingStatuses.join(", ") || "all statuses mapped");
     const priorities = ["must", "should", "could", "wont"];
@@ -296,6 +333,7 @@ export async function main(argv) {
   const command = options._[0];
   if (command === "init") return init(options);
   if (command === "upgrade") return upgrade(options);
+  if (command === "lint-story") return lintStory(options);
   if (command === "doctor") return doctor(options);
   throw new Error(`Unknown command '${command}'. Try --help.`);
 }

package/src/detect.mjs

@@ -224,6 +224,15 @@ export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, d
         },
       },
     },
+    // Research files expire. The gate asks for `sources:` on risky work before it reaches ready-for-human-review.
+    // Keep the defaults in sync with .claude/lib/config.ts (DEFAULT_RESEARCH_CONFIG).
+    research: {
+      expiryMonths: 12,
+      gate: {
+        risk: ["high"],
+        labels: ["security", "auth", "payment", "privacy"],
+      },
+    },
     setup: {
       envFile: "",
       envHint: "",

package/src/install.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -58,8 +58,8 @@ const HOOK_EVENTS = {
 const ALLOW = [
   "Bash(node .claude/skills/event-storming/scripts/validate-events.ts)",
   "Bash(node .claude/skills/event-storming/scripts/render-event-storming.ts)",
-  "Bash(node .claude/skills/user-stories/scripts/validate-stories.ts)",
-  "Bash(node .claude/skills/user-stories/scripts/render-backlog.ts)",
+  "Bash(node .claude/skills/user-stories/scripts/*)",
+  "Bash(node .claude/skills/research/scripts/*)",
   "Bash(node .claude/skills/adopt/scripts/*)",
   "Bash(node .claude/skills/backlog/scripts/*)",
   "Bash(node .claude/skills/implement/scripts/*)",
@@ -70,6 +70,21 @@ const ALLOW = [
   "Bash(git log *)",
 ];
 
+/**
+ * Files earlier versions shipped and 0.4 removed. `upgrade` deletes them from an existing installation – but only
+ * when the manifest tracks them and the local copy is unmodified, so a project that customised one keeps it.
+ * Add a path here whenever a workflow file is retired; never prune by "not in the payload", because files from
+ * optional extras and user-added agents are not the installer's to delete.
+ */
+const OBSOLETE = [
+  ".claude/agents/product-owner.md",
+  ".claude/agents/requirements-engineer.md",
+  ".claude/agents/lead-dev.md",
+  ".opencode/agents/product-owner.md",
+  ".opencode/agents/requirements-engineer.md",
+  ".opencode/agents/lead-dev.md",
+];
+
 export class Installer {
   constructor(root, { dryRun = false, force = false, log = () => {} } = {}) {
     this.root = resolve(root);
@@ -165,17 +180,52 @@ export class Installer {
   }
 
   copyWorkflowDirs() {
+    const present = new Set();
     for (const dir of WORKFLOW_DIRS) {
       const source = join(PKG, dir);
       if (!existsSync(source)) continue;
       for (const file of walk(source)) {
         const name = toPosix(relative(source, file));
         if (name.split("/").some((part) => SKIP.has(part))) continue;
-        const content = read(file);
+        const key = relPosix(this.root, join(this.root, dir, name));
+        present.add(key);
         // settings.json and opencode.jsonc are merged, not replaced
         if (file === join(source, "settings.json") || file === join(source, "opencode.jsonc")) continue;
-        this.put(join(this.root, dir, name), content);
+        this.put(join(this.root, dir, name), read(file));
+      }
+    }
+    this.pruneObsolete(present);
+  }
+
+  /**
+   * Removes the retired workflow files listed in OBSOLETE (e.g. the deleted corporate-roleplay agents).
+   *
+   * Only files recorded in the manifest are candidates, so project content and files from other tools are never
+   * touched. A file the user edited is kept and reported as a conflict – unless `--force` is given, which backs it
+   * up first. This is what makes a removed agent actually disappear from an existing installation on upgrade.
+   */
+  pruneObsolete(present) {
+    for (const key of OBSOLETE) {
+      if (present.has(key)) continue;
+      if (!(key in (this.manifest?.files ?? {}))) continue;
+
+      const path = join(this.root, key);
+      if (!existsSync(path)) {
+        delete this.files[key];
+        continue;
+      }
+
+      const known = this.manifest.files[key];
+      const local = sha(read(path));
+      if (local !== known && !this.force) {
+        this.conflicts.push(key);
+        this.record("conflict", path, "retired, but locally modified – kept");
+        continue;
       }
+      if (this.force) this.backup(path);
+      if (!this.dryRun) rmSync(path, { force: true });
+      delete this.files[key];
+      this.record("remove", path, "retired workflow file");
     }
   }
 
@@ -384,6 +434,9 @@ This repository runs the Kataster workflow. Discovery lives in \`.claude/skills/
   local mirror and the tracker is the source of truth – sync with \`/backlog-sync\`; \`BACKLOG.md\` stays generated.
 - **Map:** \`docs/workflow.md\` – sources of truth, commands, phases, rules. Read it when unsure where something
   belongs.
+- **Research:** cross-cutting questions go through the read-only \`researcher\` (\`/research\`,
+  \`/feature --research\`); findings live in \`docs/research/<topic>.md\` with an expiry and are cited from a story's
+  \`sources:\`. Evidence, not a specification.
 - **Repo map (brownfield):** \`docs/architecture/repo-map.md\` – packages, dependency edges, consumers, adopted
   slices. A package's \`AGENTS.md\` is loaded only when you work there; the root file stays free of domain.
 - **Start:** greenfield → \`/bootstrap\`; existing code → \`/adopt\` (in slices, not the whole monorepo).
@@ -391,9 +444,16 @@ This repository runs the Kataster workflow. Discovery lives in \`.claude/skills/
 - **Project checks:** \`docs/engineering/checks.yaml\` – what runs at edit time and Stop/CI; architecture boundaries
   in \`docs/architecture/boundaries.yaml\` with existing debt in the baseline (only new violations fail).
 - **Language:** domain terms exactly as in \`CONTEXT.md\`; UI words from its \`_UI (<lang>)_\` lines.
-- **Traceability:** every scenario has a test titled \`ST-NNN: <scenario title>\`; domain IDs come from
+- **1-command rule:** one story = one command + its events on one aggregate, at most 4 Gherkin scenarios. Full
+  domain stories are \`type: domain\`; UI tweaks, refactors, dependencies and setup use the fast lane
+  (\`type: chore\` or \`type: task\`).
+- **Spec gate:** \`node .claude/skills/user-stories/scripts/lint-story.ts <file>\` must be green. A story the linter
+  accepts becomes \`ready-for-human-review\`; only the user approves \`ready\`.
+- **Traceability:** every domain scenario has a test titled \`ST-NNN: <scenario title>\`; domain IDs come from
   \`docs/domain/events.yaml\`.
 - **ADRs:** new ones are \`proposed\`; only the user sets \`accepted\`. A \`done\` story is never reopened.
+- **Reviews:** \`/implement\` scales review to the diff. \`code-reviewer\` and \`acceptance-tester\` report findings and
+  never create stories; fast-lane stories skip the formal review pass.
 - **Gate:** \`node .claude/skills/implement/scripts/verify.ts\`.
 
 Keep this block short: it is loaded into every session. Put rules into the skill that owns them, not here.

package/templates/docs/domain/context-map.md

@@ -1,4 +1,8 @@
-# Context map – {{project}}
+# Target context map – {{project}}
+
+> Where the domain is going, not what the code does today. The as-is map is `context-map.as-is.md` and is
+> written only by `/adopt`; the gap register links both sides. `/bootstrap`, `/shape`, `/feature`,
+> `/event-storming`, `domain-architect` and `/improve-codebase-architecture` write this file.
 
 <!--
   One section per bounded context: purpose, core terms, owner role. Relationships as a Mermaid flowchart

package/templates/docs/domain/events.yaml

@@ -6,6 +6,9 @@
 #
 # Written by /bootstrap, /adopt, /event-storming and /feature. Validated and rendered to
 # docs/domain/event-storming.md after every write. An empty model is valid: it grows during discovery.
+#
+# Aggregates carry an optional status: target (default when missing), as-is (factual boundary, needs evidence),
+# or unresolved (boundary unclear, needs an open hotspot and grilling; no story on it can be ready).
 
 version: 1
 domain: {{project}}

package/templates/docs/research/README.md

@@ -0,0 +1,70 @@
+# Research
+
+Evidence for cross-cutting questions: authentication and identity, security, payment, privacy and data protection,
+accessibility, performance, or a new library or technology. The files here are **evidence, not a specification** –
+the user decides in grilling, and only a confirmed finding becomes a testable acceptance criterion.
+
+One file per topic: `docs/research/<topic>.md`, lowercase kebab-case, no date in the file name. Refresh in place;
+if the question changes materially, use a new topic.
+
+## Format
+
+```markdown
+---
+topic: oauth-pkce-spa
+question: "Which PKCE configuration is required for a public SPA client?"
+created: 2026-11-07
+retrieved: 2026-11-07
+expires: 2027-11-07
+stack: ["next@15.2.0", "node@22.18.0"]
+---
+
+# Research: …
+## Question
+## Findings
+### F1 – …
+- **Statement:** …
+- **Source:** <title> – <url> (<section>)
+- **Retrieved:** YYYY-MM-DD
+- **Tier:** 1 | 2 | 3
+- **Confidence:** high | medium | low
+- **Domain-model impact:** none | conflicts with `<term>` / `AGG-…` / ADR-… – what
+## Conflicts, caveats and gaps
+## Open questions for the grilling
+```
+
+Source tiers: **1** specs, standards and authorities (RFC, W3C/WAI, OWASP, NIST, ISO, GDPR/EDPB, PCI SSC, vendor
+security advisories); **2** official documentation or source of the exact version in the lockfile; **3** everything
+else – a hint, never the sole basis for a criterion.
+
+## Expiry
+
+`expires` is computed when the file is written or refreshed: `retrieved + research.expiryMonths` from
+`.claude/project.json` (default 12 months, month-end clamped). It is not recomputed on every read. A stale file is
+refreshed, not silently reused.
+
+Check a file, every referenced file, or the whole directory:
+
+```bash
+node .claude/skills/research/scripts/research-check.ts --topic <slug>
+node .claude/skills/research/scripts/research-check.ts --referenced
+node .claude/skills/research/scripts/research-check.ts --all
+```
+
+Statuses are `VALID`, `EXPIRED`, `MISSING` and `INVALID`; exit 1 means at least one file needs a refresh or repair.
+`verify.ts` runs the referenced check as an advisory step – an expired file warns, it never fails the gate.
+
+## How research enters the work
+
+- `/research <question>` runs the read-only `researcher`; the main session writes its findings verbatim into this
+  directory. `/feature --research` forces the step for a topic the trigger list does not catch.
+- The story lists the file under `sources:`. A story with `risk: high` or one of the configured gate labels in
+  `.claude/project.json` (default `security`, `auth`, `payment`, `privacy`) needs at least one resolvable source
+  before `ready-for-human-review`; the linter warns, `story-status.ts` blocks.
+- Adopted findings become testable criteria with an observable threshold. Rejected options are recorded with the
+  reason in the story, ADR or initiative – this file stays evidence, not a decision log.
+- A finding that contradicts `CONTEXT.md`, `events.yaml`, an accepted ADR or the UX guidelines is a grilling
+  question, never a silent rewrite of the model.
+
+The full workflow is `.claude/skills/research/SKILL.md`; the format template is
+`.claude/skills/research/templates/research.md`.

package/templates/docs/stories/README.md

@@ -4,9 +4,18 @@ One Markdown file per story: `ST-NNN-short-title.md`. `BACKLOG.md` is generated
 Rules, format and splitting: `.claude/skills/user-stories/SKILL.md`.
 Template: `.claude/skills/user-stories/templates/story-template.md`.
 
-Workflow: `draft → review → ready → in-progress → done` (plus `superseded`).
-
-- Discovery ends at `ready`; `/implement` moves a story to `in-progress` and `done`.
+Workflow: `draft → review → ready-for-human-review → ready → in-progress → done` (plus `superseded`).
+
+- The **spec linter** is the gate: `node .claude/skills/user-stories/scripts/lint-story.ts <file>` (or
+  `kataster lint-story`). It checks frontmatter, `aggregate`/`command`/events against `docs/domain/events.yaml`,
+  Gherkin `Given/When/Then` and the scenario limit – deterministically, no LLM.
+- Green → `ready-for-human-review`; **the user approves `ready`**. `/implement` only picks up `ready`.
+- **1-command rule:** one `type: domain` story = one command + its events on one aggregate, at most 4 scenarios.
+- An aggregate with `status: unresolved` blocks the story at `ready-for-human-review`; settle the boundary and
+  its hotspot in grilling first. A missing status means `target`; `as-is` is allowed.
+- **Fast lane:** `type: chore` or `type: task` for UI tweaks, refactorings, dependencies and setup – no Gherkin
+  matching, no formal reviews. `type: tech-task` keeps its checklist; `type: spike` is a timeboxed question.
+- `ui: true` marks a story with a frontend part; it triggers the on-demand UX utility, never a gate.
 - A story that turns out wrong goes back to `review` with an `[OPEN]` and a row in `OPEN_QUESTIONS.md`.
 - `done` is final: a change to finished behaviour is a new story.