kataster 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,31 @@
+---
+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).
+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).
+
+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.

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

@@ -0,0 +1,193 @@
+---
+name: shape
+description: Grill a large idea before it becomes features – frame the problem, decide where it belongs (existing or new bounded context, shared library), map what changes vs. what is new, slice it, and produce a rough cost range with confidence. Creates no stories; ends with a go / slice / spike / discover / park / no-go recommendation.
+disable-model-invocation: true
+argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--dry-run]"
+---
+
+# Shape a large idea
+
+This is the step between an idea and `/feature`. It answers four questions and then stops:
+
+1. **Should we do this at all?** Problem, outcome, fit with the vision, non-goals.
+2. **Where does it belong?** Existing context, new context, shared library, or cross-cutting.
+3. **What does it touch?** What changes, and what is genuinely new.
+4. **What does it roughly cost?** Scope, range, risk, confidence – not a single number.
+
+It creates **no stories**. Stories remain `/feature`'s job, one slice at a time.
+
+## When to use it
+
+Use `/shape` when the idea is larger than one feature: it crosses contexts, needs a new context or service, a
+migration, an integration, or the question "should we, and what does it cost?" is still open. A normal story goes
+straight to `/feature`; don't turn this into ceremony.
+
+A **new service in an existing monorepo** is not greenfield. It inherits the stack, the shared packages, the
+deployment and the identity model – treat those as constraints, not as a blank page.
+
+## 0. Intake and mode
+
+A reference (`ST-NNN`, `#123`, `PROJ-123`, URL) is resolved with the read-only intake:
+
+```bash
+node .claude/skills/feature/scripts/intake.ts <reference> --json
+# Jira: fetch the issue with jira_get_issue, write it as JSON, then
+node .claude/skills/feature/scripts/intake.ts PROJ-123 --from <issue.json> --json
+```
+
+Summarize the source in 3–5 lines and have the user confirm it. A ticket is **evidence, not a specification**.
+
+`--dry-run` – or the user saying "just walk me through it" – means: grill, show the brief in the conversation,
+write **nothing**. Without it, write the artifact only after the user confirms the summary.
+
+## 1. Read and scan
+
+Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`,
+`docs/architecture/data-model.md`, `docs/architecture/repo-map.md`/`.json`, `docs/engineering/conventions.md`,
+`docs/adr/`, `docs/stories/BACKLOG.md`, `docs/product/ux-guidelines.md`.
+
+Also scan the **configuration and integration points** for systems that already own the data the idea is about:
+`.env.example`, `configuration.ts`, config DTOs, API clients, external ids in entities. A name that appears only
+there – a store, an ERP, a marketplace – is evidence of a system the brief must place. Report what you found and
+what it implies; do not turn a config key into an architectural decision.
+
+If an analogue exists (a sibling service the idea resembles), use it as evidence. If it is large and not adopted,
+delegate one `repo-analyst` lens with a clear task instead of reading all of it yourself. Its model is evidence,
+**never** the new context's model.
+
+Three starting points:
+
+- **Domain model exists** (adopted, or after `/bootstrap`): full placement, impact and cost.
+- **No domain model**: frame and slice are still useful; placement stays `unknown`; recommend `/bootstrap` or
+  `/adopt`. Do not invent contexts from the idea.
+- **Partially adopted / an analogue exists**: use the sibling's model where it exists and its code/config where it
+  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
+
+Call the `grilling` skill. The frontier:
+
+- Which problem, for which user group, and why now?
+- What is the observable outcome, and how would we know it worked?
+- Must / should / could / won't – what ships first, what is explicitly out?
+- Does it fit `vision.md`, or does it change the vision? A vision change is the user's decision.
+- What is the cost of **not** doing it – opportunity or fear?
+- Constraints: deadline, regulation, budget, team, existing commitments.
+- At least one non-goal: what this initiative will not become.
+
+Don't move on before the user confirms a shared understanding.
+
+## 3. Place – architect lens
+
+Call the `architect` skill (and `domain-model` where the language is unclear). For each capability:
+
+| If … | Then |
+|---|---|
+| same language, same invariants, additive change | **existing context** |
+| a term means something else, or a new invariant must be immediately consistent | **new context** |
+| different rate of change, team, regulation or external model | **new context** |
+| pure logic used by two or more contexts, no lifecycle of its own | **shared library** |
+| notifications, audit, auth, files – a generic capability | prefer an **existing generic context** over a new one |
+
+A new **service** is not automatically a new **domain**, and a new domain is not automatically a new service.
+Separate contexts can share infrastructure packages; they must not share a domain model just because the words
+look alike. Same word, different meaning (Product as dish vs. Product as sellable variant) is the classic reason
+to split.
+
+Produce a recommendation **with at least one alternative and its consequence**, plus a confidence:
+
+> Reuse `BC-Delivery` for rescheduling (cheap, but the aggregate grows) vs. a new `BC-Delivery-Planning` (cleaner
+> consistency boundary, one more integration). Recommendation: existing context for slice 1, revisit if carriers
+> get their own scheduling model.
+
+The user decides.
+
+## 4. Impact – lead-dev lens
+
+Split the answer into **change** and **build new**. Leave nothing implicit.
+
+| Dimension | Questions | Evidence |
+|---|---|---|
+| Domain | which aggregates, events, commands, policies, read models? new or changed? | `events.yaml` (IDs, counts) |
+| Code | which packages and consumers? which new packages? | `repo-map`, dependency edges |
+| Interfaces | screens/forms/flows, API endpoints, jobs, webhooks, integrations | `ux-guidelines`, conventions |
+| Data | schema change, migration, backfill, retention, reporting | `data-model.md`, schema |
+| Rules | boundaries (`boundaries.yaml`), permissions, checks (`checks.yaml`) | architecture checks |
+| Tests | which seams – command, policy, read model, page? | seam catalog |
+| Ops | config, deployment, monitoring, support | profile, ADRs |
+
+## 5. Slice
+
+Propose 2–5 independently valuable slices, walking skeleton first. Each slice should be a `/feature` run, not a
+project. For each: outcome, contexts touched, dependencies, rough size, confidence.
+
+If the idea cannot be sliced, say so – that is a finding, not a failure of the format.
+
+## 6. Cost
+
+Never one number. Give **scope**, **range** and **risk**, plus the basis.
+
+- **Scope:** number of slices and stories, with sizes (XS–XL). The most defensible unit the toolkit has.
+- **Range:** e.g. "3–5 stories, mostly S/M" or "2–4 weeks with one developer". Person-days only if the user has a
+  calibration ("1 M ≈ 3 days"); otherwise keep story sizes.
+- **Risk:** what could blow the estimate up – unknown integration, migration, compliance, missing language.
+- **Confidence:** low/medium/high, and **what would raise it** (spike, prototype, measurement, talking to the
+  carrier).
+- **Basis:** the counts behind the estimate (e.g. 1 new command, 1 event, 1 policy, 1 read model, 1 page, 1
+  migration, 2 packages, 1 integration).
+- **Analogue:** if a similar service exists, use it as the calibration anchor – modules, LOC, endpoints, entities,
+  specs, and which parts are domain-specific vs. generic. Say what can be reused and what is genuinely new. The
+  analogue is evidence, not a template; a copy is not automatically the right design.
+
+Rules: an unknown is a line in the brief, not a silent +20 %. A spike is a cost, not a gap – give it a question and
+a timebox. Estimate the **delta** to today's system, not the whole system. Without evidence, say `unknown` and
+recommend discovery.
+
+## 7. Decide and write
+
+End with exactly one recommendation:
+
+`go` · `go with slice 1` · `spike first` · `needs discovery (/bootstrap or /adopt)` · `park` · `no-go`
+
+The user decides. Write `docs/product/initiatives/<slug>.md` after the user confirms the summary of steps 2–6.
+Set `status: proposed`; only the user sets `accepted`. On handoff, set `promoted: <slug>` and send the first slice
+to `/feature`. **Do not create stories here and do not touch `docs/stories/`.**
+
+With `--dry-run`, print the same brief in the conversation and write no file.
+
+### Artifact
+
+```markdown
+---
+status: proposed          # proposed | accepted | parked | rejected
+created: 2026-10-31
+source: PROJ-123          # optional
+promoted: ""              # feature:<slug> once slices are handed to /feature
+---
+
+# Initiative: <title>
+
+## Problem & outcome
+## Fit with the vision
+## Placement
+| Capability | Context | New/existing | Why | Confidence |
+## Impact – change vs. build new
+| Dimension | Change | New | Evidence |
+## Slices
+1. …
+## Rough cost
+| Currency | Estimate | Confidence | Basis |
+## Risks & open questions
+## Recommendation
+```
+
+## Guardrails
+
+- The brief is a proposal. The user sets `accepted`.
+- Do not let the estimate become a commitment. It is a range with a basis.
+- Every brief ends in a recommendation; do not use `/shape` to avoid a decision.
+- Do not turn initiatives into a shadow backlog. They have no `ready`/`done`; only stories do.
+- Do not write an artifact when the user only wants to test the method.
+- Keep the artifact project-neutral except for the project's own terms from `CONTEXT.md`.
+- Never present an analogue's domain model as the new context's model.

package/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle: consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification: "user can checkout with valid cart" tells you exactly what capability exists, and it survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams: where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user – the seam catalog in `docs/engineering/conventions.md` is confirmed already, so only a seam outside it goes to the user. No test is written at an unconfirmed seam. You can't test everything, so agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?" Give each proposed seam a one-line note on what it catches and what it misses.
+
+When the shape of that interface is itself in question (how deep the module is, where the seam belongs, what the interface should expose), call the `skill` tool with `codebase-design` for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
+
+## Anti-patterns
+
+- **Implementation-coupled**: mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological**: the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth: a known-good literal, a worked example, the spec.
+- **Horizontal slicing**: writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead: one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (the review and refactor steps of `/implement`), not the red → green implementation cycle.

package/.claude/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/.claude/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

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

@@ -0,0 +1,138 @@
+---
+name: user-stories
+description: Rules, format and splitting patterns for user stories, spikes and tech tasks in docs/stories/ – frontmatter, INVEST, Gherkin, status workflow, and the local mirror when a Jira or GitHub tracker is configured.
+---
+
+# User Stories
+
+The backlog is **local by default**: every story is a Markdown file in `docs/stories/`, and there is no external
+issue tracker. With `backlog.provider` set to `github` or `jira` in `.claude/project.json`, the tracker is the source
+of truth and `docs/stories/` is its local mirror – the `backlog` skill owns the sync. In both cases the story file is
+the artifact this skill describes, and `docs/stories/BACKLOG.md` is generated from it by a hook – never edit it
+manually.
+
+## Derivation from the Event Storming
+| Source in `events.yaml` | typically becomes |
+|---|---|
+| Actor + command → event | Story "As a <actor>, I want to <command>, so that <effect>" |
+| Policy (automatic) | Story from the beneficiary's perspective ("… I am notified when …") |
+| Read model | Story about finding/seeing information |
+| Hotspot | Spike (question + timebox) or `[OPEN]` in the story |
+| External system | Story or tech task for the integration |
+
+Every story links the affected events (`events: [EVT-…]`). Commands without a story = gap → report it.
+
+## File & Frontmatter
+File: `docs/stories/ST-NNN-short-title.md` (three-digit number, consecutive, never reused).
+Template: `templates/story-template.md`. Schema: `schema/story.schema.json`.
+
+| Field | Required | Who sets it |
+|---|---|---|
+| `id`, `title`, `type`, `context`, `events` | yes | requirements-engineer |
+| `priority` (`must/should/could/wont`) | yes | product-owner (initially `should`) |
+| `size` (`XS–XL`), `risk`, `depends_on` | before `ready` | lead-dev |
+| `labels` | no | anyone (lowercase, e.g. `mvp`, `feature:<slug>`) |
+| `status` | yes | see workflow |
+| `external` | with a tracker | backlog sync – never by hand |
+
+With `backlog.provider` = `github` or `jira`, `external` holds the tracker key (`external.key`) and URL. The sync writes
+it; a story must have it before it reaches `ready`. `ST-NNN` stays the stable id – never renumber a story to follow an
+issue key, and never use a label that starts with the management prefix (`kataster-` by default).
+
+**No implementation foundation inside a domain story** (user, 2026-10-01). A story describes behaviour a person
+can observe; technical groundwork that several stories need is its own **tech task**, with its own `depends_on`.
+A checklist of files to create, layers to convert or configs to set is an implementation plan, not acceptance
+criteria – it is neither the user's language nor a testable outcome, and it hides the real size of the story.
+*Why this is a rule:* a story once carried a seven-item checklist that converted **every command built so far** to an
+event catalogue. That made an M story an L, put a retrofit nine dependencies deep, and the cost grew with every
+command built before it. The grooming pulled it out as its own tech task and the story went back to M.
+The exception is a tech task or a spike – there a checklist *is* the acceptance criteria.
+
+**The `ui` label** marks every story with a frontend part – a screen, a form, a flow a person walks through.
+`/review-stories` and `/groom-backlog` route those to the `ux-designer`, so a missing label means a story nobody
+reviews from that side. What such a story has to say about the interface (and what it must not) is in the
+`ux-design` skill; the decisions it is measured against are `docs/product/ux-guidelines.md`.
+
+## Backlog Order
+
+`docs/stories/BACKLOG.md` is generated (`scripts/render-backlog.ts`) and the order is **derived on every render,
+never stored**. `backlogOrder` in `.claude/lib/discovery.ts` sorts:
+
+1. by `priority` – `must`, `should`, `could`, `wont`;
+2. within the same priority **by story ID, ascending**;
+3. then dependencies first – a story that a listed story depends on is pulled in front of it.
+
+What follows from that, and has caught us out before (story review 2026-09-29):
+
+- **Numbers decide within a priority.** A story with a higher ID never overtakes a lower one, so a new tech task
+  always lands *behind* the older stories it is meant to precede. Raising it to `must` does not help when those
+  are `must` too.
+- **`depends_on` is the only thing that really moves a story forward** – and it is for real dependencies, not
+  for planning wishes. Do not invent one to force an order.
+- **So say it out loud when a story is built out of turn**: `/implement ST-NNN` with the ID, never the bare
+  `/implement` (which follows this very order via `next-story.ts`), and record the intended order in the
+  story's Notes so the next person sees why.
+
+There is no script that re-sorts the backlog, because there is nothing to sort – only story files and this rule.
+
+## Status Workflow
+`draft` (in progress) → `review` (finished, waiting for the story review) → `ready` (after user approval; `size` set, no `[OPEN]`) → `in-progress` → `done`.
+
+Discovery ends at `ready`. The engineering workflow (`/implement`) sets `in-progress` and `done` with `node .claude/skills/implement/scripts/story-status.ts`; the validation hook enforces the same rules when the file is edited directly:
+- `in-progress` and `done` need all `depends_on` stories `done`.
+- `done` needs a test titled `ST-NNN: <scenario title>` for every scenario (story), or every checklist item ticked `- [x]` (spike, tech task).
+- A story that turns out wrong during implementation goes from `in-progress` (or `ready`) back to `review`, with `[OPEN]` + an entry in `OPEN_QUESTIONS.md`; it is revised and approved again.
+- `done` is final. A change to finished behaviour is a new story.
+- `superseded` – a story that is not built as written, before it was started: its work was done elsewhere (a direct change, another story), or a new planning replaces it. Set from `draft`, `review` or `ready`, never from `in-progress`. Its first paragraph says where the work went or what replaces it; the file stays as the record other documents link to. Final like `done`, listed in its own section of the backlog and counted in no progress (user, 2026-10-25). Set it with `node .claude/skills/implement/scripts/story-status.ts ST-NNN superseded`.
+
+## Body Structure
+```
+## Story
+As a <role from CONTEXT.md>, I want <goal>, so that <business benefit>.
+
+## Context
+Briefly: trigger, preconditions, business rules – from the command's `rules` **and from the `invariants` of its
+aggregate**. An invariant is stated once, on the aggregate, and a command's `rules` list only what
+it adds beyond them (`docs/domain/events.yaml`). So a command with few rules is not a command with
+few rules to test: read its aggregate's `invariants` and give every one the command can violate its own rejection
+scenario. "A product always has a name, a price and exactly one category" is why
+`CMD-CorrectProduct` needs a scenario for an emptied name, although its `rules` do not mention it.
+
+## Acceptance Criteria
+Scenario: <Happy path>
+  Given …
+  When …
+  Then …
+
+Scenario: <Error or edge case>
+  …
+
+## Out of Scope
+## Open Questions
+```
+Scenario titles are unique within a story and become test titles (`ST-NNN: <scenario title>`). Renaming a scenario of an `in-progress` or `done` story breaks that link – the test must be renamed too (`verify.ts` reports it).
+
+Spikes: `## Question`, `## Timebox`, `## Acceptance Criteria` (checklist `- [ ] …`).
+Tech tasks: `## Task`, `## Acceptance Criteria` (checklist).
+
+## Quality Rules
+- **INVEST**: independent, negotiable, valuable, estimable, small, testable.
+- Gherkin in English (`Given / When / Then / And / But`). At least a happy path + one error/edge case.
+- Scenarios describe **behavior**, not UI details ("clicks the blue button" ✗) and not technology.
+- **At most 10 scenarios** per story – each one is a red → green cycle in `/implement`. Spend them on domain behavior and real rejections. A pattern `docs/product/ux-guidelines.md` already defines (grouping, collapsing, kept choices after a rejection) is a G-number in the Context, tested once where the pattern is built, not restated as scenarios. More left → split (patterns below). The validator warns in `draft` and refuses `review`.
+- Measurable outcomes: "Then the item has the status 'out of order'" instead of "Then it works".
+- Non-functional requirements as concrete scenarios or checklist items with a number.
+- Terms exactly as in the glossary `CONTEXT.md`; never use an `_Avoid_` synonym.
+
+## Splitting Patterns (if larger than M)
+By workflow step · by business rule · happy path first, special cases later · by data variant · by role · "manual first, automated later".
+
+## Validation
+A hook checks every written story automatically and regenerates `BACKLOG.md`. Full check of all stories:
+`node .claude/skills/user-stories/scripts/validate-stories.ts`
+After deleting or renaming story files, regenerate the backlog:
+`node .claude/skills/user-stories/scripts/render-backlog.ts`
+
+With a tracker, validation also refuses a `ready`, `in-progress` or `done` story without `external`, and warns about
+labels reserved for the sync. Pull before validating a mirror that may be stale (`/backlog-sync pull`) and push after
+changing it (`/backlog-sync push`).

