kataster 0.3.0 → 0.4.0

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/SKILL.md

@@ -47,7 +47,7 @@ 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.
 
 ## 4. Logical Data Model (`docs/architecture/data-model.md`)

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

@@ -1,14 +1,16 @@
 ---
 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.
+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.
 disable-model-invocation: true
-argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL>"
+argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--prototype[=ui|logic]]"
 ---
 
 # New Feature
 
 The argument is a feature idea, an existing story or a ticket. Empty → ask the user for it first.
 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.
 
 ## 0. Intake – when the argument is a reference
 
@@ -28,7 +30,7 @@ Follow the route:
 |---|---|
 | `continue-story` | Read that story and treat it as the idea. Its open questions are the first grilling frontier. Do not create a parallel feature. |
 | `review-story` | Stop; run `/review-stories <id>` (or revise the story if it is still being written). |
-| `implement-story` | Stop; the next command is `/implement <id>`. |
+| `implement-story` | Stop; the next command is `/implement <id>` – with `--prototype` if the user asked for one. |
 | `new-story` | Finished behaviour is final; continue as a new feature and name the old story as the predecessor. |
 | `bug` | Use the bug path below, not the feature pipeline. |
 | `feature` | Continue with step 1. |
@@ -58,29 +60,53 @@ Do not run an event storming for a bug and do not create a feature slug unless t
 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.
 
 ## 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:
+- **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.
 
 Don't move on before the user confirms.
 
+## 2b. Prototype (optional)
+
+Only when the user asked (`--prototype`) or the grilling agreed on it. Load the `prototype` skill and follow
+it. In short:
+
+1. **Question and branch.** Name the one question and pick `ui` (what should it look like) or `logic` (does
+   the state model feel right). Write both at the top of the prototype and in its `README.md`.
+2. **Delegate to `ux-designer`** with the question, the branch, the variants/scenarios, the timebox and the
+   target `docs/prototypes/<slug>/`. It writes a self-contained HTML prototype there – no application code,
+   no tests, no persistence, no shell.
+3. **The user looks and decides.** Open the file, flip the variants or press the buttons. The verdict is the
+   user's, not the agent's.
+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.** 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
+timebox, stop and record what is known.
+
 ## 3. Focused event storming
 Read `.claude/skills/event-storming/SKILL.md` and follow it with the feature as focus: phases 1–6 (phase 0 is covered by step 2), 7–8 only if aggregates or contexts are affected. Capture the feature as its own flow (`FLOW-<FeatureName>`) and write `docs/domain/events.yaml` after every phase.
 
 ## 4. Domain model & architecture
 - Contexts, aggregates or the data model affected → delegate to `domain-architect` with the file paths, the changed/new IDs from `events.yaml` and a clear task.
 - An architectural trade-off came up that wasn't recorded during grilling → offer an ADR per the architect skill's three criteria (`status: proposed`, the user accepts).
