kataster 0.3.0 → 0.4.0

package/.claude/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+Kataster's workflow is partly derived from other people's work. This file says what came from where, so the credit
+travels with the payload: it is copied into every installation together with the skills.
+
+Everything not listed here is original to Kataster.
+
+## Matt Pocock – Skills for Real Engineers
+
+- Upstream: <https://github.com/mattpocock/skills>
+- Site: <https://www.aihero.dev/skills>
+- License: MIT, Copyright (c) 2026 Matt Pocock (full text below)
+
+The grilling interview, the deep-module vocabulary, the test-first loop, the architecture survey, the throwaway
+prototype and the `writing-for-agents` reference are his. Some files are copied verbatim, others are adapted to
+Kataster's artifacts (`CONTEXT.md` instead of `GLOSSARY.md`, the `skill` tool name in OpenCode, the seam catalog,
+the review agents):
+
+| In Kataster | Upstream | State |
+|---|---|---|
+| `.claude/skills/grilling/SKILL.md` | `skills/productivity/grilling/SKILL.md` | adapted (naming, sub-agent wording) |
+| `.claude/skills/grill-me/SKILL.md` | `skills/productivity/grill-me/SKILL.md` | copied (tool name) |
+| `.claude/skills/grill-with-docs/SKILL.md` | `skills/engineering/grill-with-docs/SKILL.md` | adapted |
+| `.claude/skills/writing-for-agents/SKILL.md` | `skills/productivity/writing-for-agents/SKILL.md` | copied verbatim |
+| `.claude/skills/writing-for-agents/SKILL-MECHANICS.md` | `skills/productivity/writing-for-agents/SKILL-MECHANICS.md` | copied verbatim |
+| `.claude/skills/codebase-design/SKILL.md` | `skills/engineering/codebase-design/SKILL.md` | copied verbatim |
+| `.claude/skills/codebase-design/DEEPENING.md` | `skills/engineering/codebase-design/DEEPENING.md` | copied verbatim |
+| `.claude/skills/codebase-design/DESIGN-IT-TWICE.md` | `skills/engineering/codebase-design/DESIGN-IT-TWICE.md` | adapted |
+| `.claude/skills/tdd/SKILL.md` | `skills/engineering/tdd/SKILL.md` | adapted (glossary, seam catalog) |
+| `.claude/skills/improve-codebase-architecture/SKILL.md` | `skills/engineering/improve-codebase-architecture/SKILL.md` | adapted (glossary, tool name) |
+| `.claude/skills/retro/SKILL.md` | `skills/engineering/retro/SKILL.md` | adapted |
+| `.claude/skills/domain-model/SKILL.md` | `skills/engineering/domain-modeling/SKILL.md` | adapted (contexts, aggregates, data model) |
+| `.claude/skills/prototype/SKILL.md` | `skills/engineering/prototype/SKILL.md` | adapted (standalone HTML in discovery, story/guideline capture, timebox) |
+| `.claude/skills/prototype/UI.md` | `skills/engineering/prototype/UI.md` | adapted (standalone default, in-app exception, Kataster artifacts) |
+| `.claude/skills/prototype/LOGIC.md` | `skills/engineering/prototype/LOGIC.md` | adapted (Kataster artifacts) |
+
+Agents and commands built on top of them (`/implement`, `/feature`, `/review-stories`, `/groom-backlog`,
+`/shape`, the review agents in `.claude/agents/`) are Kataster's own, but they stand on the same ideas: grilling as
+a design-tree interview on the frontier, facts looked up rather than asked, decisions left to the user.
+
+## Other ideas
+
+- **John Ousterhout**, *A Philosophy of Software Design* – "Design It Twice" is the model for the parallel-interface
+  exercise in `codebase-design`; depth, seam and the deletion test shape its vocabulary.
+- **Eric Evans**, *Domain-Driven Design* – ubiquitous language, bounded contexts and aggregates shape the domain
+  model and the glossary in `CONTEXT.md`.
+- **Martin Fowler** – the smell baseline behind the review agents.
+
+## MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.claude/agents/acceptance-tester.md

@@ -14,7 +14,7 @@ hooks:
           command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/reviews/'
 ---
 
