kataster 0.3.0 → 0.4.0

package/.claude/skills/prototype/LOGIC.md

@@ -0,0 +1,101 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking
+buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of
+thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it is one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain
+expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where ..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you are prototyping. One paragraph, at the
+top of the demo (in a visible intro, not just a comment) and in the `README.md`. A logic prototype that answers
+the wrong question is pure waste, so make the question explicit so it can be checked later.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that is answering the question) in a single `<script>` block written as a small,
+pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway;
+this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single
+  value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is
+  part of the question.
+- **A small set of pure functions** over a plain data type. Good when there is no implicit current state, just
+  transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it
+pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the
+other direction. This is what makes the prototype useful past its own lifetime: once the question is answered,
+the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click
+and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language** from `CONTEXT.md`, not code: buttons and
+state read like the business, not like the reducer. Explain in plain words what is happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON
+   dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call
+   out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any
+   order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language
+   description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered
+   **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and
+   moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same
+   way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a
+tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no
+gimmicks: nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They will click through the walkthroughs and free-play whenever they
+get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X
+would be different"; those are the bugs in the *idea*, which is the whole point. If they want new actions or a
+new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the
+[SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts
+into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps
+the prototype as a primary source, and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about
+  persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button
+  handlers, it is no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a framework app or a
+  dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The
+  logic module behind it is the bit worth keeping.

package/.claude/skills/prototype/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer one design question – a self-contained HTML file for a logic/state question, or several radically different UI variants switchable in one file. Use when a UX or domain question cannot be settled on paper, and in /feature or /implement when the user asks for a prototype.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape. It is not a first
+draft of the feature: no tests, no persistence, no polish, no production path. The decision it settles is the
+only thing that survives; the code is captured on a throwaway branch and never merged.
+
+## When this is the right tool
+
+Use it when the question is one of these, and the user agrees:
+
+- **"What should this look like?"** – a structural layout choice: three genuinely different information
+  hierarchies, not three colour variants.
+- **"Does this logic / state model feel right?"** – a state machine, a set of rules or a data shape pushed
+  through cases that are hard to reason about on paper.
+- **"How should this flow feel?"** – a sequence a person walks through, where the order and the feedback are
+  the question.
+
+Do **not** prototype a question a guideline, the vision or the domain model already answers. Do not prototype
+polish (colour, spacing, copy), and do not use it to avoid a grilling decision. The grilling comes first; the
+prototype is evidence for one open branch of it.
+
+## Pick a branch
+
+Identify which question is being answered – from the user's prompt, the story, the surrounding code, or by
+asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). One self-contained HTML file with
+  free-play buttons and tabbed guided walkthroughs that push the state model through the awkward cases. A
+  non-developer can drive it.
+- **"What should this look like?"** → [UI.md](UI.md). Several radically different variants in one
+  self-contained HTML file, switchable via a `?variant=` URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts, so getting this wrong wastes the whole prototype. If the
+question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the
+surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of
+the prototype.
+
+## Where it lives
+
+In discovery, the prototype is **standalone**: `docs/prototypes/<slug>/index.html`, written by the
+`ux-designer`, with a short `README.md` next to it (question, branch, variants/scenarios, timebox, verdict).
+No application code, no framework, no build step, no shell. The user opens the file in a browser.
+
+A question that genuinely needs the real application – an existing page, real data, the real header and
+sidebar – is an **in-app prototype**. That is the exception: it is built by the main session during
+`/implement` (see [UI.md](UI.md)), not by the `ux-designer`, and it follows the project's routing convention
+with a clearly marked throwaway route. The same capture rules apply.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** The path or the first line says `PROTOTYPE`. Name
+   it so a casual reader cannot mistake it for production.
+2. **Trivial to run.** Standalone: double-click the HTML file. In-app: one command from the project's task
+   runner. No thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*,
+   not something it depends on. If the question explicitly involves a database, use a scratch database or a
+   local file with a clear "PROTOTYPE, wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype runnable, no abstractions.
+   The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), render the full relevant
+   state so the user can see what changed.
+6. **One question, one timebox.** Write the question at the top, in the user's language, and agree a timebox
+   with the user (one working session is the default). If the timebox expires without an answer, stop and
+   record what is known – a second prototype needs a new question, not more polish.
+7. **Capture the answer, not the code.** Fold the validated decision into the real artifact – the story's
+   `## Context`, `docs/product/ux-guidelines.md` (a G-number when it is a recurring rule) or the domain model.
+   Then capture the prototype itself as a **primary source**: commit `docs/prototypes/<slug>/` on a throwaway
+   branch `prototype/<slug>`, push it only if the user wants to share it, and return to the branch you were
+   on. The branch is never merged. The story carries `Prototype: prototype/<slug> – <question> – <verdict>`.
+
+## How it plugs into the workflow
+
+- **`/feature`** – the UX lens proposes a prototype when the frontier leaves a structural UI, flow or state
+  question. The user decides. `--prototype[=ui|logic]` makes it explicit. The verdict goes to the
+  `ux-designer` (guidelines) and into the story's `## Context` in the main session, before the stories are reviewed.
+- **`/implement`** – only when the user asks (`--prototype`) or a spike's question is a UX/state question. A
+  `ui` story whose screen shape is still open was not `ready`; the prototype settles it, then the story goes
+  back to `review` if its behaviour changed. The engineering rule holds: never decide a story in the code.
+- **The `ux-designer`** owns the skill and builds the standalone prototype. It never writes production code,
+  tests or stories. The main session captures the branch and passes the verdict on.