-- A UX decision changes or adds a guideline → delegate to `ux-designer`: write exactly these decisions into `docs/product/ux-guidelines.md`. The audit of existing screens belongs to `/groom-backlog`, not to the feature.
+- 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 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 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, 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, 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/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,21 +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`, and which one builds a screen that a newer story has replaced?
+  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
 
@@ -61,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.
 

package/.claude/skills/implement/SKILL.md

@@ -1,117 +1,223 @@
 ---
 name: implement
-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.
+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.
 disable-model-invocation: true
-argument-hint: "[ST-NNN – empty = next ready story]"
+argument-hint: "[ST-NNN – empty = next ready story] [--fast] [--prototype[=ui|logic]]"
 ---
 
 # Implement a Story
 
-Story: the arguments from the invocation (empty → `node .claude/skills/implement/scripts/next-story.ts`; a story already `in-progress` is finished first).
+Story: the arguments from the invocation (empty → `node .claude/skills/implement/scripts/next-story.ts`; a story
+already `in-progress` is finished first). `--fast` and `--prototype[=ui|logic]` are flags, not the story ID: strip
+them before resolving the story.
 
-The main session writes the code; subagents only review. One checkpoint belongs to the user: the **merge** (step 7). Everything before it runs without asking – a `ready` story is good enough to build up to the pull request, and the acceptance tester accepts the story, not the user – unless the story turns out to be wrong (see *When the story is wrong*) or a seam is missing from the catalog (step 2).
+The main session writes the code; subagents only review, and only in the full domain lane. One checkpoint belongs to
+the user: the **merge** (step 7). Everything before it runs without asking – a `ready` story is good enough to build
+up to the pull request, and the acceptance tester accepts the story, not the user – unless the story turns out to be
+wrong (see *When the story is wrong*), a seam is missing from the catalog (step 2), or the user asked for a prototype
+(step 1b – the verdict is theirs).
 
-Engineering conventions: `docs/engineering/conventions.md` – read it if it exists; it describes the module layout, how commands and read models are built, and the **seam catalog**.
+## Two lanes
 
-Project profile: `.claude/project.json` – default branch, code roots, commands, preview provider, pull-request tool. Read it instead of assuming `main`, `npm` or GitHub.
+| Lane | Stories | What changes |
+|---|---|---|
+| **Domain** (default) | `type: domain` (legacy `story`) | TDD per Gherkin scenario, scenario ↔ test traceability, diff-scaled review, acceptance tester's verdict |
+| **Fast** | `type: chore`, `type: task`, or `--fast` on such a story | branch → implement → lint/typecheck/unit tests → verify → PR; no Gherkin matching, no formal review pass, the user merges |
+
+`--fast` on a `type: domain` story is ignored: the story has a command and scenarios, so it takes the domain lane.
+If a "chore" turns out to touch a command, a migration or authorization, stop and say so – risk decides the lane,
+not the label.
+
+Engineering conventions: `docs/engineering/conventions.md` – read it if it exists; it describes the module layout,
+how commands and read models are built, and the **seam catalog**.
+
+Project profile: `.claude/project.json` – default branch, code roots, commands, preview provider, pull-request tool.
+Read it instead of assuming `main`, `npm` or GitHub.
 
 ## 1. Prepare
-1. Working tree clean, on the default branch (`repo.defaultBranch`), up to date (`git pull`). Otherwise stop and tell the user.
+1. Working tree clean, on the default branch (`repo.defaultBranch`), up to date (`git pull`). Otherwise stop and tell
+   the user.
 2. With a tracker (`backlog.provider` ≠ `local`), pull first (`/backlog-sync pull`) and check that the story has its
    `external` key – an unlinked story never reaches `ready`, so stop and report instead of implementing a stale mirror.
-3. `node .claude/skills/implement/scripts/story-context.ts ST-NNN` – the context pack: story, exact test titles, dependencies, events/commands/rules/invariants, glossary, data model, ADRs. Read it completely; it is your source, not memory.
-4. `git switch -c st-NNN-<slug>` (slug from the file name), then `node .claude/skills/implement/scripts/story-status.ts ST-NNN in-progress` and commit `ST-NNN: start`.
+3. `node .claude/skills/implement/scripts/story-context.ts ST-NNN` – the context pack: story, exact test titles,
+   dependencies, events/commands/rules/invariants, glossary, data model, ADRs. Read it completely; it is your
+   source, not memory.
+4. `git switch -c st-NNN-<slug>` (slug from the file name), then
+   `node .claude/skills/implement/scripts/story-status.ts ST-NNN in-progress` and commit `ST-NNN: start`.
+5. **Pick the lane** and say it in one line: fast lane for `chore`/`task`, domain lane otherwise. The fast lane is
+   a shortcut for non-domain work, never a way to skip a risk review.
+
+## 1b. Prototype (only when asked)
+
+Only with `--prototype`, or when the user explicitly asks during the story. A `ui: true` story whose screen shape is
+still open was not `ready`; this is the exception that settles it before the test plan. Load the `prototype` skill and
+follow it.
+
+1. **Standalone first.** Delegate to `ux-designer`: question, branch (`ui` or `logic`), variants/scenarios, timebox,
+   target `docs/prototypes/<slug>/`. It writes the self-contained HTML file. The user decides.
+2. **In-app only when the question needs the real page** – an existing route, real data, the real header and
+   sidebar. You build the throwaway route or the `?variant=` gate yourself, following the project's routing
+   convention; the `ux-designer` defines the question and variants and reviews the result. The prototype stays out of
+   the production path and is captured on `prototype/<slug>`.
+3. **Capture.** Commit `docs/prototypes/<slug>/` (or the in-app prototype) on `prototype/<slug>`, return to the story
+   branch, and write the verdict into the story's `## Context`: `Prototype: prototype/<slug> – <question> – <verdict>`.
+   A recurring rule goes to `ux-designer` for `docs/product/ux-guidelines.md`.
+4. **Then decide.** If the prototype only settles layout and the scenarios still hold, continue with step 2. If it
+   changes behaviour or a scenario, the story goes back to `review` (see *When the story is wrong*), the main session
+   revises it, the spec linter runs and the user approves it again. The branch stays.
 
 ## 2. Test plan
