kataster 0.4.0 → 0.6.0

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

@@ -20,7 +20,7 @@ Rules:
   `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.4)
+## Workflow contract (0.5)
 
 The workflow is spec-driven and mechanical, not a simulated organisation:
 
@@ -31,7 +31,20 @@ The workflow is spec-driven and mechanical, not a simulated organisation:
   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

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 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`

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 and the on-demand UX utility (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,13 +115,14 @@ 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 |
+| `/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? |
@@ -132,6 +137,11 @@ domain, architecture, testability – and one mechanical rule: **one story = 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
@@ -149,6 +159,36 @@ Non-domain work takes the **fast lane**: `type: chore` (UI tweak, refactor, depe
 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
@@ -203,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
@@ -221,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
@@ -270,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"] }
   }
 }
 ```
@@ -327,7 +380,7 @@ 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.
+  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.
@@ -343,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
@@ -372,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.

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") turns the selected gaps into stories in the
-main session (spec engineer, spec linter gate).
+**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 @@ main session (spec engineer, spec linter gate).
 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 | 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kataster",
-  "version": "0.4.0",
+  "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/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

@@ -59,6 +59,7 @@ 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/*)",
+  "Bash(node .claude/skills/research/scripts/*)",
   "Bash(node .claude/skills/adopt/scripts/*)",
   "Bash(node .claude/skills/backlog/scripts/*)",
   "Bash(node .claude/skills/implement/scripts/*)",
@@ -433,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).

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

@@ -11,6 +11,8 @@ Workflow: `draft → review → ready-for-human-review → ready → in-progress
   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.