kataster 0.3.1 → 0.6.0

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

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

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

@@ -0,0 +1,252 @@
+/**
+ * Finds the source files a story or a diff touches and checks whether a test exists for each of them.
+ *
+ *   node .claude/skills/implement/scripts/characterize.ts --story ST-012
+ *   node .claude/skills/implement/scripts/characterize.ts --changed src/services/order-service.ts
+ *   node .claude/skills/implement/scripts/characterize.ts --base origin/main --json
+ *
+ * This is a deterministic *test-presence* check, not a coverage tool: it finds tests by file-name convention
+ * and by imports/references of the source. Whether a test covers the behaviour that is about to change is the
+ * agent's judgement. When no test exists, /implement writes characterization tests first and commits them
+ * separately, before the story's red → green loop.
+ *
+ * Exit 0 unless the arguments are wrong or the story does not exist; a missing test is a finding, not a crash.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import * as d from "../../../lib/discovery.ts";
+import * as e from "../../../lib/engineering.ts";
+import { readRepoMap, scanRepo, type RepoPackage } from "../../../lib/repo.ts";
+import { packageForFile } from "../../../lib/slices.ts";
+
+const args = process.argv.slice(2);
+
+function usage(): void {
+  console.log(
+    [
+      "Usage: node .claude/skills/implement/scripts/characterize.ts [options]",
+      "",
+      "  --story <ST-NNN>   find source files from the story's IDs, names and terms",
+      "  --changed <file>   a file (repeatable or comma-separated); default: git status",
+      "  --base <ref>       use the files changed against this ref",
+      "  --json             machine-readable result",
+    ].join("\n"),
+  );
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+let storyId = "";
+const changed: string[] = [];
+let base = "";
+for (let i = 0; i < args.length; i += 1) {
+  const take = (): string | undefined => {
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) return undefined;
+    i += 1;
+    return value;
+  };
+  if (args[i] === "--story") storyId = (take() ?? "").toUpperCase();
+  else if (args[i] === "--changed") {
+    const value = take();
+    if (value) changed.push(...value.split(",").map((f) => f.trim()).filter(Boolean));
+  } else if (args[i] === "--base") base = take() ?? base;
+}
+
+if (!storyId && !changed.length && !base) {
+  usage();
+  process.exit(1);
+}
+
+const list = (v: unknown): string[] => (Array.isArray(v) ? v : []);
+const read = (file: string): string => {
+  try {
+    return readFileSync(join(d.ROOT, file), "utf8");
+  } catch {
+    return "";
+  }
+};
+
+const map = readRepoMap(d.ROOT) ?? scanRepo(d.ROOT, { toolGraph: false });
+const pkgFor = (file: string): RepoPackage | undefined => packageForFile(map.packages, file);
+
+const testFiles = e.projectFiles().filter(e.isTest);
+const sourceFiles = e.projectFiles().filter((f) => e.isCode(f) && !e.isTestCode(f));
+
+function changedFiles(): string[] {
+  if (changed.length) return [...new Set(changed)];
+  if (base) return (e.git("diff", "--name-only", base) ?? "").split("\n").map((l) => l.trim()).filter(Boolean);
+  return (e.git("status", "--porcelain", "--untracked-files=all") ?? "")
+    .split("\n")
+    .map((line) => line.slice(3).trim().replace(/^.* -> /, ""))
+    .filter(Boolean);
+}
+
+function testBase(file: string): string {
+  return basename(file, extname(file))
+    .replace(/^test_/, "")
+    .replace(/(?:[._-](?:test|spec|tests|specs))$/i, "")
+    .replace(/(?:Test|Tests|Spec|Specs|IT)$/i, "")
+    .toLowerCase();
+}
+
+function testsFor(source: string): { file: string; reason: string }[] {
+  const sourceBase = basename(source, extname(source)).toLowerCase();
+  const out: { file: string; reason: string }[] = [];
+  for (const test of testFiles) {
+    const reason: string[] = [];
+    if (testBase(test) === sourceBase) reason.push("same name");
+    const text = read(test);
+    // A reference to the module is enough evidence to look; it is not proof of behavioural coverage.
+    if (sourceBase.length >= 3 && text.toLowerCase().includes(sourceBase)) reason.push("mentions the module");
+    if (reason.length) out.push({ file: test, reason: reason.join(", ") });
+  }
+  return out;
+}
+
+function storySeedTerms(story: d.Story): { ids: string[]; names: string[]; words: string[] } {
+  const ids = new Set<string>();
+  const names = new Set<string>();
+  const text = `${story.meta.title ?? ""}\n${story.body}`;
+  for (const id of text.matchAll(/\b(?:ACT|EXT|BC|AGG|EVT|CMD|POL|RM)-[A-Za-z0-9]+\b/g)) ids.add(id[0]);
+  for (const key of ["aggregate", "command", "context"]) {
+    if (typeof story.meta[key] === "string") ids.add(story.meta[key]);
+  }
+  for (const id of list(story.meta.events)) ids.add(id);
+
+  const model = d.loadEventsModel();
+  if (model) {
+    const idx = d.indexModel(model);
+    for (const id of [...ids]) {
+      const item = idx.get(id);
+      if (typeof item?.name === "string") names.add(item.name);
+    }
+    for (const command of (model.commands ?? []) as d.Obj[]) {
+      if (list(command.produces).some((event) => list(story.meta.events).includes(event))) {
+        if (typeof command.name === "string") names.add(command.name);
+      }
+    }
+  }
+
+  const glossary = e.loadGlossary();
+  for (const term of glossary.terms) {
+    if (new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(text)) names.add(term);
+  }
+
+  const stop = new Set(["story", "want", "that", "with", "from", "this", "when", "then", "given", "should", "must", "can", "the", "and", "for"]);
+  const words = [...new Set(
+    String(story.meta.title ?? "")
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((word) => word.length >= 4 && !stop.has(word)),
+  )];
+  return { ids: [...ids], names: [...names], words };
+}
+
+function scoreSource(file: string, terms: { ids: string[]; names: string[]; words: string[] }): { score: number; reasons: string[] } {
+  const text = read(file).toLowerCase();
+  const path = file.toLowerCase();
+  let score = 0;
+  const reasons: string[] = [];
+  for (const id of terms.ids) {
+    if (text.includes(id.toLowerCase())) {
+      score += 3;
+      reasons.push(`mentions ${id}`);
+    }
+  }
+  for (const name of terms.names) {
+    const lower = name.toLowerCase();
+    if (lower.length >= 3 && new RegExp(`\\b${lower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(text)) {
+      score += 2;
+      reasons.push(`mentions "${name}"`);
+    }
+  }
+  for (const word of terms.words) {
+    if (path.includes(word)) {
+      score += 1;
+      reasons.push(`path contains "${word}"`);
+    }
+  }
+  return { score, reasons };
+}
+
+let story: d.Story | undefined;
+const seeds = new Map<string, { file: string; score: number; reasons: string[] }>();
+const warnings: string[] = [];
+
+if (storyId) {
+  try {
+    story = e.findStory(storyId);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+  const terms = storySeedTerms(story);
+  for (const file of sourceFiles) {
+    const scored = scoreSource(file, terms);
+    if (scored.score > 0) seeds.set(file, { file, ...scored });
+  }
+  if (!seeds.size) warnings.push("no source file mentions the story's IDs or terms – pass --changed to name the affected paths");
+}
+
+for (const file of changedFiles()) {
+  if (!existsSync(join(d.ROOT, file))) continue;
+  if (!sourceFiles.includes(file)) continue;
+  seeds.set(file, { file, score: seeds.get(file)?.score ?? 0, reasons: [...(seeds.get(file)?.reasons ?? []), "changed"] });
+}
+
+const sourceRows = [...seeds.values()]
+  .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
+  .slice(0, 40)
+  .map((seed) => {
+    const tests = testsFor(seed.file);
+    const pkg = pkgFor(seed.file);
+    return {
+      file: seed.file,
+      package: pkg?.path,
+      score: seed.score,
+      reasons: seed.reasons,
+      tests,
+      covered: tests.length > 0,
+      confidence: tests.some((test) => test.reason.includes("same name") || test.reason.includes("mentions the module")) ? "medium" : "low",
+    };
+  });
+
+const storyTests = storyId
+  ? testFiles.filter((file) => read(file).includes(storyId)).map((file) => ({ file, reason: `mentions ${storyId}` }))
+  : [];
+if (storyId && !storyTests.length) warnings.push(`no test mentions ${storyId} yet – expected before the story's red → green loop`);
+
+const result = {
+  story: story ? { id: storyId, title: story.meta.title, status: story.meta.status, type: story.meta.type } : null,
+  seeds: [...seeds.values()].sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, 40),
+  sources: sourceRows,
+  storyTests,
+  warnings,
+};
+
+if (args.includes("--json")) {
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}
+
+console.log(`Characterization check${story ? ` – ${storyId}: ${story.meta.title}` : ""}`);
+if (!sourceRows.length) {
+  console.log("\nNo affected source file found. Name the paths with --changed, or widen the story terms.");
+}
+for (const row of sourceRows) {
+  const status = row.covered ? "test found" : "NO TEST FOUND";
+  console.log(`\n- ${row.file} (${row.package ?? "unmapped"}) – ${status}`);
+  if (row.reasons.length) console.log(`  why: ${row.reasons.join("; ")}`);
+  for (const test of row.tests) console.log(`  test: ${test.file} (${test.reason})`);
+  if (!row.covered) console.log("  → write a characterization test first; pin the current behaviour, commit it separately, then start the story tests.");
+}
+if (storyTests.length) {
+  console.log(`\nTests that mention ${storyId}:`);
+  for (const test of storyTests) console.log(`- ${test.file} (${test.reason})`);
+}
+for (const warning of warnings) console.log(`\nWARNING ${warning}`);
+console.log("\nA test file is evidence, not proof of behavioural coverage. If the current behaviour contradicts the story, the story goes back to review.");

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

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