-Call the `skill` tool for `tdd` (and `codebase-design` when a new module or interface is involved).
+
+**Domain lane.** Call the `skill` tool for `tdd` (and `codebase-design` when a new module or interface is involved).
 Show one table and go on to step 3 without waiting:
 
 | Scenario (exact test title) | Seam | Test type | Test file |
 |---|---|---|---|
 
-- **Story**: one row per Gherkin scenario. **Tech task**: one row per checklist item that can be tested; the rest gets its evidence named (setting, document). **Spike**: no table – see *Spikes*.
-- Seams come from the seam catalog in the engineering conventions. A seam not in the catalog is a decision for the user – the one case where you stop here and ask.
+- One row per Gherkin scenario – at most 4 by the 1-command rule.
+- Seams come from the seam catalog in the engineering conventions. A seam not in the catalog is a decision for the
+  user – the one case where you stop here and ask.
 - Name anything the story leaves open. Don't guess – see *When the story is wrong*.
 
 Seams from the catalog are the "confirmed seams" the tdd skill requires; the user approved the catalog.
 
-## 3. Red → green, one scenario at a time
-- Per row: write the test (title exactly `ST-NNN: <scenario title>`), run it and see it fail for the right reason, write the minimal code to pass, run it green. Commit: `ST-NNN: <scenario title>`.
-- Domain IDs in the code: commands, events, read models and policies carry their ID from `events.yaml` (`CMD-ReportProblem`, `EVT-ProblemReported`, …). New code uses the words of `CONTEXT.md`; a new term goes into `CONTEXT.md` first (domain-model skill).
-- Never weaken or delete an existing test to get green. If a test from an earlier story blocks you, its story and this one contradict each other → *When the story is wrong*.
-- Hooks help on the way: formatting and lint after every write, the quick gate (type check + related tests) before you finish a turn.
-- In a monorepo, run the affected set for the packages you touched before the full gate:
-  `node .claude/skills/implement/scripts/affected.ts --changed <files>` (or `--base <defaultBranch>`), then
-  execute the printed command. It follows shared-library dependents; `verify.ts` still runs everything at the end.
+**Fast lane.** No scenario table. Name the files or packages you will touch and the unit/integration tests that
+cover them; the story's checklist is the acceptance. If it already has scenarios, keep them as a sanity check but do
+not create `ST-NNN:` test titles.
+
+## 3. Red → green (domain) / implement (fast)
+
+**Domain lane:**
+- Per row: write the test (title exactly `ST-NNN: <scenario title>`), run it and see it fail for the right reason,
+  write the minimal code to pass, run it green. Commit: `ST-NNN: <scenario title>`.
+- Domain IDs in the code: commands, events, read models and policies carry their ID from `events.yaml`
+  (`CMD-ReportProblem`, `EVT-ProblemReported`, …). New code uses the words of `CONTEXT.md`; a new term goes into
+  `CONTEXT.md` first (domain-model skill).
+- Never weaken or delete an existing test to get green. If a test from an earlier story blocks you, its story and
+  this one contradict each other → *When the story is wrong*.
+
+**Fast lane:**
+- Implement the task, keep the change as small as the checklist says, and add or update unit tests where the change
+  can break behaviour. No test-title matching, no scenario traceability.
+- Tick each checklist item in the story file as it becomes true (`- [x] …`).
+- If the work turns into domain behaviour (a new/changed command, event or invariant), stop: the story is the wrong
+  type. Send it back to `review` as a `domain` story instead of deciding it in code.
+
+**Both lanes** – hooks help on the way: formatting and lint after every write, the quick gate (type check + related
+tests) before you finish a turn. In a monorepo, run the affected set for the packages you touched before the full
+gate: `node .claude/skills/implement/scripts/affected.ts --changed <files>` (or `--base <defaultBranch>`), then
+execute the printed command. It follows shared-library dependents; `verify.ts` still runs everything at the end.
 
 ## 4. Verify