package/.claude/skills/user-stories/schema/story.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Story frontmatter (docs/stories/ST-NNN-*.md)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "type", "context", "priority", "status"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^ST-[0-9]{3,}$" },
+    "title": { "type": "string", "minLength": 5, "maxLength": 120 },
+    "type": { "enum": ["story", "spike", "tech-task"] },
+    "context": { "type": "string", "pattern": "^BC-[A-Za-z0-9]+$" },
+    "priority": { "enum": ["must", "should", "could", "wont"] },
+    "size": { "enum": ["XS", "S", "M", "L", "XL", null] },
+    "risk": { "enum": ["low", "medium", "high", null] },
+    "events": {
+      "type": "array", "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^EVT-[A-Za-z0-9]+$" }
+    },
+    "depends_on": {
+      "type": "array", "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^ST-[0-9]{3,}$" }
+    },
+    "labels": {
+      "type": "array", "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9:_-]*$" }
+    },
+    "external": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "key"],
+      "properties": {
+        "provider": { "enum": ["github", "jira"] },
+        "key": { "type": "string", "minLength": 1 },
+        "url": { "type": "string" }
+      }
+    },
+    "status": { "enum": ["draft", "review", "ready", "in-progress", "done", "superseded"] }
+  }
+}

package/.claude/skills/user-stories/scripts/render-backlog.ts