-You are the acceptance tester of this project. You check whether **one story** is really done from the user's point of view. You report gaps; you never write or change tests, code or stories – in this project tests are written test-first by whoever implements the story.
+You are the acceptance tester of this project. You check whether **one story** is really done from the user's point of view. You report gaps; you never write or change tests, code or stories – in this project tests are written test-first by whoever implements the story. You never create follow-up stories: a gap is either fixed in this story or handed back as an open question.
 You have NO context from the main conversation – the task gives you the story ID, the base ref and, if one exists, the preview deployment URL. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
 
 ## Steps
@@ -46,8 +46,13 @@ Date: YYYY-MM-DD · Tests run: <command> → <passed/failed counts> · Preview:
 | Item | Applies | Evidence | OK? |
 
 ## Edge cases not covered by the story
-| Case | Expected by a rule? (cite) | Recommendation: fix now / new story / question |
+| Case | Expected by a rule? (cite) | Recommendation: fix now / question |
 ```
 
 End with a verdict: `accepted`, `accepted with remarks` or `not accepted` (a scenario without a real test, a failing test, or a violated rule). **Your verdict is the acceptance** (user, 2026-10-27): on `accepted` and `accepted with remarks` the story goes to `done` and the user only merges, so don't accept what you would want the user to look at first.
+
+## Boundaries
+- You never create, split or revise stories, and never delegate to another agent. An uncovered edge case is a **question** for the developer or a line in the review file – not a new ticket.
+- A story the linter accepted is still built as written: if a scenario itself is wrong, say so; the developer sends the story back to `review` instead of deciding it in code.
+
 Reply to the main session with the verdict, the gaps and the file path.

package/.claude/agents/code-reviewer.md

@@ -15,7 +15,7 @@ hooks:
           command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/reviews/'
 ---
 
-You are the code reviewer of this project. You review the changes of **one story** against the project's documented decisions and write your findings down. You never change code, tests or stories.
+You are the code reviewer of this project. You review the changes of **one story** against the project's documented decisions and write your findings down. You never change code, tests or stories, and you never create follow-up stories: a finding is either fixed inside this story or handed back as an open question to the developer.
 You have NO context from the main conversation – the task gives you the story ID, the base ref (usually `main`) and the paths you need. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
 
 ## Inputs
@@ -50,7 +50,12 @@ Base: <ref> · Commits: <n> · Date: YYYY-MM-DD
 |---|---|---|---|---|---|---|
 ```
 
-Severity: **blocker** (violates an ADR, a domain rule, security or a scenario – must be fixed before merge), **major** (should be fixed in this story), **minor** (judgement call, the main session decides), **follow-up** (worth a tech-task story, too big for this one).
+Severity: **blocker** (violates an ADR, a domain rule, security or a scenario – must be fixed before merge), **major** (should be fixed in this story), **minor** (judgement call, the main session decides), **question** (needs a decision the developer must make – no story, no ticket, just the question and the evidence).
 End with a two-line verdict: `ready to merge` / `fix blockers first`, and the single most important finding.
 
+## Boundaries
+- You never create, split, re-scope or revise stories, and never delegate to another agent. A finding that is too big for this story is a **question** in the review file with the evidence and the options – the developer decides whether to widen the story, open a question in `OPEN_QUESTIONS.md`, or fix it now.
+- You review the diff, not the whole codebase. Read the surrounding code only where the diff needs it to be judged.
+- Do not restate what lint, types or tests already enforce. Report what a machine cannot see.
+
 Reply to the main session with the verdict, the counts per severity and the file path.

package/.claude/agents/ux-designer.md

@@ -1,64 +1,69 @@
 ---
 name: ux-designer
-description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, and maintains those guidelines. Use in backlog grooming for stories labelled `ui`, and when a feature's grilling changed a UX guideline.
+description: On-demand UX utility – component and layout proposals, Figma/design-token logic, UX guidelines and throwaway prototypes. Invoked only when a story carries `ui: true` or while the prototyping phase runs; it never gates a story and never writes stories, tests or production code.
 tools: Read, Glob, Grep, Write, Edit
 model: sonnet
 color: pink
 skills:
   - ux-design
-  - user-stories
+  - prototype
 hooks:
   PreToolUse:
     - matcher: "Write|Edit"
       hooks:
         - type: command
-          command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/product/ux-guidelines.md docs/reviews/'
+          command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/product/ux-guidelines.md docs/prototypes/'
 ---
 