-`node .claude/skills/implement/scripts/verify.ts` (with `--e2e` when browser tests exist) must be green: lint incl. module boundaries, type check, tests, events and stories valid, scenario ↔ test and domain ID traceability. Language warnings: fix or justify.
+`node .claude/skills/implement/scripts/verify.ts` (with `--e2e` when browser tests exist) must be green: lint incl.
+module boundaries, type check, tests, events and stories valid, scenario ↔ test and domain ID traceability. Language
+warnings: fix or justify.
 
-The full `--e2e` run happens **once, before the push**. During red → green run only the spec you are working on; after the refactor (step 6) run `verify.ts` without `--e2e` plus the specs the refactor touched – CI runs every browser test on the pull request anyway (check `e2e`).
+The full `--e2e` run happens **once, before the push**. During red → green run only the spec you are working on;
+after the refactor (step 6) run `verify.ts` without `--e2e` plus the specs the refactor touched – CI runs every
+browser test on the pull request anyway (check `e2e`).
 
-## 5. Review (in parallel, scaled to the story)
-Push the branch (`git push -u origin st-NNN-<slug>`) so a preview deployment exists, when the project has one
-(`review.preview` in `.claude/project.json`: `vercel`, `netlify`, … – use the provider's MCP or CLI, or the pull
-request's preview comment). Otherwise there is no preview and the reviewers work from the code.
+## 5. Review (domain lane only, scaled to the diff)
 
-Pick the lane first – review effort follows the risk of the diff, not a fixed list:
+**Fast lane: skip this step.** No `code-reviewer`, no `acceptance-tester`, no review file. The gate is step 4 plus
+the user's merge. If the diff touches authorization, input handling, a migration or security headers, say so and offer
+the normal review anyway – the lane follows the risk, not the label.
 
-**Light lane** – when **all** of these hold: size **S**, `events: []`, no command, no migration, no input handling
-(no request handler, form action or route added or changed), no new dependency. Typical: static pages, texts, a
-link, layout.
-- Only `acceptance-tester` – task: story ID, base ref, the preview URL (if known), and: *also check the diff briefly against the engineering conventions (texts from the catalogs, the shared page frames, domain language) and list deviations as minors.* Writes `docs/reviews/ST-NNN-acceptance.md`.
+**Domain lane.** Push the branch (`git push -u origin st-NNN-<slug>`) so a preview deployment exists, when the project
+has one (`review.preview` in `.claude/project.json`: `vercel`, `netlify`, … – use the provider's MCP or CLI, or the
+pull request's preview comment). Otherwise there is no preview and the reviewers work from the code.
+
+Pick the lane from the **diff**, not from a size label:
+
+**Light lane** – all of these hold: the diff is texts, layout, styles, links or docs; no command or route added or
+changed; no input handling (no request handler, form action); no migration; no new dependency.
+- Only `acceptance-tester` – task: story ID, base ref, the preview URL (if known), and: *also check the diff briefly
+  against the engineering conventions (texts from the catalogs, the shared page frames, domain language) and list
+  deviations as minors.* Writes `docs/reviews/ST-NNN-acceptance.md`.
 - No `code-reviewer`, no extra code or security pass.
 
 **Normal lane** – everything else. Start in **one** message:
 - `code-reviewer` – task: story ID, base ref, the context pack command. Writes `docs/reviews/ST-NNN-code-review.md`.
 - `acceptance-tester` – task: story ID, base ref, the preview URL (if known). Writes `docs/reviews/ST-NNN-acceptance.md`.
-- Only for size **L/XL** or a story that changes the command layer or other shared platform code: ask the `code-reviewer` for a second, bug-focused pass over the diff.
-- Only when the **diff** touches input handling, login/roles/session, uploads or files, or security headers/CSP: ask the `code-reviewer` for a security-focused pass.
+- Only when the **diff** touches the command layer or other shared platform code: ask the `code-reviewer` for a
+  second, bug-focused pass over the diff.
+- Only when the **diff** touches input handling, login/roles/session, uploads or files, or security headers/CSP: ask
+  the `code-reviewer` for a security-focused pass.
 
-Say which lane you picked and why in one line.
+Both reviewers report findings and never create stories. A finding is **fixed in this story** or becomes an open
+question to the developer (step 6) – there is no follow-up ticket.
 
-Tell the reviewers the follow-up hurdle below, so they grade findings with it in mind.
+Say which lane you picked and why in one line.
 
 ## 6. Refactor
-- Fix all blockers and majors **inside this story**, and the minors you agree with; say which minors you skip and why. Where a finding offers options, apply the recommended one without asking; ask only when no option is recommended or a follow-up story is at stake.
-- **Follow-up hurdle** – a finding becomes a new story only if all of these hold:
-  1. it is a security or data-loss risk, or it blocks a *named* upcoming story;
-  2. it cannot be fixed in this story within about an hour;
-  3. no existing story can take it (check the stories that will first touch that code – prefer adding a checklist item there, via `requirements-engineer`, over a new story).
-  Otherwise it stays a line in the review file ("skipped minor" or "revisit when …") – no story. Say for each follow-up why it passes the hurdle.
-- Follow-ups that pass: delegate to `requirements-engineer` as new tech-task stories (`status: draft`, label `follow-up`), referencing the review file. They go through `/review-stories` like any story.
-- **Foundation just in time**: technical groundwork goes into the first story that needs it, not into a separate tech task ahead of the domain stories – a `must` tech task with met dependencies jumps ahead of every domain story in the backlog order.
-- Refactor only with green tests; the tests must not change unless they were wrong (then say so). Run
-  `affected.ts` for the touched packages, then `node .claude/skills/implement/scripts/verify.ts` again (without
-  `--e2e`) plus the browser specs the refactor touched – see step 4.
-
-## 7. Acceptance and merge → user checkpoint
-The **acceptance tester's verdict is the acceptance**: the story is `done` in the pull request, so the user only merges.
-1. After the refactor, check the verdict in `docs/reviews/ST-NNN-acceptance.md`. `accepted` or `accepted with remarks` → continue. `not accepted` → fix the gaps in the story and run the `acceptance-tester` again, until it accepts. Only when something goes badly wrong – the verdict stays `not accepted` after a second round, a scenario can't be met as written, the preview shows a defect the tester couldn't see – ask the user, the way *When the story is wrong* describes.
-2. `node .claude/skills/implement/scripts/story-status.ts ST-NNN done` – refuses unless every scenario has its test (story) or every checklist item is ticked (spike/tech task) and all dependencies are done. Commit `ST-NNN: done`, push.
+- Fix all blockers and majors **inside this story**, and the minors you agree with; say which minors you skip and why.
+  Where a finding offers options, apply the recommended one without asking; ask only when no option is recommended.
+- **No follow-up stories from reviews.** A finding that is too large for this story is either:
+  1. a **question to the developer** in the review file and in the wrap-up (with evidence and options), or
+  2. a line in `## Out of Scope` / a row in `OPEN_QUESTIONS.md` when it is a real decision for the user.
+  Only the main session and the user decide whether it becomes a new story; the reviewers never do.
+- Refactor only with green tests; the tests must not change unless they were wrong (then say so). Run `affected.ts`
+  for the touched packages, then `node .claude/skills/implement/scripts/verify.ts` again (without `--e2e`) plus the
+  browser specs the refactor touched – see step 4.
+
+## 7. Done, acceptance and merge → user checkpoint
+
+**Fast lane:** tick the last checklist item, then
+`node .claude/skills/implement/scripts/story-status.ts ST-NNN done` (it refuses while a checklist item is open).
+Commit `ST-NNN: done`, push, open the pull request.
+
+**Domain lane:** the **acceptance tester's verdict is the acceptance**: the story is `done` in the pull request, so
+the user only merges.
+1. After the refactor, check the verdict in `docs/reviews/ST-NNN-acceptance.md`. `accepted` or `accepted with
+   remarks` → continue. `not accepted` → fix the gaps in the story and run the `acceptance-tester` again, until it
+   accepts. Only when something goes badly wrong – the verdict stays `not accepted` after a second round, a scenario
+   can't be met as written, the preview shows a defect the tester couldn't see – ask the user, the way *When the story
+   is wrong* describes.
+2. `node .claude/skills/implement/scripts/story-status.ts ST-NNN done` – refuses unless every scenario has its test
+   (domain) or every checklist item is ticked (chore/task/tech task/spike) and all dependencies are done. Commit
+   `ST-NNN: done`, push.
    - GitHub: the status change closes the linked issue.
-   - Jira: `story-status.ts` prints the transition it could not make (MCP is agent-only). Run `jira_get_transitions` +
-     `jira_transition_issue` on the printed key, then push the story body once (`/backlog-sync push`).
-3. Open a pull request: title `ST-NNN: <story title>`, body = the scenarios as a checklist, links to the story and both review files, the acceptance verdict, the preview URL, remaining minors, and anything the user must approve (a conventions change). (No `gh` CLI, or it isn't authenticated: push and give the user the compare URL `git push` prints.)
-4. **The user merges** – on the preview if they want to look first. Afterwards: back to the default branch and `git pull`.
+   - Jira: `story-status.ts` prints the transition it could not make (MCP is agent-only). Run
+     `jira_get_transitions` + `jira_transition_issue` on the printed key, then push the story body once
+     (`/backlog-sync push`).
+
+**Both lanes – the pull request:**
+3. Title `ST-NNN: <story title>`, body = the scenarios as a checklist (domain) or the task checklist (fast lane),
+   links to the story and the review files (if any), the acceptance verdict (domain), the preview URL, remaining
+   minors/questions, and anything the user must approve (a conventions change). (No `gh` CLI, or it isn't
+   authenticated: push and give the user the compare URL `git push` prints.)
+4. **The user merges** – on the preview if they want to look first. Afterwards: back to the default branch and
+   `git pull`.
 
 ## 8. Wrap-up
-Summarize in a few lines: scenarios implemented, review findings fixed/skipped, follow-ups created, glossary/ADR changes. Then:
-- Suggest `/improve-codebase-architecture` after the foundation stories, when a bounded context is complete, or about every 8–10 done stories.
-- Name the next story (`node .claude/skills/implement/scripts/next-story.ts`) and tell the user to start it in a fresh session (`/new`, then `/implement`): every turn re-reads the whole session, so a second story in the same one costs several times the first.
+Summarize in a few lines: lane taken, scenarios implemented or task completed, review findings fixed/skipped, open
+questions handed to the developer, glossary/ADR changes. Then:
+- Suggest `/improve-codebase-architecture` after the foundation stories, when a bounded context is complete, or about
+  every 8–10 done stories.
+- Name the next story (`node .claude/skills/implement/scripts/next-story.ts`) and tell the user to start it in a fresh
+  session (`/new`, then `/implement`): every turn re-reads the whole session, so a second story in the same one costs
+  several times the first.
 
 ## Spikes
 A spike answers its **Question** within its **Timebox** – no test plan, no TDD for throwaway experiments.
-- Before starting, tell the user the timebox and what will be kept (skeleton code that becomes the application gets tests and passes verify).
-- Tick each checklist item in the story file as it is answered; write results where the item says (an ADR's consequences, `OPEN_QUESTIONS.md`). A new decision → ADR with `status: proposed` (architect skill); the user accepts.
+- A UX or state-model spike is a prototype: load the `prototype` skill, keep the question and timebox in the story,
+  and capture the verdict the same way (step 1b).
+- Before starting, tell the user the timebox and what will be kept (skeleton code that becomes the application gets
+  tests and passes verify).
+- Tick each checklist item in the story file as it is answered; write results where the item says (an ADR's
+  consequences, `OPEN_QUESTIONS.md`). A new decision → ADR with `status: proposed` (architect skill); the user accepts.
 - Timebox exhausted → stop, document what is known, and ask the user how to continue.
 - Review: `code-reviewer` only for code that is kept; `acceptance-tester` checks the checklist evidence.
 
 ## When the story is wrong
-Never guess. When a scenario contradicts another story, a rule or an ADR, can't be tested as written, or leaves a decision open:
+Never guess. When a scenario contradicts another story, a rule or an ADR, can't be tested as written, or leaves a
+decision open:
 1. Stop implementing that part. Mark it `[OPEN]` in the story and add a row to `docs/stories/OPEN_QUESTIONS.md`.
-2. `node .claude/skills/implement/scripts/story-status.ts ST-NNN review` and tell the user. The fix goes through discovery: `requirements-engineer` revises the story, `/review-stories` approves it again. Work already done on the branch stays.
-3. New domain term → `CONTEXT.md` (domain-model skill). Architecture deviation → a `proposed` ADR (architect skill). An accepted ADR is never edited; the hooks block it.
+2. `node .claude/skills/implement/scripts/story-status.ts ST-NNN review` and tell the user. The fix goes through
+   discovery in the main session: revise the story, run the spec linter, and let the user approve it again
+   (`/review-stories`). Work already done on the branch stays.
+3. New domain term → `CONTEXT.md` (domain-model skill). Architecture deviation → a `proposed` ADR (architect skill).
+   An accepted ADR is never edited; the hooks block it.
 4. A `done` story is never reopened – a change to finished behaviour is a new story.
 
 ## Foundation stories

package/.claude/skills/implement/scripts/check-scenarios.ts

@@ -36,7 +36,7 @@ for (const [id, scenarios] of superseded) {
 }
 
 for (const [id, s] of stories) {
-  if (only ? id !== only : !["in-progress", "done"].includes(s.meta.status) || s.meta.type !== "story") continue;
+  if (only ? id !== only : !["in-progress", "done"].includes(s.meta.status) || !d.isDomain(s.meta)) continue;
   const { covered, missing: untested } = e.scenarioCoverage(s, titles);
   const missing = untested.filter((sc) => !superseded.get(id)?.has(sc));
   for (const sc of missing) {

package/.claude/skills/implement/scripts/story-context.ts

@@ -40,7 +40,7 @@ const out: string[] = [`# Context pack – ${id}: ${story.meta.title}`, ""];
 
 // Story
 out.push("## Story file", "", `\`${d.rel(story.path)}\``, "", "````markdown", storyText.trimEnd(), "````", "");
-if (story.meta.type === "story") {
+if (d.isDomain(story.meta)) {
   out.push("## Test titles (exact)", "", "Every scenario gets one test with exactly this title:", "");
   for (const sc of e.scenarioTitles(story)) out.push(`- \`${e.testTitle(id, sc)}\``);
   out.push("");

package/.claude/skills/implement/scripts/verify.ts

@@ -70,7 +70,7 @@ for (const s of appSteps.filter((s) => !commands[s] && !scripts[s])) {
 const node = process.execPath;
 const disc = join(here, "..", "..");
 run("events.yaml", node, [join(disc, "event-storming", "scripts", "validate-events.ts")]);
-run("stories", node, [join(disc, "user-stories", "scripts", "validate-stories.ts")]);
+run("stories + spec linter", node, [join(disc, "user-stories", "scripts", "validate-stories.ts")]);
 // The map is generated; staleness is a warning (adoption may not have run yet), not a failed gate.
 run("repository map", node, [join(disc, "adopt", "scripts", "repo-map.ts"), "--check"], true);
 run("path-scoped rules", node, [join(disc, "adopt", "scripts", "rule-doc.ts"), "--check"], true);