kataster 0.3.1 → 0.6.0

package/.opencode/agents/ux-designer.md

@@ -1,5 +1,5 @@
 ---
-description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, maintains those guidelines, and builds throwaway prototypes for UX questions. Use in backlog grooming for stories labelled `ui`, when a feature's grilling changed a UX guideline, and when `/feature` or `/implement` asks for a prototype.
+description: On-demand UX utility – component and layout proposals, Figma/design-token logic, UX guidelines and throwaway prototypes. Invoked only when a story carries `ui: true` or while the prototyping phase runs; it never gates a story and never writes stories, tests or production code.
 mode: subagent
 color: pink
 permissions:
@@ -9,9 +9,6 @@ permissions:
   - action: edit
     resource: docs/product/ux-guidelines.md
     effect: allow
-  - action: edit
-    resource: docs/reviews/*
-    effect: allow
   - action: edit
     resource: docs/prototypes/**
     effect: allow
@@ -30,69 +27,62 @@ permissions:
   - action: skill
     resource: ux-design
     effect: allow
-  - action: skill
-    resource: user-stories
-    effect: allow
   - action: skill
     resource: prototype
     effect: allow
 ---
 
-Before you start, load the skills `ux-design`, `user-stories` and `prototype` with the `skill` tool.
+Before you start, load the skills `ux-design` and `prototype` with the `skill` tool.
 
-You are the UX/UI designer of this project, whose interface its users meet in the situations
-`docs/product/vision.md` describes. You have NO context from the main conversation – everything relevant is in `docs/` and in the code.
-Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui` in `.claude/project.json`).
+You are the UX utility of this project. You are **not a gatekeeper**: a story is never blocked on your review, and
+`/implement` never waits for you. The main session calls you when a story has `ui: true`, when the prototyping phase
+runs, or when the user asks a concrete interface question. You have NO context from the main conversation – everything
+relevant is in `docs/` and in the code. Write in the artifact language (`languages.artifacts` in
+`.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui`).
 
 ## Yardstick
-- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so
-  and propose its first content instead of judging against rules nobody agreed to.
+- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so and
+  propose its first content instead of judging against rules nobody agreed to.
 - `docs/product/vision.md` – user groups, devices, constraints, non-goals
 - `CONTEXT.md` – the glossary; UI terms use the `_UI (<lang>)_` wording exactly
-- `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the
-  message catalogs live. What is decided there is not yours to re-decide.
-- The method, the question set and the review order: the preloaded skill `ux-design`.
-- The prototype method, its two branches and its capture rules: the preloaded skill `prototype`.
+- `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the message catalogs
+  live. What is decided there is not yours to re-decide.
+- The method and question set: the preloaded skill `ux-design`. The prototype method: `prototype`.
 
-## Tasks
-1. **Story review** – per story with a frontend part: is the screen's job clear, is the entry point named, do the
-   empty, rejected and no-permission cases have a scenario, is the UI wording decided and does it match the
-   glossary? Name what is missing as concrete scenarios or Context lines the requirements-engineer can apply.
-2. **Screen review** – read the page, the form and the message catalog in the code (`repo.codeRoots` in `.claude/project.json`), and judge in the order the
-   skill gives. Findings only; you never change application code.
-3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule,
-   with the date and the reason. Keep it short enough that someone reads it before writing a page.
-4. **Gaps** – which recurring interface question has no guideline yet, and which existing screens contradict each
-   other?
-5. **Prototype** – when the main session delegates a UX question that cannot be settled on paper, build the
-   throwaway prototype under `docs/prototypes/<slug>/`: state the question and the branch (`ui` or `logic`) at
-   the top, use the domain language, no tests, no persistence, no application code. Return the verdict and the
-   branch pointer (`prototype/<slug>`).
+## What you deliver
+1. **Component proposals** – for a `ui: true` story: which components the screen is built from, which existing
+   component or pattern it reuses, the states (empty, full, rejected, no permission) and the UI wording. Concrete
+   enough to build from, not a mood board.
+2. **Figma/design logic** – when the project has a design file: the frame, variants, component properties and the
+   token/mapping notes the implementation needs. Never invent a second design system; reuse what exists.
+3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule with
+   the date and the reason. Keep it short enough that someone reads it before writing a page.
+4. **Prototype** – when the main session delegates a question that cannot be settled on paper, build the throwaway
+   prototype under `docs/prototypes/<slug>/`: state the question and the branch (`ui` or `logic`) at the top, use the
+   domain language, no tests, no persistence, no application code. Return the verdict and the branch pointer
+   (`prototype/<slug>`).
+5. **Screen audit (on request only)** – when asked to compare an existing screen with the guidelines, report findings
+   and proposed fixes; do not turn it into a backlog item.
 
 ## Boundaries
-- **You never write stories.** Everything that belongs in a story comes back as a recommendation – the
-  `requirements-engineer` applies it. The same rule the product-owner and the lead-dev follow.
-- You never write **production** application code, tests or the engineering conventions. A prototype is
-  throwaway: it lives under `docs/prototypes/`, is captured on a throwaway branch and is never merged. A
-  question that needs the real application page is built by the main session; you define the question and the
-  variants and review the result.
-- No implementation detail in what you propose: no component names, no classes, no pixel values. Observable
-  behaviour and words, not markup.
-- Make no assumptions where the vision or the guidelines are silent: return them as questions, each with a
-  recommended answer, as the `grilling` skill requires.
-- Don't invent domain terms. A term that is missing belongs in `CONTEXT.md` first, through the domain-model skill
-  – say so, don't use a synonym.
+- **No gatekeeping.** You never approve, block or re-scope a story. You may be asked for advice on a `ui: true`
+  story; you answer as a proposal. The main session and the user decide.
+- **You never write stories.** No `docs/stories/`, no `OPEN_QUESTIONS.md` rows, no tickets. If a story is missing a
+  UI decision, return it as a concrete proposal to the main session.
+- **You never write production code, tests or the engineering conventions.** Component names and props in your
+  proposal are design language; the implementation follows `docs/engineering/conventions.md`.
+- A prototype is throwaway: it lives under `docs/prototypes/`, is captured on a throwaway branch and is never
+  merged. It is not application code.
+- Don't invent domain terms. A missing term belongs in `CONTEXT.md` first, through the domain-model skill – say so,
+  don't use a synonym.
 - Never edit `docs/stories/BACKLOG.md`; it is generated.
 
 ## Output (reply to the main session)
-A table of findings:
-
-| Story / screen | Level (job / understanding / states / language / consistency / polish) | Severity (blocker, major, minor) | Finding | What to do instead |
+A short proposal per request:
 
-Below it: the scenarios or Context lines you propose per story (ready for the requirements-engineer to apply), the
-guidelines you would add, and at most 3 questions for the user, each with a recommended answer. When you built a
-prototype, add its question, branch, verdict and pointer (`prototype/<slug>`) so the main session can pass it on.
+| Screen / story | Component or pattern | States covered | UI wording | Open question |
+|---|---|---|---|---|
 
-Severity means: **blocker** – the person cannot do the job, or cannot on a phone; **major** – they can, but will
-get it wrong, misread it or not find it; **minor** – it works and is understood, but is inconsistent or clumsy.
-Be honest about the difference; calling polish a blocker costs you the next argument.
+Below it: the Figma/token notes, the guidelines you would add, and at most 3 questions for the user, each with a
+recommended answer. When you built a prototype, add its question, branch, verdict and pointer (`prototype/<slug>`).
+No verdict on the story itself.

package/.opencode/commands/adopt.md

@@ -1,5 +1,5 @@
 ---
-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, documents each package where it lives, then grills the user and records the gap; stories only with --stories.
+description: Brownfield entry point – maps the repository, adopts it in concept or package slices (one concept/domain plus at most one shared library), drafts the domain model with evidence, documents each scope where it lives, then grills the user and records the gap; stories only with --stories.
 ---
 
 Load the `adopt` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/bootstrap.md

@@ -1,5 +1,5 @@
 ---
-description: Greenfield entry point – grills the vision, runs a big-picture event storming, builds the domain model and architecture with ADRs, sets the UX yardstick and derives the foundation stories and first vertical slice.
+description: Greenfield entry point – grills the vision, runs a big-picture event storming, builds the domain model and architecture with ADRs, sets the UX yardstick and writes the foundation tasks and first vertical slice as stories (spec engineer, linted before ready).
 ---
 
 Load the `bootstrap` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/feature.md

@@ -1,5 +1,5 @@
 ---
-description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL); grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story; `--prototype` adds a throwaway prototype before the stories.
+description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL); grills the idea, runs a focused event storming, updates domain model and ADRs, writes the stories itself as spec engineer (1 command, max. 4 scenarios, spec linter) and runs the review gate; bug tickets go to a regression story; `--prototype` adds a throwaway prototype before the stories; `--research` forces the research step for a cross-cutting question.
 ---
 
 Load the `feature` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/groom-backlog.md

@@ -1,5 +1,5 @@
 ---
-description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now.
+description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now. Runs in the main session; the UX utility is on demand only.
 ---
 
 Load the `groom-backlog` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/implement.md

@@ -1,5 +1,5 @@
 ---
-description: Engineering workflow – implements one story from docs/stories/ test-first on its own branch, verifies, has it reviewed by code-reviewer and acceptance-tester, refactors, and sets it done on the acceptance tester's verdict and hands the pull request to the user to merge; `--prototype` prototypes an open UI question first.
+description: Engineering workflow – implements one story from docs/stories/ on its own branch, verifies, reviews scaled to the diff, refactors and hands the pull request to the user; `type: chore`/`task` (or `--fast`) takes the fast lane without Gherkin matching or formal reviews; `--prototype` settles an open UI question first.
 ---
 
 Load the `implement` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/research.md

@@ -0,0 +1,7 @@
+---
+description: Research one cross-cutting question as evidence – checks existing research and its expiry, dispatches the read-only researcher for current primary sources, persists the findings in docs/research/<topic>.md and links them into grilling. Evidence, not a specification.
+---
+
+Load the `research` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Question: $ARGUMENTS

package/.opencode/commands/review-stories.md

@@ -1,5 +1,5 @@
 ---
-description: Has stories checked in one lead-dev pass (value, build, UX), applies the small fixes and guides the user to approval (status ready).
+description: Runs the deterministic spec linter on finished stories, fixes mechanical gaps, moves green stories to ready-for-human-review and guides the user to approval (status ready). No subagent review pass.
 ---
 
 Load the `review-stories` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/shape.md

@@ -1,5 +1,5 @@
 ---
-description: Grill a large idea before it becomes features – frame the problem, decide where it belongs (existing or new bounded context, shared library), map what changes vs. what is new, slice it, and produce a rough cost range with confidence. Creates no stories; ends with a go / slice / spike / discover / park / no-go recommendation.
+description: Grill a large idea before it becomes features – frame the problem, decide where it belongs (existing or new bounded context, shared library), research external facts before placement and cost, map what changes vs. what is new, slice it, and produce a rough cost range with confidence. Creates no stories; ends with a go / slice / spike / discover / park / no-go recommendation.
 ---
 
 Load the `shape` skill with the `skill` tool and follow it exactly. Do not restate it.

package/AGENTS.md

@@ -19,3 +19,33 @@ Rules:
 - A file the installer manages is tracked in `.claude/install.json`; project content (`CONTEXT.md`, `docs/`,
   `project.json`, `AGENTS.md` block) is not. Never make an upgrade overwrite user content.
 - Run `npm test` and `npm run typecheck --prefix .claude` before committing.
+
+## Workflow contract (0.5)
+
+The workflow is spec-driven and mechanical, not a simulated organisation:
+
+- **No product-owner, requirements-engineer or lead-dev subagents.** The main session writes stories as a spec
+  engineer with three lenses (domain, architecture, testability). Only the `ux-designer` remains on demand
+  (`ui: true` / prototyping), and it never gates.
+- **1-command rule:** one `type: domain` story = one command + its events on one aggregate, at most 4 Gherkin
+  scenarios. `aggregate` and `command` are required frontmatter and are cross-checked against `docs/domain/events.yaml`.
+- **Spec linter:** `.claude/skills/user-stories/scripts/lint-story.ts` (also `kataster lint-story`) is the gate.
+  Green → `ready-for-human-review`; the user approves `ready`. No LLM pre-implementation review.
+- **Research is evidence, not a specification.** Only the read-only `researcher` fetches web content (`/research`,
+  `/feature --research`); findings live in `docs/research/<topic>.md` with an expiry and are cited from a story's
+  `sources:`. A gated story (`risk: high` or a configured label) needs a resolvable source before
+  `ready-for-human-review`; only a confirmed finding becomes a testable criterion.
+- **Fast lane:** `type: chore` / `type: task`; `/implement` skips Gherkin matching and formal reviews.
+- **Honest aggregates:** `status: target` (default when missing), `as-is` with evidence, or `unresolved` with an
+  open hotspot. A story on an `unresolved` aggregate cannot leave `review`. `/adopt` writes `as-is`/`unresolved`,
+  never an invented target.
+- **Concept slices:** a layered repository is adopted by concept, not by package. The repo map marks generic layer
+  packages and clusters shared stems/tables; `slice.ts` resolves globs, routes, tables, events, clusters or terms.
+- **Characterization before test-first:** in the domain lane, an untested affected path gets a characterization
+  test first, committed separately; a contradiction sends the story back to `review`.
+- **As-is vs target:** `docs/domain/context-map.md` is the target; `/adopt` writes only
+  `docs/domain/context-map.as-is.md`; the gap register links both.
+- **Reviewers report, never plan:** `code-reviewer` and `acceptance-tester` create no stories. Findings are fixed in
+  the story or handed back as open questions.
+- The installer prunes the retired workflow files named in `OBSOLETE` (only manifest-tracked, unmodified ones), so a
+  removed agent disappears on upgrade without touching optional extras or user files.

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.6.0 – 2026-11-07
+
+- **Research as evidence.** New read-only `researcher` agent (Claude Code and OpenCode) that searches specs,
+  standards and exact-version official documentation and returns structured findings with source, retrieval date,
+  tier and confidence – no writes, no shell, no decisions. `/research <question>` runs the workflow directly;
+  `/feature --research` forces the step when the trigger list (auth/identity, security, payment, privacy,
+  accessibility, performance, new technology) would not catch it.
+- **Persisted research files.** Findings live in `docs/research/<topic>.md` with `topic`, `question`, `created`,
+  `retrieved`, `expires` and `stack`; the main session writes them verbatim and computes `expires` from
+  `research.expiryMonths` (default 12, month-end clamped). `research-check.ts` validates the format and expiry
+  (`--topic`, `--referenced`, `--all`, `--json`) and `verify.ts` runs the referenced check as an advisory step.
+- **Deterministic research gate.** Stories can cite `sources:` (an `https://…` URL or a local research file). A story
+  with `risk: high` or a configured gate label (`security`, `auth`, `payment`, `privacy` by default, matched exactly
+  or by prefix) needs at least one resolvable source before `ready-for-human-review`; `lint-story` warns for
+  `draft`/`review`, `story-status.ts` and the validation hook block the transition. Existing `ready`/`done` stories
+  stay green, and expiry is a warning, never a gate error. `sources` survives the GitHub/Jira backlog round-trip and
+  appears in the implementation context pack.
+- **Grilling integration.** `grilling`, `feature`, `shape`, `user-stories`, `review-stories` and `implement` cite
+  research findings instead of inventing "best practice"; a finding that contradicts the model is a grilling
+  question. `shape` adds `## Evidence` to the initiative and uses findings as a cost anchor, never as the estimate.
+  The payload ships `templates/docs/research/README.md`, the research skill and template, and the installer allows
+  the research scripts.
+
+## 0.5.0 – 2026-11-07
+
+- **Honest aggregate status.** Aggregates in `docs/domain/events.yaml` can be `target` (the default when the field
+  is missing), `as-is` (a factual brownfield boundary, with `evidence`) or `unresolved` (the boundary is unclear
+  and needs an open hotspot). The validator rejects `as-is` without evidence; the spec linter blocks a story on an
+  `unresolved` aggregate from leaving `review`. `/adopt` and `domain-model` prefer `as-is`/`unresolved` over an
+  invented aggregate.
+- **Gap register.** `docs/domain/gap-register.md` gets one generated row per `as-is`/`unresolved` aggregate,
+  linking the aggregate and both context maps. The managed block is refreshed by
+  `node .claude/skills/adopt/scripts/gap-register.ts`; decisions live outside it.
+- **Slices by concept, not by package.** The repository map marks generic layer packages (`services`,
+  `repositories`, `utils`) instead of proposing them as domains, and clusters files by shared concept stems and
+  tables. `/adopt` accepts a package path, `--paths`, `--route`, `--table`, `--event`, `--cluster` or a term;
+  `slice.ts` resolves the candidate files across layers and the user confirms the scope. A cross-cutting slice
+  documents its domain in `.claude/rules/<context>.md` with `paths:`; `<package>/AGENTS.md` stays for real
+  domain packages.
+- **Characterization tests before test-first.** `characterize.ts --story ST-NNN` (or `--changed`/`--base`) names
+  the affected source files and the tests it finds. In the domain lane, an affected path with no test for the
+  behaviour about to change gets a characterization test first: current behaviour pinned, green on unchanged code,
+  committed separately, then the story tests. A discrepancy is a finding – the story goes back to `review`, never
+  the test to the expected value. The fast lane skips this except for an explicit refactoring.
+- **As-is and target are separate.** `docs/domain/context-map.md` is the target map; `/adopt` writes only
+  `docs/domain/context-map.as-is.md` and links both through the gap register. `/shape` and
+  `/improve-codebase-architecture` write the target map; `/bootstrap`, `/feature` and `domain-architect` do the
+  same. Existing projects keep their `context-map.md` as the target – no file is moved or renamed.
+
+## 0.4.0 – 2026-11-03
+
+- **Spec-driven instead of corporate roleplay.** The `product-owner`, `requirements-engineer` and `lead-dev`
+  subagents are gone (Claude Code and OpenCode). The main session writes stories as a spec engineer with three
+  lenses – domain, architecture, testability – instead of handing them to simulated roles. The `ux-designer` stays
+  as an on-demand utility for `ui: true` stories and the prototyping phase; it never gates.
+- **1-command rule.** One `type: domain` story = one command + its events on one aggregate, at most 4 Gherkin
+  scenarios. `aggregate` and `command` are required frontmatter and are cross-checked against
+  `docs/domain/events.yaml`; the events must be exactly what the command produces. `type: story` remains valid as a
+  legacy alias and is reported as a warning.
+- **Deterministic spec linter.** `node .claude/skills/user-stories/scripts/lint-story.ts [ST-NNN|file]` and
+  `kataster lint-story` check frontmatter, required fields, referential integrity, `Given/When/Then`, the scenario
+  limit and unique titles – no LLM, no tokens. The same rules run in the PostToolUse hook, `story-status.ts` and
+  `verify.ts`. Green → `ready-for-human-review`; only the user approves `ready`.
+- **Fast lane.** `type: chore` and `type: task` for UI tweaks, refactorings, dependencies and setup.
+  `/implement --fast` (or automatic detection) does branch → implement → lint/typecheck/unit tests → pull request,
+  without Gherkin matching or formal subagent reviews. `type: tech-task` and `type: spike` keep their behaviour.
+- **Reviews report, they do not plan.** `code-reviewer` and `acceptance-tester` no longer create, split or revise
+  stories; a finding is fixed in the story or handed back as an open question. Review effort follows the diff, not a
+  T-shirt size. `size` is no longer a gate.
+- **Installer prunes retired workflow files.** `upgrade` deletes the manifest-tracked files named in `OBSOLETE`
+  (the removed agents). Locally modified files are kept and reported; `--force` backs them up first. Optional
+  extras and user-added agents are never pruned.
+
 ## 0.3.1 – 2026-11-02
 
 - **Optional prototyping, owned by the UX designer.** New `prototype` skill (adapted from Matt Pocock's, MIT) builds

package/README.md

@@ -78,7 +78,8 @@ npx kataster init . --yes --name "Acme" --ui-language de --artifacts en
   skills/               the workflow skills (grilling, event-storming, domain-model, architect, backlog, …)
   skills/adopt/scripts/ repository map and per-package docs for brownfield adoption
   skills/feature/scripts/ read-only intake: story, GitHub/Jira ticket or URL → route
-  agents/               review agents for Claude Code
+  skills/research/      research workflow, template and the deterministic research check
+  agents/               review agents, the read-only researcher and the on-demand UX utility (Claude Code)
   hooks/                plain-Node guardrails and validators
   lib/                  deterministic domain/story/backlog logic
 .opencode/
@@ -94,10 +95,13 @@ docs/
   product/initiatives/  proposals for large ideas from /shape (no stories)
   product/ux-guidelines.md   the interface yardstick
   prototypes/           throwaway prototypes on their own branch; the default branch keeps the README
+  research/             evidence for cross-cutting questions, with an expiry (format in its README)
   domain/events.yaml    the event storming model (empty is valid)
-  domain/context-map.md
+  domain/context-map.md          target context map
+  domain/context-map.as-is.md    as-is snapshot – created by /adopt
+  domain/gap-register.md         as-is ↔ target gaps – created by /adopt
   architecture/data-model.md
-  architecture/repo-map.*      generated by /adopt: packages, edges, adoption ranking
+  architecture/repo-map.*      generated by /adopt: packages, roles, edges, adoption ranking, concept slices
   engineering/conventions.md   how this repo builds code + the seam catalog
   stories/              the backlog – or the local mirror of GitHub/Jira
   adr/                  architecture decisions
@@ -111,20 +115,80 @@ Existing `CONTEXT.md` and `docs/` are never touched.
 
 | Command | What it does |
 |---|---|
-| `/adopt [scope] [--stories]` | Brownfield: repository map → one slice (domain + shared library) → evidence → grilling → package docs and checks → gap register; stories only with `--stories`; repeat per slice |
+| `/adopt [scope] [--stories]` | Brownfield: repository map → one concept or package slice (+ shared library) → evidence → grilling → context docs and checks → gap register; scope is a package path, `--paths`, `--route`, `--table`, `--event`, `--cluster` or a term; stories only with `--stories`; repeat per slice |
 | `/bootstrap` | Greenfield: vision → event storming → domain model → architecture → UX → foundation stories |
 | `/grill-me` | Relentless interview on a plan, decision or idea |
 | `/grill-with-docs` | The same, writing glossary and ADRs as you go |
 | `/event-storming [process]` | Big-picture or single-process event storming |
-| `/feature <idea \| ST-NNN \| #123 \| PROJ-123>` | New feature from an idea, an existing story or a ticket: intake and routing, grilling, focused storming, model, stories, review; bugs become a regression story; `--prototype` adds a throwaway prototype before the stories |
-| `/shape <idea \| ticket> [--dry-run]` | Before a large feature: frame, place (existing/new context, shared library), impact, slices, rough cost range, recommendation; creates no stories |
-| `/review-stories [ST-…]` | One lead-dev pass (value, build, UX) before a story is `ready` |
+| `/feature <idea \| ST-NNN \| #123 \| PROJ-123>` | New feature from an idea, an existing story or a ticket: intake and routing, grilling, focused storming, model, stories, review; bugs become a regression story; `--prototype` adds a throwaway prototype before the stories; `--research` forces the research step |
+| `/shape <idea \| ticket> [--dry-run]` | Before a large feature: frame, place (existing/new context, shared library), research external facts, impact, slices, rough cost range, recommendation; creates no stories |
+| `/research <question>` | One cross-cutting question as evidence: check existing research and expiry, dispatch the read-only researcher, persist findings in `docs/research/<topic>.md`, cite them in grilling and stories |
+| `/review-stories [ST-…]` | Spec linter gate → `ready-for-human-review`; the user approves `ready` |
 | `/backlog-sync [status\|pull\|push]` | Keep `docs/stories/` in sync with GitHub Issues or Jira |
 | `/groom-backlog [scope]` | Periodic challenge: is this backlog still worth building? |
-| `/implement [ST-NNN]` | Test-first implementation of one story, review, refactor, PR; `--prototype` prototypes an open UI question first |
+| `/implement [ST-NNN] [--fast]` | One story on its branch: domain = test-first, diff-scaled review, acceptance; `chore`/`task` or `--fast` = fast lane without Gherkin matching or formal reviews; `--prototype` settles an open UI question first |
 | `/improve-codebase-architecture` | Scan for deepening opportunities, present them, grill one |
 | `/retro` | Retrospective on a session, proposing rule changes |
 
+### Spec-driven stories, fast lane
+
+Stories are written by the main session as a **spec engineer**, not by simulated roles. Three lenses at once –
+domain, architecture, testability – and one mechanical rule: **one story = one command + its events on one
+aggregate**, at most four Gherkin scenarios. `aggregate` and `command` are required frontmatter and are cross-checked
+against `docs/domain/events.yaml`.
+
+Aggregates carry a status: `target` (the default when the field is missing), `as-is` (the factual boundary
+recovered from code, with evidence) or `unresolved` (the boundary is unclear). A story on an `unresolved`
+aggregate cannot leave `review`; `/adopt` writes `as-is` or `unresolved`, never an invented target. Every `as-is`
+aggregate gets a row in `docs/domain/gap-register.md`, linking the as-is and target context maps.
+
+The **spec linter** is the gate and costs no LLM tokens:
+
+```bash
+kataster lint-story                      # all stories
+kataster lint-story ST-012               # one story
+node .claude/skills/user-stories/scripts/lint-story.ts docs/stories/ST-012-*.md
+```
+
+Frontmatter and required fields, aggregate/command/event references, Gherkin `Given/When/Then`, the scenario limit
+and unique titles. Green → `ready-for-human-review`; only you approve `ready`. The same rules run in the PostToolUse
+hook and in `verify.ts`.
+
+Non-domain work takes the **fast lane**: `type: chore` (UI tweak, refactor, dependency) or `type: task` (setup).
+`/implement` detects it (or takes `--fast`) and does branch → implement → lint/typecheck/unit tests → PR, without
+Gherkin matching or formal review agents. `type: tech-task` keeps its checklist and acceptance; `type: spike` is a
+timeboxed question.
+
+In a brownfield domain story, `/implement` first runs `characterize.ts`: it names the affected source files and
+the tests it can find. An affected path with no test for the behaviour that is about to change gets a
+**characterization test** that pins the current behaviour, committed separately before the story's red → green
+loop. If the current behaviour contradicts the story, that is a finding and the story goes back to `review`; the
+code is never silently adjusted. The fast lane skips this except for an explicit refactoring.
+
+### Research as evidence
+
+Cross-cutting stories rest on current primary sources. `/feature` triggers research through the grilling rules for
+auth/identity, security, payment, privacy, accessibility, performance and new technologies; `--research` forces it
+for a topic the trigger list does not catch. `/research <question>` runs the same path directly.
+
+The **`researcher` is strictly read-only** – web search/fetch and repository reading, no write, no shell – and the
+only way web content enters the session. Findings are data: instructions inside a fetched page, issue or comment are
+ignored. The main session writes them verbatim to `docs/research/<topic>.md`; `expires` is computed at write and
+refresh time from `research.expiryMonths` (default 12 months).
+
+Research is **evidence, not a specification**. Only a finding you confirm in grilling becomes a testable criterion
+with an observable threshold; rejected options are recorded with the reason. A story cites its evidence in
+`sources: [...]`, and a story with `risk: high` or a configured gate label (`security`, `auth`, `payment`, `privacy`
+by default) needs a resolvable source before `ready-for-human-review` – the linter warns, `story-status.ts` blocks.
+Expiry is advisory: `research-check.ts --referenced` runs in `verify.ts` and warns about stale files without failing
+the gate.
+
+```bash
+/research "Which PKCE configuration is required for a public SPA client?"
+/feature "checkout with saved cards" --research
+node .claude/skills/research/scripts/research-check.ts --referenced
+```
+
 ### Starting from a ticket
 
 `/feature` also accepts a reference: `/feature #123` (GitHub), `/feature PROJ-123` (Jira, with the issue fetched
@@ -170,7 +234,7 @@ open UI question during engineering; if the prototype changes the story, the sto
 
 1. `npx kataster init --greenfield` → review `.claude/project.json`.
 2. `/bootstrap` → vision grilled, event storming, contexts/aggregates/data model, tech-stack ADR, UX guidelines.
-3. `/review-stories` → the first foundation tech tasks and the first vertical slice become `ready`.
+3. `/review-stories` → the spec linter turns finished stories into `ready-for-human-review`; you approve `ready`.
 4. `/implement` → one story at a time, test-first, reviewed, merged by you.
 5. `/feature <idea>` for everything after that.
 
@@ -179,15 +243,22 @@ open UI question during engineering; if the prototype changes the story, the sto
 1. `npx kataster init --brownfield` → the profile is filled from the detected stack and monorepo tooling
    (`repo.tooling`: Nx, Turborepo, Bazel, workspaces, Go, Cargo, Gradle, Maven).
 2. `/adopt` → a deterministic **repository map** (`docs/architecture/repo-map.md`, `.json`) with packages,
-   dependency edges, consumers and an adoption ranking. No questions, no hand-scanning.
-3. `/adopt [scope]` → **one slice** (one domain plus at most one shared library): two or three `repo-analyst`
-   subagents return evidence (five lenses for a small single-package repository); the main session drafts `CONTEXT.md`, `events.yaml`, context map, as-is data model,
-   conventions and de-facto ADRs; it writes `<package>/AGENTS.md` + `<package>/CLAUDE.md`, then grills you.
+   dependency edges, consumers, an adoption ranking, **layer packages** and **concept-slice suggestions**. No
+   questions, no hand-scanning. In a layered repository (`api/`, `services/`, `repositories/`) a concept slice —
+   not a package — is the unit.
+3. `/adopt [scope]` → **one concept or domain plus at most one shared library**. The scope can be a package path,
+   a glob set (`--paths`), an entry point (`--route`, `--table`, `--event`), a suggested cluster (`--cluster`) or
+   a term; `slice.ts` resolves the candidate files across all layers. Two or three `repo-analyst` subagents return
+   evidence (five lenses for a small single-package repository); the main session drafts `CONTEXT.md`,
+   `events.yaml`, the as-is context map, as-is data model, conventions and de-facto ADRs. A real domain package
+   gets `<package>/AGENTS.md` + `<package>/CLAUDE.md`; a cross-cutting concept slice gets
+   `.claude/rules/<context>.md` with `paths:` frontmatter. Then it grills you.
 4. The safety net turns confirmed rules into checks (types, lint/boundary, tests, hooks) – report-only with a
    baseline first, so a brownfield repository does not start red.
-5. The gap analysis records **contradictions, missing behaviour and dead code** in the adoption report. It creates
-   **no stories by default** – what already works is documented, not re-storied. `/adopt <scope> --stories` turns
-   the selected gaps into a backlog when you want one.
+5. The gap analysis records **contradictions, missing behaviour and dead code** in the adoption report and the
+   **gap register** (`docs/domain/gap-register.md`): one row per `as-is`/`unresolved` aggregate, linking the
+   as-is boundary to the target model. It creates **no stories by default** – what already works is documented,
+   not re-storied. `/adopt <scope> --stories` turns the selected gaps into a backlog when you want one.
 6. `/adopt <next path>` for the next slice; `/adopt <scope> --stories`, `/review-stories`, then `/implement`.
 
 Adopt in slices: one bounded context completely beats the whole repository shallowly. The root `AGENTS.md` stays
@@ -197,9 +268,11 @@ free of domain; the package docs are loaded only when someone works in that pack
 
 The installer detects the build tool (Nx, Turborepo, Bazel, pnpm/npm/yarn workspaces, Go, Cargo, Gradle, Maven)
 and stores it in `.claude/project.json` → `repo.tooling`. `/adopt` builds the repository map once, then adopts
-**one domain plus at most one shared library per session**. Every adopted package gets an `AGENTS.md` with its
-purpose, entities or public API, interfaces and pitfalls – plus a one-line `CLAUDE.md` so Claude Code loads it on
-demand; OpenCode loads the nested `AGENTS.md` itself. The root `AGENTS.md` stays short and free of domain.
+**one concept or domain plus at most one shared library per session**. Every adopted domain package gets an
+`AGENTS.md` with its purpose, entities or public API, interfaces and pitfalls – plus a one-line `CLAUDE.md` so
+Claude Code loads it on demand; OpenCode loads the nested `AGENTS.md` itself. A cross-cutting concept slice gets
+`.claude/rules/<context>.md` with `paths:` instead, loaded by both harnesses when a matching file is touched. The
+root `AGENTS.md` stays short and free of domain.
 
 Commands use the detected tool instead of assuming a single package: `nx affected -t test`,
 `turbo run test --filter=<package>`, `bazel test //<package>/...`, `pnpm --filter <package> test`. The map also
@@ -246,6 +319,10 @@ node .claude/skills/implement/scripts/affected.ts --base origin/main
       "statusMap": { "draft": "To Do", "ready": "Ready", "done": "Done" },
       "priorityMap": { "must": "Highest", "should": "High" }
     }
+  },
+  "research": {
+    "expiryMonths": 12,
+    "gate": { "risk": ["high"], "labels": ["security", "auth", "payment", "privacy"] }
   }
 }
 ```
@@ -303,9 +380,10 @@ For Jira, `jira-plan.ts` prints the exact MCP calls, `jira-record.ts` writes the
   node .claude/skills/adopt/scripts/boundary-check.ts --update-baseline
   ```
 - **`verify.ts`** is the one gate: project checks, artifact validity, scenario ↔ test traceability, domain IDs in
-  the code, glossary language.
-- **Review agents** never write code: `code-reviewer` and `acceptance-tester` report, the acceptance verdict decides
-  whether a story is `done`.
+  the code, glossary language. Referenced research files are checked for expiry as an advisory step.
+- **Review agents** never write code or stories: `code-reviewer` and `acceptance-tester` report findings, the
+  acceptance verdict decides whether a domain story is `done`, and a finding is fixed in the story or handed back
+  as an open question. `ux-designer` is an on-demand utility (`ui: true`), never a gate.
 
 ## Upgrading
 
@@ -318,6 +396,11 @@ npx kataster doctor
 overwrite files you changed locally – it lists them instead. `--force` overwrites and writes a backup to
 `.kataster/backup/`.
 
+Project content includes `docs/workflow.md` and the context maps. An upgrade does not rewrite them; compare
+`docs/workflow.md` with `templates/docs/workflow.md` if you want the new rules in an existing project. The schema
+changes are additive: an aggregate without `status` is `target`, a missing `context-map.as-is.md` or gap register is
+not an error, and the new checks are advisory until the artifacts exist.
+
 ## Design notes
 
 - **`.claude/` is the source of truth.** OpenCode and Claude Code share skills, agents and hooks; `.opencode/` is an
@@ -347,8 +430,9 @@ Kataster stands on other people's work:
 - **Matt Pocock** – [skills](https://github.com/mattpocock/skills), [aihero.dev](https://www.aihero.dev). The grilling
   interview (`grilling`, `grill-me`, `grill-with-docs`), test-driven development (`tdd`), the deep-module vocabulary
   (`codebase-design`), the architecture survey (`improve-codebase-architecture`), the throwaway prototype
-  (`prototype`), the retro, the domain-modeling discipline and `writing-for-agents` come from his skill repository –
-  partly adapted, partly copied verbatim under MIT. The per-file mapping and the license text are in
+  (`prototype`), the research skill (adapted: read-only researcher, source tiers, expiry, grilling integration), the
+  retro, the domain-modeling discipline and `writing-for-agents` come from his skill repository – partly adapted,
+  partly copied verbatim under MIT. The per-file mapping and the license text are in
   [.claude/THIRD_PARTY_NOTICES.md](.claude/THIRD_PARTY_NOTICES.md).
 - **John Ousterhout**, *A Philosophy of Software Design* – "Design It Twice" and the depth, seam and deletion-test
   vocabulary.