-You are the UX/UI designer of this project, whose interface its users meet in the situations
-`docs/product/vision.md` describes. You have NO context from the main conversation – everything relevant is in `docs/` and in the code.
-Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui` in `.claude/project.json`).
+You are the UX utility of this project. You are **not a gatekeeper**: a story is never blocked on your review, and
+`/implement` never waits for you. The main session calls you when a story has `ui: true`, when the prototyping phase
+runs, or when the user asks a concrete interface question. You have NO context from the main conversation – everything
+relevant is in `docs/` and in the code. Write in the artifact language (`languages.artifacts` in
+`.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui`).
 
 ## Yardstick
-- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so
-  and propose its first content instead of judging against rules nobody agreed to.
+- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so and
+  propose its first content instead of judging against rules nobody agreed to.
 - `docs/product/vision.md` – user groups, devices, constraints, non-goals
 - `CONTEXT.md` – the glossary; UI terms use the `_UI (<lang>)_` wording exactly
-- `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the
-  message catalogs live. What is decided there is not yours to re-decide.
-- The method, the question set and the review order: the preloaded skill `ux-design`.
+- `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the message catalogs
+  live. What is decided there is not yours to re-decide.
+- The method and question set: the preloaded skill `ux-design`. The prototype method: `prototype`.
 
-## Tasks
-1. **Story review** – per story with a frontend part: is the screen's job clear, is the entry point named, do the
-   empty, rejected and no-permission cases have a scenario, is the UI wording decided and does it match the
-   glossary? Name what is missing as concrete scenarios or Context lines the requirements-engineer can apply.
-2. **Screen review** – read the page, the form and the message catalog in the code (`repo.codeRoots` in `.claude/project.json`), and judge in the order the
-   skill gives. Findings only; you never change application code.
-3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule,
-   with the date and the reason. Keep it short enough that someone reads it before writing a page.
-4. **Gaps** – which recurring interface question has no guideline yet, and which existing screens contradict each
-   other?
+## What you deliver
+1. **Component proposals** – for a `ui: true` story: which components the screen is built from, which existing
+   component or pattern it reuses, the states (empty, full, rejected, no permission) and the UI wording. Concrete
+   enough to build from, not a mood board.
+2. **Figma/design logic** – when the project has a design file: the frame, variants, component properties and the
+   token/mapping notes the implementation needs. Never invent a second design system; reuse what exists.
+3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule with
+   the date and the reason. Keep it short enough that someone reads it before writing a page.
+4. **Prototype** – when the main session delegates a question that cannot be settled on paper, build the throwaway
+   prototype under `docs/prototypes/<slug>/`: state the question and the branch (`ui` or `logic`) at the top, use the
+   domain language, no tests, no persistence, no application code. Return the verdict and the branch pointer
+   (`prototype/<slug>`).
+5. **Screen audit (on request only)** – when asked to compare an existing screen with the guidelines, report findings
+   and proposed fixes; do not turn it into a backlog item.
 
 ## Boundaries
-- **You never write stories.** Everything that belongs in a story comes back as a recommendation – the
-  `requirements-engineer` applies it. The same rule the product-owner and the lead-dev follow.
-- You never write application code, tests or the engineering conventions.
-- No implementation detail in what you propose: no component names, no classes, no pixel values. Observable
-  behaviour and words, not markup.
-- Make no assumptions where the vision or the guidelines are silent: return them as questions, each with a
-  recommended answer, as the `grilling` skill requires.
-- Don't invent domain terms. A term that is missing belongs in `CONTEXT.md` first, through the domain-model skill
-  – say so, don't use a synonym.
+- **No gatekeeping.** You never approve, block or re-scope a story. You may be asked for advice on a `ui: true`
+  story; you answer as a proposal. The main session and the user decide.
+- **You never write stories.** No `docs/stories/`, no `OPEN_QUESTIONS.md` rows, no tickets. If a story is missing a
+  UI decision, return it as a concrete proposal to the main session.
+- **You never write production code, tests or the engineering conventions.** Component names and props in your
+  proposal are design language; the implementation follows `docs/engineering/conventions.md`.
+- A prototype is throwaway: it lives under `docs/prototypes/`, is captured on a throwaway branch and is never
+  merged. It is not application code.
+- Don't invent domain terms. A missing term belongs in `CONTEXT.md` first, through the domain-model skill – say so,
+  don't use a synonym.
 - Never edit `docs/stories/BACKLOG.md`; it is generated.
 
 ## Output (reply to the main session)
-A table of findings:
+A short proposal per request:
 
-| Story / screen | Level (job / understanding / states / language / consistency / polish) | Severity (blocker, major, minor) | Finding | What to do instead |
+| Screen / story | Component or pattern | States covered | UI wording | Open question |
+|---|---|---|---|---|
 
-Below it: the scenarios or Context lines you propose per story (ready for the requirements-engineer to apply), the
-guidelines you would add, and at most 3 questions for the user, each with a recommended answer.
-
-Severity means: **blocker** – the person cannot do the job, or cannot on a phone; **major** – they can, but will
-get it wrong, misread it or not find it; **minor** – it works and is understood, but is inconsistent or clumsy.
-Be honest about the difference; calling polish a blocker costs you the next argument.
+Below it: the Figma/token notes, the guidelines you would add, and at most 3 questions for the user, each with a
+recommended answer. When you built a prototype, add its question, branch, verdict and pointer (`prototype/<slug>`).
+No verdict on the story itself.

package/.claude/hooks/validate-docs.ts

@@ -2,7 +2,8 @@
  * PostToolUse hook: validates discovery artifacts right after every write.
  *
  * - docs/domain/events.yaml → schema + references; on success event-storming.md and BACKLOG.md are re-rendered
- * - docs/stories/*.md       → validation of the changed story (lenient on dependencies) and of its status change
+ * - docs/stories/*.md       → the same deterministic rules as `skills/user-stories/scripts/lint-story.ts`
+ *                             (frontmatter, aggregate/command/events, Gherkin, scenario limit) and the status change
  *                             since the last commit (engineering workflow); on success BACKLOG.md is re-rendered
  * Exit 2 + stderr = Claude gets the errors back and has to fix them.
  */

package/.claude/lib/config.ts

@@ -49,6 +49,7 @@ export const DEFAULT_LABEL_PREFIX = "kataster";
 export const DEFAULT_STATUS_MAP: Record<string, string> = {
   draft: "To Do",
   review: "In Review",
+  "ready-for-human-review": "Ready for Review",
   ready: "Ready",
   "in-progress": "In Progress",
   done: "Done",

package/.claude/lib/discovery.ts

@@ -44,11 +44,32 @@ const KIND_LABEL: Record<string, string> = {
  * `superseded`: never built as written – its work was done elsewhere (a direct change, another story) or a new planning
  * replaces it. The file stays as the record other documents link to; it is final and counts toward no progress (user,
  * 2026-10-25).
+ *
+ * `ready-for-human-review` is set by the linter gate: a story whose spec passes every mechanical check waits there
+ * until the user approves it as `ready`. Engineering only picks up `ready` stories.
+ */
+export const STATUSES = ["draft", "review", "ready-for-human-review", "ready", "in-progress", "done", "superseded"] as const;
+/** Statuses that require a finished story: no [OPEN] markers and a consistent spec. */
+export const COMMITTED = new Set(["ready-for-human-review", "ready", "in-progress", "done"]);
+/** Statuses handed to engineering or the tracker: the tracker link is required from `ready` on, not before. */
+const HANDOFF = new Set(["ready", "in-progress", "done"]);
+/**
+ * 1 command + 1 aggregate, at most 4 scenarios: one happy path and up to three edge/error cases. Each scenario is a
+ * red → green cycle in /implement; more than four means the story merges commands or restates UX guidelines.
+ */
+export const MAX_SCENARIOS = 4;
+/**
+ * Story types.
+ *
+ *   domain     – full DDD/TDD path: exactly one command on one aggregate, Gherkin traceability, reviews
+ *   chore/task – fast lane: UI tweaks, refactorings, dependencies, setup; no Gherkin matching, no formal reviews
+ *   tech-task  – deliberate technical groundwork with a checklist
+ *   spike      – a timeboxed question
+ *   story      – the legacy name of `domain`; still valid, reported as a warning
  */
-export const STATUSES = ["draft", "review", "ready", "in-progress", "done", "superseded"] as const;
-/** Statuses that require a finished story: size set, no [OPEN] markers. */
-export const COMMITTED = new Set(["ready", "in-progress", "done"]);
-export const MAX_SCENARIOS = 10;
+export const DOMAIN_TYPES = new Set(["domain", "story"]);
+export const FAST_TYPES = new Set(["chore", "task"]);
+export const LEGACY_TYPES: Record<string, string> = { story: "domain" };
 const PRIORITIES = ["must", "should", "could", "wont"];
 
 // --------------------------------------------------------------------------
@@ -82,6 +103,13 @@ const list = (v: unknown): string[] => (Array.isArray(v) ? v : []);
 const items = (model: Obj, key: string): Obj[] => list(model[key]) as unknown as Obj[];
 const prefix = (id: string): string => id.split("-", 1)[0];
 
+/** Domain story: full DDD/TDD path. `story` is the legacy name of `domain`. */
+export const isDomain = (meta: Obj): boolean => DOMAIN_TYPES.has(String(meta.type));
+/** Fast lane: chore or task – no Gherkin matching, no formal subagent reviews. */
+export const isFastLane = (meta: Obj): boolean => FAST_TYPES.has(String(meta.type));
+/** A story with a frontend part: the explicit `ui: true` flag, or the legacy `ui` label. */
+export const isUi = (meta: Obj): boolean => meta.ui === true || list(meta.labels).includes("ui");
+
 /** Resolves symlinks where possible so paths from hooks and from ROOT compare equal. */
 export function realPath(p: string): string {
   try {
@@ -489,8 +517,8 @@ export const SCENARIO_RE = /^\s*(?:Scenario Outline|Scenario Template|Scenario|E
 
 function checkBody(r: Report, where: string, meta: Obj, body: string): void {
   const secs = sections(body);
-  const type = meta.type;
-  if (type === "story") {
+  const type = String(meta.type);
+  if (isDomain(meta)) {
     const s = section(secs, "story");
     if (s === null) {
       r.error(where, "section '## Story' is missing");
@@ -499,7 +527,9 @@ function checkBody(r: Report, where: string, meta: Obj, body: string): void {
     }
   }
   if (type === "spike" && section(secs, "question") === null) r.error(where, "spike needs a '## Question' section");
-  if (type === "tech-task" && section(secs, "task") === null) r.error(where, "tech task needs a '## Task' section");
+  if (type === "tech-task" || type === "task" || type === "chore") {
+    if (section(secs, "task") === null) r.error(where, `${type} needs a '## Task' section`);
+  }
 
   const ac = section(secs, "acceptance criteria");
   if (ac === null) {
@@ -511,12 +541,11 @@ function checkBody(r: Report, where: string, meta: Obj, body: string): void {
   const titles = scenarios.map((sc) => sc.split("\n")[0].trim().toLowerCase());
   const dupes = titles.filter((t, n) => t && titles.indexOf(t) !== n);
   if (dupes.length) r.error(where, `scenario titles must be unique within the story: ${[...new Set(dupes)].join(", ")}`);
-  if (type === "story") {
+  if (isDomain(meta)) {
     if (scenarios.length < 2) r.error(where, "at least 2 Gherkin scenarios required (happy path + error/edge case)");
     scenarios.forEach((sc, n) => {
-      if (!/^\s*When\b/m.test(sc) || !/^\s*Then\b/m.test(sc)) {
-        r.error(where, `scenario ${n + 1}: 'When' and 'Then' are required`);
-      }
+      const missing = ["Given", "When", "Then"].filter((step) => !new RegExp(`^\\s*${step}\\b`, "m").test(sc));
+      if (missing.length) r.error(where, `scenario ${n + 1}: ${missing.join(", ")} required (Gherkin Given/When/Then)`);
     });
   } else if (!scenarios.length && !/^\s*[-*]\s*\[[ xX]\]/m.test(ac)) {
     r.error(where, "give acceptance criteria as scenarios or a checklist ('- [ ] …')");
@@ -554,8 +583,8 @@ export function scenarioTitlesIn(body: string): string[] {
  * and stays the authority.
  */
 export function completenessWarnings(story: Story): string[] {
-  if (story.meta.type !== "story") return []; // spikes and tech tasks carry checklists, not screens
-  if (!list(story.meta.labels).includes("ui")) return [];
+  if (!isDomain(story.meta)) return []; // fast lane, spikes and tech tasks carry checklists, not screens
+  if (!isUi(story.meta)) return [];
   const ac = section(sections(story.body), "acceptance criteria") ?? "";
   if (!ac.trim()) return [];
   const titles = scenarioTitlesIn(story.body);
@@ -638,24 +667,90 @@ export function validateStories(report: Report, only: string | null = null, leni
         else r.error(where, msg);
       }
     }
-    const status = m.status;
-    if (COMMITTED.has(status) && !m.size) r.error(where, `size is missing – lead-dev must estimate before '${status}'`);
-    if (m.size === "XL") {
-      const msg = "size XL – split the story";
-      if (COMMITTED.has(status)) r.error(where, msg);
-      else r.warn(where, msg);
+    const status = String(m.status);
+    const type = String(m.type);
+    // The strict 1-command rules apply to the new `domain` type. `story` is the legacy name and stays valid
+    // (warnings only), so an upgrade does not turn an existing backlog red.
+    const strict = type === "domain";
+    if (LEGACY_TYPES[type]) {
+      r.warn(where, `type '${type}' is the legacy name of '${LEGACY_TYPES[type]}' – use '${LEGACY_TYPES[type]}'`);
+    }
+    if (!isDomain(m) && !isFastLane(m) && type !== "spike" && type !== "tech-task") {
+      r.error(where, `unknown type '${type}' (domain, chore, task, tech-task, spike)`);
     }
-    // Every scenario is a red → green cycle in /implement; past ten the story is too big or restates UX
-    // guideline patterns (user, 2026-10-26). `ready` ones were approved under the older rules.
+    if (strict) {
+      if (!m.context) r.error(where, "domain story needs a bounded context ('context: BC-…')");
+      if (!m.aggregate) r.error(where, "domain story needs exactly one aggregate ('aggregate: AGG-…')");
+      if (!m.command) r.error(where, "domain story needs exactly one command ('command: CMD-…')");
+    }
+    if (isDomain(m) && !strict) {
+      if (!m.aggregate || !m.command) {
+        r.warn(where, "legacy story without aggregate/command – the 1-command rule cannot be checked; migrate it to type: domain");
+      }
+    }
+    if (idx !== null) {
+      const ctx = m.context;
+      if (typeof ctx === "string" && ctx && (!idx.has(ctx) || prefix(ctx) !== "BC")) {
+        r.error(where, `context '${ctx}' does not exist in events.yaml`);
+      }
+      for (const ev of list(m.events)) {
+        if (!idx.has(ev) || prefix(ev) !== "EVT") r.error(where, `event '${ev}' does not exist in events.yaml`);
+      }
+      if (m.aggregate !== undefined) {
+        if (typeof m.aggregate !== "string" || !idx.has(m.aggregate) || prefix(m.aggregate) !== "AGG") {
+          r.error(where, `aggregate '${fmt(m.aggregate)}' does not exist in events.yaml`);
+        }
+      }
+      if (m.command !== undefined) {
+        if (typeof m.command !== "string" || !idx.has(m.command) || prefix(m.command) !== "CMD") {
+          r.error(where, `command '${fmt(m.command)}' does not exist in events.yaml`);
+        }
+      }
+      // The 1-command rule: one story = one command + its events on one aggregate.
+      const cmd = typeof m.command === "string" ? idx.get(m.command) : undefined;
+      if (cmd && typeof m.aggregate === "string" && cmd.aggregate && cmd.aggregate !== m.aggregate) {
+        r.error(where, `command '${m.command}' belongs to aggregate '${cmd.aggregate}', not '${m.aggregate}'`);
+      }
+      if (strict && cmd) {
+        const produced = list(cmd.produces);
+        const linked = list(m.events);
+        if (!produced.length) {
+          r.error(where, `command '${m.command}' produces no event in events.yaml`);
+        } else {
+          const missing = produced.filter((ev) => !linked.includes(ev));
+          const extra = linked.filter((ev) => !produced.includes(ev));
+          if (missing.length || extra.length) {
+            r.error(
+              where,
+              `events must be exactly what command '${m.command}' produces (${produced.join(", ")})` +
+                (missing.length ? ` – missing: ${missing.join(", ")}` : "") +
+                (extra.length ? ` – not produced: ${extra.join(", ")}` : ""),
+            );
+          }
+        }
+      }
+    } else if (isDomain(m)) {
+      // Without a readable model the required fields are checked above; the cross-check cannot run.
+      r.warn(where, "events.yaml is missing or invalid – the aggregate/command cross-check was skipped");
+    }
+    for (const dep of list(m.depends_on)) {
+      if (dep === id) {
+        r.error(where, "depends on itself");
+      } else if (!stories.has(dep)) {
+        const msg = `depends_on '${dep}' does not exist`;
+        if (lenientDeps) r.warn(where, msg);
+        else r.error(where, msg);
+      }
+    }
+    if (m.size === "XL") r.warn(where, "size XL – split the story");
+    // Every scenario is a red → green cycle in /implement; past four the story merges commands or restates UX
+    // guideline patterns. Domain stories must obey it; legacy `story` files get a warning until migrated.
     const scenarioTotal = scenarioTitlesIn(s.body).length;
-    if (m.type === "story" && scenarioTotal > MAX_SCENARIOS && (status === "draft" || status === "review")) {
-      const msg = `${scenarioTotal} scenarios, at most ${MAX_SCENARIOS} – split the story, or reference the UX guideline (G-number) instead of restating its pattern as scenarios`;
-      if (status === "review") r.error(where, msg);
+    if (isDomain(m) && scenarioTotal > MAX_SCENARIOS && (status === "draft" || status === "review" || status === "ready-for-human-review")) {
+      const msg = `${scenarioTotal} scenarios, at most ${MAX_SCENARIOS} – split the story (one command, one aggregate), or reference the UX guideline (G-number) instead of restating its pattern as scenarios`;
+      if (strict && status !== "draft") r.error(where, msg);
       else r.warn(where, msg);
     }
-    if (m.type === "story" && COMMITTED.has(status) && !list(m.events).length) {
-      r.warn(where, "no domain events linked – traceability is missing");
-    }
 
     // In tracker mode the Markdown file is a mirror. A story that is handed to engineering must carry its
     // external key, otherwise the next pull cannot match it and the tracker is not the source of truth any more.
@@ -668,7 +763,7 @@ export function validateStories(report: Report, only: string | null = null, leni
           r.error(where, "external.key is missing");
         }
       }
-      if (COMMITTED.has(status) && !(ext && typeof ext === "object" && typeof ext.key === "string" && ext.key)) {
+      if (HANDOFF.has(status) && !(ext && typeof ext === "object" && typeof ext.key === "string" && ext.key)) {
         r.error(where, `not linked to the ${backlog.provider} backlog – run /backlog-sync push before '${status}'`);
       }
       const prefix = labelPrefix(backlog);
@@ -680,7 +775,9 @@ export function validateStories(report: Report, only: string | null = null, leni
     checkBody(r, where, m, s.body);
     // Completeness is checked while a story is being written; `ready` ones were approved under the older rules
     // and are challenged in `/groom-backlog` instead (user, 2026-10-01).
-    if (status === "draft" || status === "review") for (const w of completenessWarnings(s)) r.warn(where, w);
+    if (status === "draft" || status === "review" || status === "ready-for-human-review") {
+      for (const w of completenessWarnings(s)) r.warn(where, w);
+    }
   }
 
   // Cycles in depends_on
@@ -710,6 +807,7 @@ export function validateStories(report: Report, only: string | null = null, leni
 const STATUS_TITLES: [string, string][] = [
   ["in-progress", "In Progress"],
   ["ready", "Ready"],
+  ["ready-for-human-review", "Ready for Human Review"],
   ["review", "In Review"],
   ["draft", "Draft"],
   ["done", "Done"],
@@ -763,14 +861,14 @@ export function renderBacklog(stories: Story[], model: Obj | null): string {
     );
   }
   if (!stories.length) {
-    out.push("_No stories yet. Derive them from the event storming with `@requirements-engineer`._", "");
+    out.push("_No stories yet. Derive them from the event storming as a spec engineer (main session)._", "");
     return out.join("\n");
   }
 
   const counts = STATUS_TITLES.map(([st, title]) => [title, stories.filter((s) => s.meta.status === st).length] as const);
   // Progress is measured in domain stories and their scenarios, not in the total number of stories (CLAUDE.md).
   // A superseded story was never built as one – its work counts where it was done.
-  const domain = stories.filter((s) => s.meta.type === "story" && s.meta.status !== "superseded");
+  const domain = stories.filter((s) => isDomain(s.meta) && s.meta.status !== "superseded");
   const scenarioCount = (s: Story) =>
     (section(sections(s.body), "acceptance criteria") ?? "")
       .split("\n")

package/.claude/lib/engineering.ts

@@ -66,13 +66,15 @@ export const testTitle = (id: string, scenario: string): string => `${id}: ${sce
 // Status workflow
 // --------------------------------------------------------------------------
 /**
- * Allowed single steps. Discovery owns draft/review/ready; engineering moves ready → in-progress → done
- * and sends a story back to review when it turns out to be wrong. `done` is final: changes to finished
- * behaviour become a new story.
+ * Allowed single steps. Discovery owns draft/review/ready-for-human-review; the linter sets the review state, the
+ * user approves `ready`. Engineering moves ready → in-progress → done and sends a story back to review when it turns
+ * out to be wrong. `done` is final: changes to finished behaviour become a new story.
  */
 const TRANSITIONS: Record<string, string[]> = {
   draft: ["review", "superseded"],
-  review: ["draft", "ready", "superseded"],
+  review: ["draft", "ready-for-human-review", "superseded"],
+  // The linter gate passed; only the user turns this into `ready`.
+  "ready-for-human-review": ["draft", "review", "ready", "superseded"],
   ready: ["review", "in-progress", "superseded"],
   "in-progress": ["review", "done"],
   done: [],
@@ -106,7 +108,7 @@ export function transitionErrors(story: d.Story, from: string, to: string, stori
     errs.push(
       from === "done" || from === "superseded"
         ? `a ${from} story is never reopened – capture the change as a new story`
-        : `status '${from}' cannot become '${to}' (workflow: draft → review → ready → in-progress → done, back to review when a story is wrong; superseded from any status before in-progress)`,
+        : `status '${from}' cannot become '${to}' (workflow: draft → review → ready-for-human-review → ready → in-progress → done, back to review when a story is wrong; superseded from any status before in-progress)`,
     );
     return errs;
   }
@@ -114,8 +116,12 @@ export function transitionErrors(story: d.Story, from: string, to: string, stori
     const open = list(story.meta.depends_on).filter((dep) => stories.get(dep)?.meta.status !== "done");
     if (open.length) errs.push(`depends on stories that are not done yet: ${open.join(", ")}`);
   }
+  // The linter gate and the user's approval are two separate steps; skipping one defeats the workflow.
+  if (to === "ready" && from !== "ready-for-human-review") {
+    errs.push("'ready' needs 'ready-for-human-review' first – run the spec linter and let the user approve");
+  }
   if (to === "done") {
-    if (story.meta.type === "story") {
+    if (d.isDomain(story.meta)) {
       const cov = scenarioCoverage(story);
       if (cov.missing.length) {
         errs.push(`scenarios without a test titled '${d.storyId(story)}: <scenario title>': ${cov.missing.map((m) => `"${m}"`).join(", ")}`);

package/.claude/package.json

@@ -7,6 +7,7 @@
     "node": ">=22.18"
   },
   "scripts": {
+    "lint:story": "node skills/user-stories/scripts/lint-story.ts",
     "validate": "node skills/event-storming/scripts/validate-events.ts && node skills/user-stories/scripts/validate-stories.ts",
     "render": "node skills/event-storming/scripts/render-event-storming.ts && node skills/user-stories/scripts/render-backlog.ts",
     "typecheck": "tsc -p ."

package/.claude/settings.json

@@ -5,8 +5,7 @@
       "Bash(node .claude/skills/adopt/scripts/*)",
       "Bash(node .claude/skills/event-storming/scripts/validate-events.ts)",
       "Bash(node .claude/skills/event-storming/scripts/render-event-storming.ts)",
-      "Bash(node .claude/skills/user-stories/scripts/validate-stories.ts)",
-      "Bash(node .claude/skills/user-stories/scripts/render-backlog.ts)",
+      "Bash(node .claude/skills/user-stories/scripts/*)",
       "Bash(node .claude/skills/implement/scripts/*)",
       "Bash(git status *)",
       "Bash(git diff *)",

package/.claude/skills/adopt/SKILL.md

@@ -211,9 +211,11 @@ user has not prioritised.
 
 Only when the invocation contains `--stories`, or the user explicitly asks after seeing the table:
 
-- delegate to `requirements-engineer` with the **selected** gaps only, the confirmed IDs from `events.yaml`, the
-  label `adoption:<slug>`, and `ui` for stories with a frontend part;
-- new stories start as `status: draft`; the ones the user wants first go through `/review-stories`.
+- write the stories yourself as the spec engineer (the `user-stories` skill is the method) with the **selected**
+  gaps only, the confirmed IDs from `events.yaml`, `type: domain` with one `command` and its `aggregate`, `ui: true`
+  for stories with a frontend part, and the label `adoption:<slug>`;
+- new stories start as `status: draft`; the ones the user wants first go through the spec linter and
+  `/review-stories`.
 
 **Do not write stories for behaviour that already works** – that turns the backlog into a description of the
 past. Existing behaviour is covered by its tests, and the domain model is the map. If an earlier run created

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

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