kataster 0.3.1 → 0.6.0

package/.claude/skills/adopt/templates/context-map.as-is.md

@@ -0,0 +1,22 @@
+# As-is context map – {{project}}
+
+> Recovered from code by `/adopt` on {{date}} at {{commit}}. This is **not a target**.
+> Target: [context-map.md](context-map.md) · Gap register: [gap-register.md](gap-register.md).
+
+<!--
+  One section per recovered bounded context. Use `### BC-… – <name>` so gap-register.ts can link to it.
+  Evidence is a table, a service method or a path; no target statements, no invented terms.
+-->
+
+```mermaid
+flowchart LR
+  %% BC-ExampleA -->|recovered dependency| BC-ExampleB
+```
+
+## Contexts
+
+### BC-Example – <name>
+Purpose (as recovered): …
+Core terms: …
+Evidence: `<path:line>`, `<table>`, `<service method>`.
+Boundaries: …

package/.claude/skills/architect/SKILL.md

@@ -21,10 +21,15 @@ Domain language (the glossary in `CONTEXT.md`), bounded contexts, aggregates and
     ├── architecture/
     │   └── data-model.md       ← logical data model (domain-model skill)
     └── domain/
-        ├── context-map.md
+        ├── context-map.md        ← target map
+        ├── context-map.as-is.md  ← as-is snapshot, written only by /adopt
+        ├── gap-register.md       ← as-is ↔ target gaps (generated rows + decisions)
         └── events.yaml
 ```
 
+`docs/domain/context-map.md` is the target; `context-map.as-is.md` is the snapshot recovered by `/adopt`. Do not
+write the as-is map from an architecture session – a target decision belongs in the target map.
+
 Once code exists and contexts live in separate modules, context-specific decisions may move next to the code (`src/<context>/docs/adr/`); system-wide decisions stay in `docs/adr/`.
 
 ## During the session

package/.claude/skills/backlog/SKILL.md

@@ -155,8 +155,8 @@ silently – ask the user.
 
 ## When to sync
 
-- after `requirements-engineer` created or changed stories → `push`
-- after `product-owner` or `lead-dev` changed `priority`, `size`, `risk`, `depends_on` → `push`
+- after the main session created or changed stories (spec engineer) → `push`
+- after `priority`, `size`, `risk` or `depends_on` changed → `push`
 - before `/review-stories` → `pull`, then review, then `push` the approved stories
 - before `/implement` → `pull`; after each status change the workflow updates the tracker (GitHub directly, Jira by
   the printed MCP transition), and after `done` → `push`

package/.claude/skills/bootstrap/SKILL.md

@@ -77,24 +77,26 @@ and reason. Do not let it become a mood board.
 
 ## Phase 5 – Foundation stories and the first slice
 
-Delegate to `requirements-engineer` in two parts:
+Write the stories yourself as the spec engineer (the `user-stories` skill is the method), in two parts:
 
 1. **Foundation tech tasks** – what every later story relies on: repository skeleton, the single quality command
    (`verify`), CI, the test harness and test data approach, auth/roles if the vision needs them, deployment.
    Each is a tech task with a checklist and `depends_on`, not a domain story. Keep them minimal: foundation just
    in time, not a platform project.
 2. **The first vertical slice** – the smallest set of stories that delivers one real end-to-end path from the
-   vision (e.g. "report → triage → resolve"), each a story with Gherkin scenarios, `ui` where a person sees
+   vision (e.g. "report → triage → resolve"), each a story with Gherkin scenarios, `ui: true` where a person sees
    something.
 
-Rules: at most 10 scenarios per story; no implementation plan inside a domain story; every story links its
-`events`; `status: draft`, then `review` when finished.
+Rules: one story = one command + its events on one aggregate, at most 4 scenarios; no implementation plan inside a
+domain story; every domain story links `aggregate`, `command` and its `events`; `status: draft`, then `review` when
+finished. The spec linter must be green before `ready-for-human-review`.
+
 
 ## Phase 6 – Review
 
-Read `.claude/skills/review-stories/SKILL.md` and follow it with the story IDs from Phase 5. The user approves
-every `ready`. Fix what the review finds through `requirements-engineer` – never by editing a story into shape
-yourself when the change is structural.
+Read `.claude/skills/review-stories/SKILL.md` and follow it with the story IDs from Phase 5. The spec linter is the
+gate; the user approves every `ready`. Fix what it finds in the story (or in the model, when an event or aggregate
+is missing) – never work around a lint error.
 
 ## Phase 7 – Wrap-up
 

package/.claude/skills/domain-model/CONTEXT-FORMAT.md

@@ -42,6 +42,6 @@ _Avoid_: Fix, service
 
 ## Single vs multi-context
 
-During discovery there is one root `CONTEXT.md`, grouped by bounded context; the relationships between contexts are in `docs/domain/context-map.md`.
+During discovery there is one root `CONTEXT.md`, grouped by bounded context; the relationships between contexts are in `docs/domain/context-map.md` (target). `/adopt` records what the code does today in `docs/domain/context-map.as-is.md` – not a target.
 
 When code exists and contexts become separate modules, the glossary may be split: a root `CONTEXT-MAP.md` lists the contexts and links to one `CONTEXT.md` per module (e.g. `src/workshop/CONTEXT.md`). Only split when the code is actually structured that way – decide it via ADR.

package/.claude/skills/domain-model/SKILL.md

@@ -15,7 +15,9 @@ Architecture decisions (ADRs, tech stack) belong to the `architect` skill. The d
 |---|---|
 | Glossary (ubiquitous language) | `CONTEXT.md` at the repo root – format: [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) |
 | Event storming model incl. `bounded_contexts`, `aggregates` | `docs/domain/events.yaml` |
-| Context map | `docs/domain/context-map.md` |
+| Target context map | `docs/domain/context-map.md` – where the domain is going |
+| As-is context map | `docs/domain/context-map.as-is.md` – recovered from code, written only by `/adopt` |
+| Gap register | `docs/domain/gap-register.md` – links as-is and target, generated rows + user decisions |
 | Logical data model | `docs/architecture/data-model.md` – template: `templates/data-model.md` |
 
 ## 1. Language (during every session)
@@ -30,7 +32,7 @@ When the user uses vague or overloaded terms, propose a precise canonical term.
 When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. "A customer reports the same problem on an item that already has an open case – a new case or the same one?"
 
 ### Cross-reference with docs and code
-When the user states how something works, check whether `docs/domain/events.yaml`, the stories (and the code, once it exists) agree. If you find a contradiction, surface it.
+When the user states how something works, check whether `docs/domain/events.yaml`, the stories (and the code, once it exists) agree. If you find a contradiction, surface it. A source that contradicts the model is a grilling question, not a silent rewrite of the model (see the `research` skill).
 
 ### Update CONTEXT.md inline
 When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. `CONTEXT.md` is totally devoid of implementation details. It is a glossary and nothing else – not a spec, not a scratch pad.
@@ -39,7 +41,8 @@ Same word, different meaning in two places → a hint at a bounded context bound
 
 ## 2. Bounded Contexts & Context Map
 - Draw boundaries along language (same word, different meaning → different context) and responsibility (who decides?).
-- `docs/domain/context-map.md`: per context its purpose, core terms, owner role. Relationships as a Mermaid `flowchart` using the patterns Customer/Supplier, Conformist, Anti-Corruption Layer, Shared Kernel, Published Language.
+- `docs/domain/context-map.md` is the **target** map: per context its purpose, core terms, owner role. Relationships as a Mermaid `flowchart` using the patterns Customer/Supplier, Conformist, Anti-Corruption Layer, Shared Kernel, Published Language.
+- `docs/domain/context-map.as-is.md` is the **as-is** snapshot: what the code does today, with evidence. Only `/adopt` writes it; every other discovery path writes the target. The gap register links both.
 - 2–4 contexts are typical for a small system. More only with justification.
 - Maintain them in `events.yaml` under `bounded_contexts`, and group the terms in `CONTEXT.md` by context.
 
@@ -47,9 +50,26 @@ Same word, different meaning in two places → a hint at a bounded context bound
 - An aggregate protects invariants that must be consistent **immediately**. Everything else is eventually consistent via events/policies.
 - Keep them small. Reference other aggregates by ID only.
 - Per aggregate in `events.yaml`: `context`, `invariants` (as testable statements). Assign commands and events via `aggregate`.
-- **An invariant is stated once, on the aggregate** (user, 2026-10-01). A command's `rules` list only what it adds beyond them: defaults, actor permissions no invariant carries, required input, checks across aggregate or context boundaries, and consequences of the transition. Everything the stored state has to satisfy is an invariant, not a rule – the requirements-engineer reads both when deriving scenarios.
+- **An invariant is stated once, on the aggregate** (user, 2026-10-01). A command's `rules` list only what it adds beyond them: defaults, actor permissions no invariant carries, required input, checks across aggregate or context boundaries, and consequences of the transition. Everything the stored state has to satisfy is an invariant, not a rule – the spec engineer reads both when deriving scenarios.
 - Sign of a wrong aggregate: a command needs data from several aggregates to check a rule.
 
+### Aggregate status: target, as-is, unresolved
+Every aggregate carries a status; a missing `status` means `target`, so existing models stay valid.
+
+| Status | Meaning | Rule |
+|---|---|---|
+| `target` | The boundary the project wants. The default in greenfield and in a confirmed target model. | Only a user decision makes an inferred boundary `target`. |
+| `as-is` | The factual consistency boundary recovered from code. | Requires `evidence`: the table, service method or path that marks it. |
+| `unresolved` | The boundary is unclear. | Requires an open hotspot (`refs: [AGG-…]`) and grilling. No story on it can become ready. |
+
+**Prefer `as-is` or `unresolved` over an invented aggregate.** `/adopt` never writes `target` for something it
+inferred from code. If you cannot name the table, method or path that holds the boundary together, it is not
+`as-is` – it is `unresolved`. After changing a status or evidence, refresh the gap register:
+
+```bash
+node .claude/skills/adopt/scripts/gap-register.ts
+```
+
 ## 4. Logical Data Model (`docs/architecture/data-model.md`)
 - Per aggregate: root entity, entities, value objects, attributes with **domain** types (e.g. `SerialNumber`, `Money`, `Timestamp`), required/optional.
 - Lifecycle as a Mermaid `stateDiagram-v2` (derive states from the events).

package/.claude/skills/event-storming/SKILL.md

@@ -12,7 +12,8 @@ Focus of this session: the arguments from the invocation (empty = big picture ac
 
 ## Preparation
 1. Call the `skill` tool for `grilling` and `domain-model`. Grilling sets how you ask questions; domain-model sets how you guard the language in `CONTEXT.md`.
-2. Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`.
+2. Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md` (target),
+   `docs/domain/context-map.as-is.md` and `docs/domain/gap-register.md` when they exist.
 3. Format reference: `templates/events.example.yaml` in this skill folder (unrelated example domain – copy the format only, no content).
 
 ## Facilitation Rules
@@ -33,7 +34,7 @@ Focus of this session: the arguments from the invocation (empty = big picture ac
 4. **Commands & actors** – What triggers each event, and who does it? Capture external systems (`EXT-`). Business rules of the command go into `rules` – only what the command adds beyond the `invariants` of its aggregate, which are stated once, there (user, 2026-10-01).
 5. **Policies** – "Whenever <event>, then <command>". Include time-triggered ones (event with `origin: time`) and manual routines.
 6. **Read models** – What information does an actor need to trigger the command? (`fed_by`, `used_by`, `fields`)
-7. **Aggregates (proposal)** – Which rules must be protected consistently? Rough assignment of commands/events. Detailed work is done by `domain-architect`.
+7. **Aggregates (proposal)** – Which rules must be protected consistently? Rough assignment of commands/events. Detailed work is done by `domain-architect`. Every aggregate gets `status: target` in greenfield; a boundary the user cannot settle becomes `status: unresolved` with an open hotspot. When adopting existing code, the status is `as-is` (with evidence) or `unresolved`, never an invented `target`.
 8. **Bounded contexts (proposal)** – Where do language or responsibility change? Propose rough boundaries.
 
 When focusing on a single process: phases 0–6 for that process (phase 0 only for what the vision doesn't cover yet), 7–8 only if something new emerges.

package/.claude/skills/event-storming/schema/events.schema.json

@@ -51,6 +51,8 @@
         "id": { "type": "string", "pattern": "^AGG-[A-Za-z0-9]+$" },
         "name": { "$ref": "#/$defs/text" },
         "context": { "type": "string" },
+        "status": { "enum": ["target", "as-is", "unresolved"] },
+        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" } },
         "invariants": { "type": "array", "items": { "$ref": "#/$defs/text" } },
         "description": { "type": "string" }
       }

package/.claude/skills/event-storming/templates/events.example.yaml

@@ -24,12 +24,18 @@ aggregates:
   - id: AGG-Bike
     name: Bike
     context: BC-Rental
+    status: target
     invariants:
       - A bike can only be rented out once at a time
       - A bike marked as damaged cannot be rented out
   - id: AGG-RepairOrder
     name: Repair order
     context: BC-Workshop
+    # status: as-is          # factual boundary recovered from code; add evidence below
+    # evidence:
+    #   - repair_orders table (db/schema.sql:40)
+    #   - RepairOrderService.open() (src/services/repairOrderService.ts:22)
+    # status: unresolved    # boundary unclear; add an open hotspot with refs: [AGG-RepairOrder]
 
 events:
   - id: EVT-BikeRented

package/.claude/skills/feature/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: feature
-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 instead; `--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, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story instead; `--prototype` adds a throwaway prototype before the stories; `--research` forces the research step for a cross-cutting question.
 disable-model-invocation: true
-argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--prototype[=ui|logic]]"
+argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--prototype[=ui|logic]] [--research]"
 ---
 
 # New Feature
@@ -11,6 +11,8 @@ The argument is a feature idea, an existing story or a ticket. Empty → ask the
 Pick a short kebab-case slug for it (e.g. `order-photos`); stories get the label `feature:<slug>`.
 `--prototype[=ui|logic]` is a flag, not part of the idea: strip it before resolving a reference. It asks for a
 prototype before the stories are written; without a branch the `prototype` skill picks it from the question.
+`--research` is a flag too: strip it before resolving a reference. It forces the research step for a topic the
+trigger list in step 2 does not catch.
 
 ## 0. Intake – when the argument is a reference
 
@@ -57,14 +59,15 @@ ADRs and `docs/product/ux-guidelines.md` first.
 Do not run an event storming for a bug and do not create a feature slug unless the rule changes.
 
 ## 1. Preparation
-Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`, `docs/architecture/data-model.md`, `docs/adr/`, `docs/stories/BACKLOG.md`. Find out what already exists for this idea (events, stories, hotspots) before asking anything. With an intake result, use its source and matching story instead of searching from scratch. If a linked story exists, pull the tracker first (`/backlog-sync pull`) so the mirror is current.
+Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md` (target), `docs/domain/context-map.as-is.md`, `docs/domain/gap-register.md`, `docs/architecture/data-model.md`, `docs/adr/`, `docs/stories/BACKLOG.md`. Find out what already exists for this idea (events, stories, hotspots) before asking anything. With an intake result, use its source and matching story instead of searching from scratch. If a linked story exists, pull the tracker first (`/backlog-sync pull`) so the mirror is current.
 
 ## 2. Grill the idea