@@ -0,0 +1,4 @@
+/** Regenerates docs/stories/BACKLOG.md from the story files (also after deleting or renaming stories). */
+import * as d from "../../../lib/discovery.ts";
+
+console.log(`Written: ${d.rel(d.writeBacklogMd())}`);

package/.claude/skills/user-stories/scripts/validate-stories.ts

@@ -0,0 +1,13 @@
+/** Validates all stories in docs/stories/ (frontmatter, references, Gherkin, status). Exit 1 on errors. */
+import * as d from "../../../lib/discovery.ts";
+
+const report = new d.Report();
+const stories = d.validateStories(report);
+for (const line of report.lines()) console.log(line);
+if (report.ok) {
+  const byStatus = new Map<string, number>();
+  for (const s of stories.values()) byStatus.set(s.meta.status, (byStatus.get(s.meta.status) ?? 0) + 1);
+  const summary = [...byStatus].map(([st, n]) => `${st}: ${n}`).join(", ");
+  console.log(`OK – ${stories.size} stories` + (summary ? ` (${summary})` : ""));
+}
+process.exit(report.ok ? 0 : 1);

package/.claude/skills/user-stories/templates/story-template.md

@@ -0,0 +1,38 @@
+---
+id: ST-001
+title: Short, domain-level title
+type: story
+context: BC-Example
+priority: should
+size: null
+risk: null
+events: [EVT-Example]
+depends_on: []
+labels: []
+status: draft
+# external: { provider: github|jira, key: "…", url: "…" } – written by /backlog-sync, never by hand
+---
+
+## Story
+As a <role>, I want <goal>, so that <benefit>.
+
+## Context
+<Trigger, preconditions, business rules>
+
+## Acceptance Criteria
+
+Scenario: <Happy path>
+  Given <initial situation>
+  When <action>
+  Then <observable outcome>
+
+Scenario: <Error or edge case>
+  Given <initial situation>
+  When <action>
+  Then <observable outcome>
+
+## Out of Scope
+- …
+
+## Open Questions
+- none