kataster 0.4.0 → 0.6.0

package/.claude/skills/adopt/templates/context-map.as-is.md

@@ -0,0 +1,22 @@
+# As-is context map – {{project}}
+
+> Recovered from code by `/adopt` on {{date}} at {{commit}}. This is **not a target**.
+> Target: [context-map.md](context-map.md) · Gap register: [gap-register.md](gap-register.md).
+
+<!--
+  One section per recovered bounded context. Use `### BC-… – <name>` so gap-register.ts can link to it.
+  Evidence is a table, a service method or a path; no target statements, no invented terms.
+-->
+
+```mermaid
+flowchart LR
+  %% BC-ExampleA -->|recovered dependency| BC-ExampleB
+```
+
+## Contexts
+
+### BC-Example – <name>
+Purpose (as recovered): …
+Core terms: …
+Evidence: `<path:line>`, `<table>`, `<service method>`.
+Boundaries: …

package/.claude/skills/architect/SKILL.md

@@ -21,10 +21,15 @@ Domain language (the glossary in `CONTEXT.md`), bounded contexts, aggregates and
     ├── architecture/
     │   └── data-model.md       ← logical data model (domain-model skill)
     └── domain/
-        ├── context-map.md
+        ├── context-map.md        ← target map
+        ├── context-map.as-is.md  ← as-is snapshot, written only by /adopt
+        ├── gap-register.md       ← as-is ↔ target gaps (generated rows + decisions)
         └── events.yaml
 ```
 
+`docs/domain/context-map.md` is the target; `context-map.as-is.md` is the snapshot recovered by `/adopt`. Do not
+write the as-is map from an architecture session – a target decision belongs in the target map.
+
 Once code exists and contexts live in separate modules, context-specific decisions may move next to the code (`src/<context>/docs/adr/`); system-wide decisions stay in `docs/adr/`.
 
 ## During the session

package/.claude/skills/domain-model/CONTEXT-FORMAT.md

@@ -42,6 +42,6 @@ _Avoid_: Fix, service
 
 ## Single vs multi-context
 
-During discovery there is one root `CONTEXT.md`, grouped by bounded context; the relationships between contexts are in `docs/domain/context-map.md`.
+During discovery there is one root `CONTEXT.md`, grouped by bounded context; the relationships between contexts are in `docs/domain/context-map.md` (target). `/adopt` records what the code does today in `docs/domain/context-map.as-is.md` – not a target.
 
 When code exists and contexts become separate modules, the glossary may be split: a root `CONTEXT-MAP.md` lists the contexts and links to one `CONTEXT.md` per module (e.g. `src/workshop/CONTEXT.md`). Only split when the code is actually structured that way – decide it via ADR.

package/.claude/skills/domain-model/SKILL.md

@@ -15,7 +15,9 @@ Architecture decisions (ADRs, tech stack) belong to the `architect` skill. The d
 |---|---|
 | Glossary (ubiquitous language) | `CONTEXT.md` at the repo root – format: [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) |
 | Event storming model incl. `bounded_contexts`, `aggregates` | `docs/domain/events.yaml` |
-| Context map | `docs/domain/context-map.md` |
+| Target context map | `docs/domain/context-map.md` – where the domain is going |
+| As-is context map | `docs/domain/context-map.as-is.md` – recovered from code, written only by `/adopt` |
+| Gap register | `docs/domain/gap-register.md` – links as-is and target, generated rows + user decisions |
 | Logical data model | `docs/architecture/data-model.md` – template: `templates/data-model.md` |
 
 ## 1. Language (during every session)
@@ -30,7 +32,7 @@ When the user uses vague or overloaded terms, propose a precise canonical term.
 When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. "A customer reports the same problem on an item that already has an open case – a new case or the same one?"
 
 ### Cross-reference with docs and code
-When the user states how something works, check whether `docs/domain/events.yaml`, the stories (and the code, once it exists) agree. If you find a contradiction, surface it.
+When the user states how something works, check whether `docs/domain/events.yaml`, the stories (and the code, once it exists) agree. If you find a contradiction, surface it. A source that contradicts the model is a grilling question, not a silent rewrite of the model (see the `research` skill).
 
 ### Update CONTEXT.md inline
 When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. `CONTEXT.md` is totally devoid of implementation details. It is a glossary and nothing else – not a spec, not a scratch pad.
@@ -39,7 +41,8 @@ Same word, different meaning in two places → a hint at a bounded context bound
 
 ## 2. Bounded Contexts & Context Map
 - Draw boundaries along language (same word, different meaning → different context) and responsibility (who decides?).
-- `docs/domain/context-map.md`: per context its purpose, core terms, owner role. Relationships as a Mermaid `flowchart` using the patterns Customer/Supplier, Conformist, Anti-Corruption Layer, Shared Kernel, Published Language.
+- `docs/domain/context-map.md` is the **target** map: per context its purpose, core terms, owner role. Relationships as a Mermaid `flowchart` using the patterns Customer/Supplier, Conformist, Anti-Corruption Layer, Shared Kernel, Published Language.
+- `docs/domain/context-map.as-is.md` is the **as-is** snapshot: what the code does today, with evidence. Only `/adopt` writes it; every other discovery path writes the target. The gap register links both.
 - 2–4 contexts are typical for a small system. More only with justification.
 - Maintain them in `events.yaml` under `bounded_contexts`, and group the terms in `CONTEXT.md` by context.
 
@@ -50,6 +53,23 @@ Same word, different meaning in two places → a hint at a bounded context bound
 - **An invariant is stated once, on the aggregate** (user, 2026-10-01). A command's `rules` list only what it adds beyond them: defaults, actor permissions no invariant carries, required input, checks across aggregate or context boundaries, and consequences of the transition. Everything the stored state has to satisfy is an invariant, not a rule – the spec engineer reads both when deriving scenarios.
 - Sign of a wrong aggregate: a command needs data from several aggregates to check a rule.
 
+### Aggregate status: target, as-is, unresolved
+Every aggregate carries a status; a missing `status` means `target`, so existing models stay valid.
+
+| Status | Meaning | Rule |
+|---|---|---|
+| `target` | The boundary the project wants. The default in greenfield and in a confirmed target model. | Only a user decision makes an inferred boundary `target`. |
+| `as-is` | The factual consistency boundary recovered from code. | Requires `evidence`: the table, service method or path that marks it. |
+| `unresolved` | The boundary is unclear. | Requires an open hotspot (`refs: [AGG-…]`) and grilling. No story on it can become ready. |
+
+**Prefer `as-is` or `unresolved` over an invented aggregate.** `/adopt` never writes `target` for something it
+inferred from code. If you cannot name the table, method or path that holds the boundary together, it is not
+`as-is` – it is `unresolved`. After changing a status or evidence, refresh the gap register:
+
+```bash
+node .claude/skills/adopt/scripts/gap-register.ts
+```
+
 ## 4. Logical Data Model (`docs/architecture/data-model.md`)
 - Per aggregate: root entity, entities, value objects, attributes with **domain** types (e.g. `SerialNumber`, `Money`, `Timestamp`), required/optional.
 - Lifecycle as a Mermaid `stateDiagram-v2` (derive states from the events).

package/.claude/skills/event-storming/SKILL.md

@@ -12,7 +12,8 @@ Focus of this session: the arguments from the invocation (empty = big picture ac
 
 ## Preparation
 1. Call the `skill` tool for `grilling` and `domain-model`. Grilling sets how you ask questions; domain-model sets how you guard the language in `CONTEXT.md`.
-2. Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`.
+2. Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md` (target),
+   `docs/domain/context-map.as-is.md` and `docs/domain/gap-register.md` when they exist.
 3. Format reference: `templates/events.example.yaml` in this skill folder (unrelated example domain – copy the format only, no content).
 
 ## Facilitation Rules
@@ -33,7 +34,7 @@ Focus of this session: the arguments from the invocation (empty = big picture ac
 4. **Commands & actors** – What triggers each event, and who does it? Capture external systems (`EXT-`). Business rules of the command go into `rules` – only what the command adds beyond the `invariants` of its aggregate, which are stated once, there (user, 2026-10-01).
 5. **Policies** – "Whenever <event>, then <command>". Include time-triggered ones (event with `origin: time`) and manual routines.
 6. **Read models** – What information does an actor need to trigger the command? (`fed_by`, `used_by`, `fields`)
-7. **Aggregates (proposal)** – Which rules must be protected consistently? Rough assignment of commands/events. Detailed work is done by `domain-architect`.
+7. **Aggregates (proposal)** – Which rules must be protected consistently? Rough assignment of commands/events. Detailed work is done by `domain-architect`. Every aggregate gets `status: target` in greenfield; a boundary the user cannot settle becomes `status: unresolved` with an open hotspot. When adopting existing code, the status is `as-is` (with evidence) or `unresolved`, never an invented `target`.
 8. **Bounded contexts (proposal)** – Where do language or responsibility change? Propose rough boundaries.
 
 When focusing on a single process: phases 0–6 for that process (phase 0 only for what the vision doesn't cover yet), 7–8 only if something new emerges.

package/.claude/skills/event-storming/schema/events.schema.json

@@ -51,6 +51,8 @@
         "id": { "type": "string", "pattern": "^AGG-[A-Za-z0-9]+$" },
         "name": { "$ref": "#/$defs/text" },
         "context": { "type": "string" },
+        "status": { "enum": ["target", "as-is", "unresolved"] },
+        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" } },
         "invariants": { "type": "array", "items": { "$ref": "#/$defs/text" } },
         "description": { "type": "string" }
       }

package/.claude/skills/event-storming/templates/events.example.yaml

@@ -24,12 +24,18 @@ aggregates:
   - id: AGG-Bike
     name: Bike
     context: BC-Rental
+    status: target
     invariants:
       - A bike can only be rented out once at a time
       - A bike marked as damaged cannot be rented out
   - id: AGG-RepairOrder
     name: Repair order
     context: BC-Workshop
+    # status: as-is          # factual boundary recovered from code; add evidence below
+    # evidence:
+    #   - repair_orders table (db/schema.sql:40)
+    #   - RepairOrderService.open() (src/services/repairOrderService.ts:22)
+    # status: unresolved    # boundary unclear; add an open hotspot with refs: [AGG-RepairOrder]
 
 events:
   - id: EVT-BikeRented

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

@@ -1,8 +1,8 @@
 ---
 name: feature
-description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL), grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story instead; `--prototype` adds a throwaway prototype before the stories.
+description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL), grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story instead; `--prototype` adds a throwaway prototype before the stories; `--research` forces the research step for a cross-cutting question.
 disable-model-invocation: true
-argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--prototype[=ui|logic]]"
+argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--prototype[=ui|logic]] [--research]"
 ---
 
 # New Feature
@@ -11,6 +11,8 @@ The argument is a feature idea, an existing story or a ticket. Empty → ask the
 Pick a short kebab-case slug for it (e.g. `order-photos`); stories get the label `feature:<slug>`.
 `--prototype[=ui|logic]` is a flag, not part of the idea: strip it before resolving a reference. It asks for a
 prototype before the stories are written; without a branch the `prototype` skill picks it from the question.
+`--research` is a flag too: strip it before resolving a reference. It forces the research step for a topic the
+trigger list in step 2 does not catch.
 
 ## 0. Intake – when the argument is a reference
 
@@ -57,10 +59,11 @@ ADRs and `docs/product/ux-guidelines.md` first.
 Do not run an event storming for a bug and do not create a feature slug unless the rule changes.
 
 ## 1. Preparation
-Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`, `docs/architecture/data-model.md`, `docs/adr/`, `docs/stories/BACKLOG.md`. Find out what already exists for this idea (events, stories, hotspots) before asking anything. With an intake result, use its source and matching story instead of searching from scratch. If a linked story exists, pull the tracker first (`/backlog-sync pull`) so the mirror is current.
+Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md` (target), `docs/domain/context-map.as-is.md`, `docs/domain/gap-register.md`, `docs/architecture/data-model.md`, `docs/adr/`, `docs/stories/BACKLOG.md`. Find out what already exists for this idea (events, stories, hotspots) before asking anything. With an intake result, use its source and matching story instead of searching from scratch. If a linked story exists, pull the tracker first (`/backlog-sync pull`) so the mirror is current.
 
 ## 2. Grill the idea
 Call the `skill` tool four times, for `grilling`, `domain-model`, `architect` and `ux-design` (the first three are the set of `/grill-with-docs`, which can't be called from a skill). Grill the user until the frontier is empty and they confirm a shared understanding. The grilling carries the three perspectives the spec linter cannot check – product, engineering, UX. With an intake result, the ticket's claims and the intake's `signals` seed the frontier; unresolved comments and contradictions are the first questions. Typical branches:
+- **Research – does the idea rest on an external fact?** Auth/identity, security, payment, privacy/data protection, accessibility, performance, a new library or technology, or `--research`: load the `research` skill before grilling the affected branch. Check `docs/research/` first; a trigger is not a mandate, and one run covers a topic, not a story. Findings enter the round as cited recommendations – evidence, not decisions.
 - **Product**: Which problem, for which user group, and what value? Measurable outcome? Does it fit the vision, or touch a non-goal? If it changes scope → update `docs/product/vision.md` with the user. Must vs. could – what ships first?
 - **Engineering**: Which existing code, data and stories change? Is there a migration? What is hard to test? Where does it cut into stories – one command per story, at most 4 scenarios?
 - Which existing processes, events and stories does it change? What's explicitly out of scope?
@@ -103,10 +106,10 @@ Read `.claude/skills/event-storming/SKILL.md` and follow it with the feature as
 - A UX decision changes or adds a guideline → delegate to `ux-designer`: write exactly these decisions into `docs/product/ux-guidelines.md`. A prototype verdict is a decision like any other; the branch pointer and the verdict go into the story through step 5. The audit of existing screens belongs to `/groom-backlog`, not to the feature.
 
 ## 5. Stories
-Write the stories yourself as the spec engineer (the `user-stories` skill is the method): derive one story per new or changed command, policy or read model; name `aggregate` and `command` (exactly one each), the event/command IDs, `ui: true` for every story with a frontend part, `type: chore`/`task` for non-domain work, the label `feature:<slug>`, the label `bug` for the bug path, the source reference (`Source: <ref> (<url>)`) for every story derived from a ticket, the UX decisions from step 2 (with the G-numbers of the guidelines they reference), the prototype verdict and branch pointer from step 2b, and existing stories that need revising. Do not merge two commands into one story; if the cut needs more than 4 scenarios, split it. Finished stories get `status: review` and are run through the spec linter.
+Write the stories yourself as the spec engineer (the `user-stories` skill is the method): derive one story per new or changed command, policy or read model; name `aggregate` and `command` (exactly one each), the event/command IDs, `ui: true` for every story with a frontend part, `type: chore`/`task` for non-domain work, the label `feature:<slug>`, the label `bug` for the bug path, the source reference (`Source: <ref> (<url>)`) for every story derived from a ticket, the research files they cite (`sources: [docs/research/<topic>.md]`) with adopted/rejected findings and their reasons in `## Context`, the UX decisions from step 2 (with the G-numbers of the guidelines they reference), the prototype verdict and branch pointer from step 2b, and existing stories that need revising. Do not merge two commands into one story; if the cut needs more than 4 scenarios, split it. Finished stories get `status: review` and are run through the spec linter.
 
 ## 6. Review
 Read `.claude/skills/review-stories/SKILL.md` and follow it with the story IDs from step 5 as the arguments (only this feature's stories, not everything in `review`). The spec linter must be green before a story reaches `ready-for-human-review`; the user approves every change and every `ready`. There is no separate review subagent.
 
 ## 7. Wrap-up
-Summarize: the source and the route taken (idea, ticket, existing story or bug), glossary changes, new/changed events, ADRs proposed, a prototype run and its verdict (if any), stories created and their review outcome (`ready` vs. still open), open hotspots/questions. Point to `docs/stories/BACKLOG.md`, where `ready` stories are queued for the engineering workflow. For a bug, say which documented rule was restored, or that the rule changed and became a feature.
+Summarize: the source and the route taken (idea, ticket, existing story or bug), glossary changes, new/changed events, ADRs proposed, research files created or refreshed and the findings the user adopted or rejected, a prototype run and its verdict (if any), stories created and their review outcome (`ready` vs. still open), open hotspots/questions. Point to `docs/stories/BACKLOG.md`, where `ready` stories are queued for the engineering workflow. For a bug, say which documented rule was restored, or that the rule changed and became a feature.

package/.claude/skills/grilling/SKILL.md

@@ -27,4 +27,19 @@ Each round the user answers reshapes the tree: settled decisions push the fronti
 
 Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
 
+## Research before a round
+
+When a frontier question depends on an external fact – authentication/identity, security, payment, privacy/data
+protection, accessibility, performance, a new library or technology – load the `research` skill before the round. A
+trigger is **not a mandate**: if `CONTEXT.md`, `docs/domain/events.yaml`, an accepted ADR, the UX guidelines, the
+conventions or a valid research file already answers it, run nothing. One run per topic, not per story.
+
+- The recommendation cites the finding and its source: `➡️ … (RFC 9700 §2.1.1; F1 in docs/research/oauth-pkce.md)`.
+- Only a confirmed recommendation becomes a Gherkin scenario or checklist item with an observable threshold – never
+  "follow best practices". A finding that cannot be tested is context or a guideline, not an acceptance criterion.
+- Rejected options are recorded with the reason in the story's `## Context` / `## Out of Scope` (or the ADR /
+  initiative). The research file stays evidence and is not rewritten into a decision log.
+- A finding that contradicts `CONTEXT.md`, `events.yaml`, an accepted ADR or the UX guidelines is a grilling
+  question. Never edit the model to match the source silently.
+
 The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

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