-Call the `skill` tool four times, for `grilling`, `domain-model`, `architect` and `ux-design` (the first three are the set of `/grill-with-docs`, which can't be called from a skill). Grill the user until the frontier is empty and they confirm a shared understanding. The grilling carries the three perspectives the story review later only checks – product owner, lead dev, UX. With an intake result, the ticket's claims and the intake's `signals` seed the frontier; unresolved comments and contradictions are the first questions. Typical branches:
-- **PO**: Which problem, for which user group, and what value? Measurable outcome? Does it fit the vision, or touch a non-goal? If it changes scope → update `docs/product/vision.md` with the user. Must vs. could – what ships first?
-- **Lead dev**: Which existing code, data and stories change? Is there a migration? What is hard to test? Where does it cut into stories – each a vertical slice of at most ~10 scenarios?
+Call the `skill` tool four times, for `grilling`, `domain-model`, `architect` and `ux-design` (the first three are the set of `/grill-with-docs`, which can't be called from a skill). Grill the user until the frontier is empty and they confirm a shared understanding. The grilling carries the three perspectives the spec linter cannot check – product, engineering, UX. With an intake result, the ticket's claims and the intake's `signals` seed the frontier; unresolved comments and contradictions are the first questions. Typical branches:
+- **Research – does the idea rest on an external fact?** Auth/identity, security, payment, privacy/data protection, accessibility, performance, a new library or technology, or `--research`: load the `research` skill before grilling the affected branch. Check `docs/research/` first; a trigger is not a mandate, and one run covers a topic, not a story. Findings enter the round as cited recommendations – evidence, not decisions.
+- **Product**: Which problem, for which user group, and what value? Measurable outcome? Does it fit the vision, or touch a non-goal? If it changes scope → update `docs/product/vision.md` with the user. Must vs. could – what ships first?
+- **Engineering**: Which existing code, data and stories change? Is there a migration? What is hard to test? Where does it cut into stories – one command per story, at most 4 scenarios?
 - Which existing processes, events and stories does it change? What's explicitly out of scope?
-- **UX – does a person see anything?** Almost always yes – then the UX frontier of `ux-design` belongs in the rounds: entry point, the screen's one job, what is shown before acting, what happens afterwards, the rejected, empty, full and no-permission cases, and the UI wording. A feature whose screens nobody named gets them by accident. Stories with a frontend part get the label `ui`.
+- **UX – does a person see anything?** Almost always yes – then the UX frontier of `ux-design` belongs in the rounds: entry point, the screen's one job, what is shown before acting, what happens afterwards, the rejected, empty, full and no-permission cases, and the UI wording. A feature whose screens nobody named gets them by accident. Stories with a frontend part get `ui: true`.
 - **Prototype – is paper enough?** When the UX frontier leaves a structural layout choice, a flow or a state model that cannot be settled in words, the UX lens proposes a prototype: one question, the branch (`ui` or `logic`), the variants or scenarios, and a timebox. The user decides. `--prototype` makes it explicit. Do not propose one for polish or for a question a guideline already answers. If it is agreed, run step 2b before the event storming.
 - New or changed terms → `CONTEXT.md` inline.
 - An architectural trade-off → ADR (`status: proposed`) only if the architect skill's three criteria hold.
@@ -86,9 +89,9 @@ it. In short:
 4. **Capture.** The decision goes to `ux-designer` for `docs/product/ux-guidelines.md` (a G-number when it is
    a recurring rule). Commit `docs/prototypes/<slug>/` on a throwaway branch `prototype/<slug>`, push it only
    if the user wants to share it, then return to the branch you were on. The branch is never merged.
-5. **Into the story.** Pass the verdict and the branch pointer to `requirements-engineer` in section 5: the
-   story's `## Context` gets `Prototype: prototype/<slug> – <question> – <verdict>`, and the scenarios reflect
-   the decision. The `ux-designer` never writes the story itself.
+5. **Into the story.** In section 5 you write the verdict and the branch pointer into the story's `## Context`:
+   `Prototype: prototype/<slug> – <question> – <verdict>`, and the scenarios reflect the decision. The
+   `ux-designer` never writes the story itself.
 
 If the question needs the real application (an existing page, real data), say so: that is an in-app prototype
 and belongs to `/implement`, not to discovery. If the prototype does not answer the question within its
@@ -103,10 +106,10 @@ Read `.claude/skills/event-storming/SKILL.md` and follow it with the feature as
 - A UX decision changes or adds a guideline → delegate to `ux-designer`: write exactly these decisions into `docs/product/ux-guidelines.md`. A prototype verdict is a decision like any other; the branch pointer and the verdict go into the story through step 5. The audit of existing screens belongs to `/groom-backlog`, not to the feature.
 
 ## 5. Stories
-Delegate to `requirements-engineer`: derive stories for the feature's new or changed commands, policies and read models; name the event/command IDs, the label `feature:<slug>`, the label `ui` for every story with a frontend part, the label `bug` for the bug path, the source reference (`Source: <ref> (<url>)`) for every story derived from a ticket, the UX decisions from step 2 (with the G-numbers of the guidelines they reference), the prototype verdict and branch pointer from step 2b, the story cut from step 2, and existing stories that need revising. Finished stories get `status: review`; have it report the IDs of all stories it created or revised.
+Write the stories yourself as the spec engineer (the `user-stories` skill is the method): derive one story per new or changed command, policy or read model; name `aggregate` and `command` (exactly one each), the event/command IDs, `ui: true` for every story with a frontend part, `type: chore`/`task` for non-domain work, the label `feature:<slug>`, the label `bug` for the bug path, the source reference (`Source: <ref> (<url>)`) for every story derived from a ticket, the research files they cite (`sources: [docs/research/<topic>.md]`) with adopted/rejected findings and their reasons in `## Context`, the UX decisions from step 2 (with the G-numbers of the guidelines they reference), the prototype verdict and branch pointer from step 2b, and existing stories that need revising. Do not merge two commands into one story; if the cut needs more than 4 scenarios, split it. Finished stories get `status: review` and are run through the spec linter.
 
 ## 6. Review
-Read `.claude/skills/review-stories/SKILL.md` and follow it with the story IDs from step 5 as the arguments (only this feature's stories, not everything in `review`). The user still approves every change and every `ready`.
+Read `.claude/skills/review-stories/SKILL.md` and follow it with the story IDs from step 5 as the arguments (only this feature's stories, not everything in `review`). The spec linter must be green before a story reaches `ready-for-human-review`; the user approves every change and every `ready`. There is no separate review subagent.
 
 ## 7. Wrap-up
-Summarize: the source and the route taken (idea, ticket, existing story or bug), glossary changes, new/changed events, ADRs proposed, a prototype run and its verdict (if any), stories created and their review outcome (`ready` vs. still open), open hotspots/questions. Point to `docs/stories/BACKLOG.md`, where `ready` stories are queued for the engineering workflow. For a bug, say which documented rule was restored, or that the rule changed and became a feature.
+Summarize: the source and the route taken (idea, ticket, existing story or bug), glossary changes, new/changed events, ADRs proposed, research files created or refreshed and the findings the user adopted or rejected, a prototype run and its verdict (if any), stories created and their review outcome (`ready` vs. still open), open hotspots/questions. Point to `docs/stories/BACKLOG.md`, where `ready` stories are queued for the engineering workflow. For a bug, say which documented rule was restored, or that the rule changed and became a feature.

package/.claude/skills/feature/scripts/intake.ts

@@ -94,7 +94,7 @@ function storyRef(story: d.Story): StoryRef {
     path: d.rel(story.path),
     title: String(story.meta.title ?? ""),
     status: String(story.meta.status ?? ""),
-    type: String(story.meta.type ?? "story"),
+    type: String(story.meta.type ?? "domain"),
   };
 }
 

package/.claude/skills/grilling/SKILL.md

@@ -27,4 +27,19 @@ Each round the user answers reshapes the tree: settled decisions push the fronti
 
 Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
 
+## Research before a round
+
+When a frontier question depends on an external fact – authentication/identity, security, payment, privacy/data
+protection, accessibility, performance, a new library or technology – load the `research` skill before the round. A
+trigger is **not a mandate**: if `CONTEXT.md`, `docs/domain/events.yaml`, an accepted ADR, the UX guidelines, the
+conventions or a valid research file already answers it, run nothing. One run per topic, not per story.
+
+- The recommendation cites the finding and its source: `➡️ … (RFC 9700 §2.1.1; F1 in docs/research/oauth-pkce.md)`.
+- Only a confirmed recommendation becomes a Gherkin scenario or checklist item with an observable threshold – never
+  "follow best practices". A finding that cannot be tested is context or a guideline, not an acceptance criterion.
+- Rejected options are recorded with the reason in the story's `## Context` / `## Out of Scope` (or the ADR /
+  initiative). The research file stays evidence and is not rewritten into a decision log.
+- A finding that contradicts `CONTEXT.md`, `events.yaml`, an accepted ADR or the UX guidelines is a grilling
+  question. Never edit the model to match the source silently.
+
 The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/.claude/skills/groom-backlog/SKILL.md

@@ -15,7 +15,8 @@ every done story, every ADR and every answered open question since then may have
 or differently important. Nothing here is a formality – a grooming run that changes nothing was a wasted run or a
 healthy backlog, and you have to be able to say which.
 
-Do **not** fix anything yourself. Grooming produces a decision for the user and a task for the `requirements-engineer`.
+Do **not** fix anything yourself. Grooming produces a decision for the user. The main session carries the product and
+engineering lenses; it does not delegate them to simulated roles.
 
 ## 1. Mechanical health check
 
@@ -39,22 +40,23 @@ rows in `OPEN_QUESTIONS.md`, and the "revisit when …" lines parked in `docs/re
 this list to the subagents – they cannot see it, and without it they re-read the same stories that were already
 reviewed once.
 
-## 3. Challenge in parallel
+## 3. Challenge – two lenses, one pass
 
-Start in **one** message, with the full file paths, the scope and the change list from step 2:
+The main session holds both lenses at once. Write down which one produced each finding; do not average a conflict
+between them away.
 
-- `product-owner` – is the value still real and still in the vision? Is the story already covered by what was
-  built? Does the MVP slice still hold? Which `must` is not a `must` any more, and which `could` turned out to be
-  one? Which need from the vision still has no story?
-- `lead-dev` – do `depends_on`, `size` and `risk` still fit **now that the code exists**? Which story has become
+- **Value** – is the value still real and still in the vision? Is the story already covered by what was built? Does
+  the MVP slice still hold? Which `must` is not a `must` any more, and which `could` turned out to be one? Which
+  need from the vision still has no story?
+- **Build** – do `depends_on`, `size` and `risk` still fit **now that the code exists**? Which story has become
   smaller because the foundation is there, which bigger? Which dependency is technical fiction? Which story should
-  be split, merged or dropped?
-- `ux-designer` – only for stories with the label `ui` (or an obvious frontend part): does the story still match
-  `docs/product/ux-guidelines.md`, which one builds a screen that a newer story has replaced, and is there an open
-  UX question that needs a prototype (the `prototype` skill) before the story can be reviewed again?
+  be split (one command!), re-typed as `chore`/`task`, or dropped?
 
-Tell each one explicitly: **recommend, don't rewrite** – they change only the frontmatter fields they own
-(`priority` for the PO, `size`/`risk`/`depends_on` for the lead dev), everything else comes back as a proposal.
+For stories with `ui: true` (or an obvious frontend part), ask the `ux-designer` only when a concrete question needs
+it – component/pattern, an open UX decision, or a prototype. It advises; it does not gate.
+
+Do not hand the backlog to subagents: the change list from step 2 is context they cannot see, and re-reading stories
+that were already reviewed once is the cost this workflow removes.
 
 ## 4. Consolidate
 
@@ -62,22 +64,22 @@ Write `docs/reviews/YYYY-MM-DD-backlog-grooming.md`:
 
 - the health-check findings with what they turned out to mean
 - per challenged story: keep / revise / split / merge / drop, with the reason and who said it
-- conflicts between the three – name them, don't average them away
+- conflicts between the two lenses – name them, don't average them away
 - proposed new stories, and stories proposed for `priority: wont`
 - what explicitly stays as it is, so the next run does not re-litigate it
 
 ## 5. The user decides
 
 Present it in rounds, at most 3 questions at a time, each with a recommended answer. Adopt nothing without consent.
-A disagreement between PO and lead-dev is a question for the user, not something to resolve on their behalf.
+A disagreement between value and build is a question for the user, not something to resolve on their behalf.
 
 ## 6. Apply
 
-- Content changes → `requirements-engineer`, referencing the grooming file.
+- Content changes → edit the story in the main session, referencing the grooming file; then re-run the spec linter.
 - **Dropped stories are never deleted**: they get `priority: wont` and keep their file, so the decision stays
   traceable. A story that is wrong rather than unwanted goes back to `status: review` and through `/review-stories`.
 - A `done` story is never reopened – a change to finished behaviour is a new story.
-- New stories from the grooming get `status: draft` and go through `/review-stories` like any other.
+- New stories from the grooming get `status: draft` and go through `/review-stories` like any other (linter → human).
 - With a tracker, push the applied changes (`/backlog-sync push`) before the wrap-up, so Jira/GitHub and the mirror
   agree. A story that is not linked yet stays a local draft until the push creates it.