package/.claude/skills/prototype/UI.md

@@ -0,0 +1,130 @@
+# UI Prototype
+
+Generate **several radically different UI variations** in one self-contained HTML file, switchable from a
+floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then
+throws the rest away.
+
+If the question is about logic/state rather than what something looks like, this is the wrong branch. Use
+[LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes: standalone first
+
+A UI prototype is easier to judge when it butts up against the rest of the app – real header, real sidebar,
+real data, real density. A variant in a vacuum looks fine in isolation. But in discovery there is no app code
+yet, and the `ux-designer` must not write it. So the default is standalone; the in-app shape is the exception.
+
+### Sub-shape A: standalone HTML (default in discovery)
+
+One file, `docs/prototypes/<slug>/index.html`, with inline CSS and JS. No framework, no bundler, no server. It
+opens by double-click and survives being emailed around.
+
+- Use sample data that matches the domain (`CONTEXT.md`), not `foo`/`bar`.
+- Give each variant a clear component name in the file: `VariantA`, `VariantB`, `VariantC`.
+- Keep the page frame realistic: the header, the navigation and the density the real page will have. A blank
+  page hides design problems that a populated one exposes.
+- If the feature will live inside an existing screen, render that screen's frame around the variants.
+
+### Sub-shape B: in-app throwaway route (only in `/implement`)
+
+Only when the question genuinely needs the real application: an existing page, real data, the real header and
+sidebar. The main session builds it, not the `ux-designer`. Follow the project's routing convention; do not
+invent a new top-level structure. Name the route or the file so it is obviously a prototype. Same `?variant=`
+pattern and the same switcher. Never wire it to real mutations; read-only is fine.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise, so cap there.
+
+Write down the plan in one line, at the top of the file and in the `README.md`:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system if the prototype is in-app; plain CSS if it is standalone.
+- A clear component name in the file, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different**: different layout, different information hierarchy, different
+primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's
+wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher in the file:
+
+```js
+// pseudo-code, adapt to the file
+const variant = new URLSearchParams(location.search).get("variant") ?? "A";
+render(
+  variant === "A" ? VariantA(data) :
+  variant === "B" ? VariantB(data) :
+  VariantC(data)
+);
+renderSwitcher(["A", "B", "C"], variant);
+```
+
+For sub-shape B (in-app), keep all the existing data fetching above the switcher; only the rendered subtree
+changes per variant.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow**: cycles to the previous variant (wraps around).
+- **Variant label**: shows the current variant key and, if the variant exports a name, that name too. e.g.
+  `B (Sidebar layout)`.
+- **Right arrow**: cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (`history.replaceState` in a standalone file, the framework's
+  router in-app) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or
+  `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it is obviously not part of the
+  design being evaluated.
+- In-app only: hidden in production builds, gated on `process.env.NODE_ENV !== "production"` or an equivalent
+  check, so a stray prototype merge cannot ship the bar to users. A standalone file never enters the build.
+
+### 5. Hand it over
+
+Surface the file path or the URL (and the `?variant=` keys). The user will flip through whenever they get to
+it. The interesting feedback is usually **"I want the header from B with the sidebar from C"**, which is the
+actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer (which variant and why), then capture the prototype the way the
+[SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch,
+not into main:
+
+- **Standalone**: the decision goes into the story and, when it is a recurring rule, into
+  `docs/product/ux-guidelines.md`. The whole `docs/prototypes/<slug>/` folder goes to `prototype/<slug>`.
+- **In-app**: fold the winner into the existing page; drop the losing variants and the switcher from the story
+  branch. The full set goes to `prototype/<slug>`.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin. Variant
+components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree
+  about structure.
+- **Sharing too much code between variants.** A shared header is fine; a shared layout defeats the point.
+  Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it
+  at a stub: the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype
+  constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/.claude/skills/review-stories/SKILL.md

@@ -1,31 +1,51 @@
 ---
 name: review-stories
-description: Has stories checked in one lead-dev pass (value, build, UX), applies the small fixes and guides the user to approval (status ready).
+description: Runs the deterministic spec linter on finished stories, fixes mechanical gaps, moves green stories to ready-for-human-review and guides the user to approval (status ready). No subagent review pass.
 disable-model-invocation: true
 argument-hint: "[ST-IDs, empty = all with status review]"
 ---
 
 # Story Review
 
-The perspectives of product owner, lead dev and UX were settled with the user in the grilling. This review checks
-that the stories carry them – one pass, not a second discovery (user, 2026-10-26).
+There is no simulated role play. The domain, architecture and testability decisions were made in the grilling and
+the event storming; the **spec linter** now checks mechanically that the story carries them. The user approves; the
+agent does not approve on their behalf.
 
 1. **Selection**: Stories from the invocation arguments, or all with `status: review` in `docs/stories/`. With a
    tracker (`backlog.provider` ≠ `local`), pull first (`/backlog-sync pull`) so the review sees the tracker's state.
    None found → report and stop.
-2. **Delegate once** to `lead-dev` with the full file paths of the stories, the review file path
-   `docs/reviews/YYYY-MM-DD-story-review.md` and the task *story review: all three lenses*. It sets `size`, `risk`,
-   `depends_on` and `priority` and writes the findings into the review file.
-3. **Let the user decide** only what the findings leave open: conflicts with a decision from the grilling, a
-   proposed split, a proposed new story (max. 3 questions at a time, each with a recommended answer). Adopt nothing
-   that changes a grilling decision without consent.
-4. **Apply**:
-   - Small content changes (a scenario, a wording, a Context line, a G-reference) → edit the story yourself.
-   - A split or a restructured story → delegate to `requirements-engineer` (referencing the review file).
-   - With a tracker, push the selected stories that are still unlinked (`/backlog-sync push ST-001 …`) **before**
-     setting `ready` – the push creates the issue and writes `external`; without it the validator refuses `ready`.
-   - Approved stories: `node .claude/skills/implement/scripts/story-status.ts ST-NNN ready` (only if `size` is set
-     and no `[OPEN]` remains – the script checks this). GitHub follows the status change directly; for Jira, run the
-     transition the script prints.
-   - Push the changed and approved stories again so body, labels and status agree in the tracker.
-5. Wrap-up: run `node .claude/skills/user-stories/scripts/validate-stories.ts`, show the status overview and point to `docs/stories/BACKLOG.md` (regenerated automatically), where `ready` stories are queued for the engineering workflow.
+2. **Lint first** – this is the gate, not a suggestion:
+
+   ```bash
+   node .claude/skills/user-stories/scripts/lint-story.ts ST-NNN
+   ```
+
+   Errors are the agent's to fix in the story: a missing `aggregate`/`command`, a command that belongs to another
+   aggregate, events that are not exactly what the command produces, a missing `Given/When/Then`, more than 4
+   scenarios, duplicate titles, a broken reference. Do not weaken a check to get green – if the model is missing the
+   event or aggregate, fix `docs/domain/events.yaml` (event-storming/domain-model skill) first.
+3. **Warnings that matter**: a `ui: true` story with no empty/rejection case, a legacy `type: story`, a scenario that
+   reads like a UX guideline restated. Fix what is clearly right; leave the rest as a note in the review summary.
+   This is not a second discovery – adopt nothing that changes a decision from the grilling without asking.
+4. **Tracker link**: with a tracker, push unlinked stories (`/backlog-sync push ST-001 …`) **before** setting
+   `ready` – the push creates the issue and writes `external`; without it the validator refuses `ready`.
+5. **Linter green → `ready-for-human-review`**:
+
+   ```bash
+   node .claude/skills/implement/scripts/story-status.ts ST-NNN ready-for-human-review
+   ```
+
+   The script validates the file and refuses on any lint error.
+6. **The user approves** – present one short table (ID, title, type, command/aggregate, scenario count, warnings) and
+   ask for approval. On approval:
+
+   ```bash
+   node .claude/skills/implement/scripts/story-status.ts ST-NNN ready
+   ```
+
+   With a tracker, push again so body, labels and status agree. If the user declines, the story goes back to
+   `review` or `draft` with their reason.
+7. **UX on demand only**: a story with `ui: true` may get a component/Figma proposal from the `ux-designer`, but
+   only when the user asks. It is advice, never a gate – do not wait for it.
+8. Wrap-up: run `node .claude/skills/user-stories/scripts/lint-story.ts`, show the status overview and point to
+   `docs/stories/BACKLOG.md` (regenerated automatically), where `ready` stories are queued for engineering.

package/.claude/skills/shape/SKILL.md

@@ -64,7 +64,7 @@ Three starting points:
   does not. Confidence is `medium` at best; say what is inferred. If the sibling is central, recommend
   `/adopt <sibling>` as the first slice before committing to a cost range.
 
-## 2. Frame – product owner lens
+## 2. Frame – product lens
 
 Call the `grilling` skill. The frontier:
 
@@ -103,7 +103,7 @@ Produce a recommendation **with at least one alternative and its consequence**,
 
 The user decides.
 
-## 4. Impact – lead-dev lens
+## 4. Impact – engineering lens
 
 Split the answer into **change** and **build new**. Leave nothing implicit.