@@ -40,8 +40,11 @@ Read it instead of assuming `main`, `npm` or GitHub.
 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.
+   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
@@ -85,6 +88,38 @@ Seams from the catalog are the "confirmed seams" the tdd skill requires; the use
 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:**
@@ -211,7 +246,8 @@ A spike answers its **Question** within its **Timebox** – no test plan, no TDD
 
 ## 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:
+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 in the main session: revise the story, run the spec linter, and let the user approve it again

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/story-context.ts

@@ -19,6 +19,7 @@ import { join } from "node:path";
 import { stringify } from "yaml";
 import * as d from "../../../lib/discovery.ts";
 import * as e from "../../../lib/engineering.ts";
+import * as research from "../../../lib/research.ts";
 
 const id = process.argv[2]?.toUpperCase();
 if (!id) {
@@ -57,6 +58,36 @@ if (deps.length) {
   out.push("");
 }
 
+// Research sources: evidence the story cites. Expiry is advisory, but a missing or invalid file is a finding.
+const sources = research.sourceRefs(story.meta);
+if (sources.length) {
+  out.push(
+    "## Research sources",
+    "",
+    "Research is evidence, not a specification. When a scenario depends on a cited finding, read the file before implementing it.",
+    "",
+  );
+  for (const ref of sources) {
+    if (!research.isLocalResearchRef(ref)) {
+      out.push(`- ${ref}`);
+      continue;
+    }
+    const state = research.researchStatus(research.researchPath(ref));
+    if (state.status === "missing" || state.status === "invalid") {
+      out.push(`- \`${ref}\` – **${state.status.toUpperCase()}**`);
+      continue;
+    }
+    const detail = [
+      state.question ? `question: ${state.question}` : "",
+      state.retrieved ? `retrieved ${state.retrieved}` : "",
+      state.expires ? `expires ${state.expires}` : "",
+      state.status === "expired" ? "**EXPIRED**" : "",
+    ].filter(Boolean);
+    out.push(`- \`${ref}\`${detail.length ? ` – ${detail.join(" · ")}` : ""}`);
+  }
+  out.push("");
+}
+
 // Domain model
 const model = d.loadEventsModel();
 const aggregates = new Set<string>();
@@ -100,6 +131,39 @@ if (glossary) {
   if (entries.length) out.push("## Glossary (`CONTEXT.md`, terms used by the story)", "", ...entries.flatMap((x) => [x, ""]));
 }
 
+// Context maps: the target says where the story belongs, the as-is map says what the code does today.
+const contextIds = new Set<string>();
+if (typeof story.meta.context === "string") contextIds.add(story.meta.context);
+for (const match of storyText.matchAll(/\bBC-[A-Za-z0-9]+\b/g)) contextIds.add(match[0]);
+
+function contextBlocks(path: string): string[] {
+  const text = read(path);
+  if (!text) return [];
+  const lines = text.split("\n");
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = /^(#{2,4})\s+(BC-[A-Za-z0-9]+)\b/.exec(lines[i]);
+    if (!match || !contextIds.has(match[2])) continue;
+    const level = match[1].length;
+    const block = [lines[i]];
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const heading = /^(#{1,6})\s+/.exec(lines[j]);
+      if (heading && heading[1].length <= level) break;
+      block.push(lines[j]);
+    }
+    out.push(block.join("\n").trim());
+  }
+  return out;
+}
+
+const targetBlocks = contextBlocks(join(d.ROOT, "docs", "domain", "context-map.md"));
+const asIsBlocks = contextBlocks(join(d.ROOT, "docs", "domain", "context-map.as-is.md"));
+if (targetBlocks.length || asIsBlocks.length) {
+  out.push("## Context maps", "");
+  if (targetBlocks.length) out.push("### Target (`docs/domain/context-map.md`)", "", ...targetBlocks.flatMap((block) => [block, ""]));
+  if (asIsBlocks.length) out.push("### As-is (`docs/domain/context-map.as-is.md`)", "", ...asIsBlocks.flatMap((block) => [block, ""]));
+}
+
 // Data model
 const dataModel = read(join(d.ROOT, "docs", "architecture", "data-model.md"));
 if (dataModel && aggregates.size) {

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

@@ -71,9 +71,12 @@ const node = process.execPath;
 const disc = join(here, "..", "..");
 run("events.yaml", node, [join(disc, "event-storming", "scripts", "validate-events.ts")]);
 run("stories + spec linter", node, [join(disc, "user-stories", "scripts", "validate-stories.ts")]);
+// Research is evidence: expired or missing referenced files warn, they never fail the gate.
+run("research sources", node, [join(disc, "research", "scripts", "research-check.ts"), "--referenced"], true);
 // The map is generated; staleness is a warning (adoption may not have run yet), not a failed gate.
 run("repository map", node, [join(disc, "adopt", "scripts", "repo-map.ts"), "--check"], true);
 run("path-scoped rules", node, [join(disc, "adopt", "scripts", "rule-doc.ts"), "--check"], true);
+run("gap register", node, [join(disc, "adopt", "scripts", "gap-register.ts"), "--check"], true);
 run("project checks", node, [join(d.ROOT, ".claude", "hooks", "project-check.ts"), "--phase", "stop"]);
 run("scenario ↔ test traceability", node, [join(here, "check-scenarios.ts")]);
 run("domain ID traceability", node, [join(here, "check-commands.ts")]);