@eventmodelers/cli 1.0.44 → 1.0.46

package/stacks/kurrent/templates/root/mvnw.cmd

@@ -0,0 +1,149 @@
+<# : batch portion
+@REM ----------------------------------------------------------------------------
+@REM Licensed to the Apache Software Foundation (ASF) under one
+@REM or more contributor license agreements.  See the NOTICE file
+@REM distributed with this work for additional information
+@REM regarding copyright ownership.  The ASF licenses this file
+@REM to you under the Apache License, Version 2.0 (the
+@REM "License"); you may not use this file except in compliance
+@REM with the License.  You may obtain a copy of the License at
+@REM
+@REM    http://www.apache.org/licenses/LICENSE-2.0
+@REM
+@REM Unless required by applicable law or agreed to in writing,
+@REM software distributed under the License is distributed on an
+@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@REM KIND, either express or implied.  See the License for the
+@REM specific language governing permissions and limitations
+@REM under the License.
+@REM ----------------------------------------------------------------------------
+
+@REM ----------------------------------------------------------------------------
+@REM Apache Maven Wrapper startup batch script, version 3.3.2
+@REM
+@REM Optional ENV vars
+@REM   MVNW_REPOURL - repo url base for downloading maven distribution
+@REM   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+@REM   MVNW_VERBOSE - true: enable verbose log; others: silence the output
+@REM ----------------------------------------------------------------------------
+
+@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0)
+@SET __MVNW_CMD__=
+@SET __MVNW_ERROR__=
+@SET __MVNW_PSMODULEP_SAVE=%PSModulePath%
+@SET PSModulePath=
+@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @(
+  IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B)
+)
+@SET PSModulePath=%__MVNW_PSMODULEP_SAVE%
+@SET __MVNW_PSMODULEP_SAVE=
+@SET __MVNW_ARG0_NAME__=
+@SET MVNW_USERNAME=
+@SET MVNW_PASSWORD=
+@IF NOT "%__MVNW_CMD__%"=="" (%__MVNW_CMD__% %*)
+@echo Cannot start maven from wrapper >&2 && exit /b 1
+@GOTO :EOF
+: end batch / begin powershell #>
+
+$ErrorActionPreference = "Stop"
+if ($env:MVNW_VERBOSE -eq "true") {
+  $VerbosePreference = "Continue"
+}
+
+# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties
+$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl
+if (!$distributionUrl) {
+  Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+}
+
+switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) {
+  "maven-mvnd-*" {
+    $USE_MVND = $true
+    $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip"
+    $MVN_CMD = "mvnd.cmd"
+    break
+  }
+  default {
+    $USE_MVND = $false
+    $MVN_CMD = $script -replace '^mvnw','mvn'
+    break
+  }
+}
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+if ($env:MVNW_REPOURL) {
+  $MVNW_REPO_PATTERN = if ($USE_MVND) { "/org/apache/maven/" } else { "/maven/mvnd/" }
+  $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace '^.*'+$MVNW_REPO_PATTERN,'')"
+}
+$distributionUrlName = $distributionUrl -replace '^.*/',''
+$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$',''
+$MAVEN_HOME_PARENT = "$HOME/.m2/wrapper/dists/$distributionUrlNameMain"
+if ($env:MAVEN_USER_HOME) {
+  $MAVEN_HOME_PARENT = "$env:MAVEN_USER_HOME/wrapper/dists/$distributionUrlNameMain"
+}
+$MAVEN_HOME_NAME = ([System.Security.Cryptography.MD5]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join ''
+$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME"
+
+if (Test-Path -Path "$MAVEN_HOME" -PathType Container) {
+  Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
+  exit $?
+}
+
+if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) {
+  Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl"
+}
+
+# prepare tmp dir
+$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile
+$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir"
+$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null
+trap {
+  if ($TMP_DOWNLOAD_DIR.Exists) {
+    try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+    catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+  }
+}
+
+New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null
+
+# Download and Install Apache Maven
+Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+Write-Verbose "Downloading from: $distributionUrl"
+Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+$webclient = New-Object System.Net.WebClient
+if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) {
+  $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD)
+}
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum
+if ($distributionSha256Sum) {
+  if ($USE_MVND) {
+    Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties."
+  }
+  Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash
+  if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) {
+    Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property."
+  }
+}
+
+# unzip and move
+Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null
+Rename-Item -Path "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" -NewName $MAVEN_HOME_NAME | Out-Null
+try {
+  Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null
+} catch {
+  if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) {
+    Write-Error "fail to move MAVEN_HOME"
+  }
+} finally {
+  try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+  catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+}
+
+Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"

package/stacks/kurrent/templates/root/pom.xml

@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>com.example.quickstart</groupId>
+    <artifactId>quickstart</artifactId>
+    <name>Kurrent Quickstart</name>
+    <version>0.0.1-SNAPSHOT</version>
+
+    <properties>
+        <java.version>21</java.version>
+        <kurrentdb.version>1.2.1</kurrentdb.version>
+        <spring-boot.version>4.1.0</spring-boot.version>
+        <!-- Must track whatever version kurrentdb-client itself pulls in transitively (grpc-api is
+             runtime-scope only there) — check `mvn dependency:tree | grep grpc` after bumping
+             kurrentdb.version, and bump this to match. -->
+        <grpc.version>1.80.0</grpc.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-webmvc</artifactId>
+        </dependency>
+
+        <!-- Classic Jackson 2 (com.fasterxml.jackson.core), for hand-serializing event payloads
+             (LibraryEventTypes and friends) with the same ObjectMapper the kurrentdb-client's own
+             samples use. Spring Boot 4 moved its own internal JSON handling to Jackson 3
+             (tools.jackson.core) and only pulls classic Jackson 2 in at *runtime* scope, transitively
+             via kurrentdb-client itself — not on the compile classpath by default. Declared explicitly,
+             version still resolved from Spring Boot's dependency-management BOM. -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+
+        <!-- Read model persistence: Spring Data JPA + PostgreSQL, default for all projections -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.postgresql</groupId>
+            <artifactId>postgresql</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+
+        <!-- KurrentDB Java client (plain SDK — no Spring Boot auto-configuration of its own,
+             see config.KurrentConfiguration for the beans this project wires by hand) -->
+        <dependency>
+            <groupId>io.kurrent</groupId>
+            <artifactId>kurrentdb-client</artifactId>
+            <version>${kurrentdb.version}</version>
+        </dependency>
+
+        <!-- io.grpc.Status/StatusRuntimeException — needed at compile scope to detect an
+             ALREADY_EXISTS conflict when idempotently creating a persistent-subscription group
+             (see build-state-view/build-automation). Only pulled in transitively by
+             kurrentdb-client at *runtime* scope otherwise. -->
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-api</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+
+        <!-- Auto-starts docker-compose.yml services (KurrentDB, Postgres) on app run -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-docker-compose</artifactId>
+            <scope>runtime</scope>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Testing -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- Spring Boot 4 test slices: @DataJpaTest and @WebMvcTest each moved to their own artifact -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-data-jpa-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-webmvc-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-testcontainers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers-postgresql</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers-junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                    <parameters>true</parameters>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-dependencies</artifactId>
+                <version>${spring-boot.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+</project>

package/stacks/kurrent/templates/root/src/main/java/com/example/quickstart/QuickstartApplication.java

@@ -0,0 +1,12 @@
+package com.example.quickstart;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class QuickstartApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(QuickstartApplication.class, args);
+    }
+}

package/stacks/kurrent/templates/root/src/main/java/com/example/quickstart/common/EventStore.java

@@ -0,0 +1,91 @@
+package com.example.quickstart.common;
+
+import io.kurrent.dbclient.*;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+import java.util.concurrent.ExecutionException;
+
+/**
+ * Thin wrapper around {@link KurrentDBClient} shared by every write slice — reads a stream into a
+ * plain list (or empty, if the stream doesn't exist yet) and appends events, translating the client's
+ * checked/wrapped exceptions into unchecked ones so slice code doesn't repeat this boilerplate.
+ *
+ * <p>This project has no CQRS framework layer (unlike the OpenCQRS/Axon kits) — this class, plus each
+ * slice's own {@code decide}/{@code evolve} functions, is the entire "framework". See
+ * {@code .build-kit/CLAUDE.md} for the full convention.
+ */
+@Component
+public class EventStore {
+
+    private final KurrentDBClient client;
+
+    public EventStore(KurrentDBClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Reads every event in {@code streamId}, forwards from the start. Returns
+     * {@link StreamEvents#empty()} if the stream doesn't exist yet — this is the normal, expected case
+     * for a creation command, not an error.
+     */
+    public StreamEvents read(String streamId) {
+        try {
+            ReadResult result = client.readStream(streamId, ReadStreamOptions.get().forwards().fromStart()).get();
+            return new StreamEvents(result.getEvents(), result.getLastStreamPosition());
+        } catch (ExecutionException e) {
+            if (e.getCause() instanceof StreamNotFoundException) {
+                return StreamEvents.empty();
+            }
+            throw new EventStoreException(e.getCause());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new EventStoreException(e);
+        }
+    }
+
+    /**
+     * Appends {@code events} to {@code streamId} under the given {@code expectedState} (see
+     * {@link StreamState#noStream()}/{@link StreamState#streamRevision(long)}/etc). Throws
+     * {@link WrongExpectedVersionException} directly (unwrapped) on an optimistic-concurrency
+     * conflict — callers decide for themselves whether that's a real conflict (map it to HTTP 409) or
+     * an expected redelivery to swallow (see build-automation's SKILL.md).
+     */
+    public WriteResult append(String streamId, StreamState expectedState, List<EventData> events) {
+        try {
+            AppendToStreamOptions options = AppendToStreamOptions.get().streamState(expectedState);
+            return client.appendToStream(streamId, options, events.toArray(new EventData[0])).get();
+        } catch (ExecutionException e) {
+            if (e.getCause() instanceof WrongExpectedVersionException wrongExpectedVersion) {
+                throw wrongExpectedVersion;
+            }
+            throw new EventStoreException(e.getCause());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new EventStoreException(e);
+        }
+    }
+
+    public record StreamEvents(List<ResolvedEvent> events, long lastStreamPosition) {
+        private static final long NO_STREAM_POSITION = -1;
+
+        public static StreamEvents empty() {
+            return new StreamEvents(List.of(), NO_STREAM_POSITION);
+        }
+
+        public boolean isEmpty() {
+            return events.isEmpty();
+        }
+
+        /** The {@link StreamState} to append under, given this stream's current position. */
+        public StreamState expectedState() {
+            return isEmpty() ? StreamState.noStream() : StreamState.streamRevision(lastStreamPosition);
+        }
+    }
+
+    public static class EventStoreException extends RuntimeException {
+        public EventStoreException(Throwable cause) {
+            super(cause);
+        }
+    }
+}

package/stacks/kurrent/templates/root/src/main/java/com/example/quickstart/config/KurrentConfiguration.java

@@ -0,0 +1,42 @@
+package com.example.quickstart.config;
+
+import io.kurrent.dbclient.ConnectionStringParsingException;
+import io.kurrent.dbclient.KurrentDBClient;
+import io.kurrent.dbclient.KurrentDBClientSettings;
+import io.kurrent.dbclient.KurrentDBConnectionString;
+import io.kurrent.dbclient.KurrentDBPersistentSubscriptionsClient;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * The KurrentDB Java client ({@code kurrentdb-client}) ships no Spring Boot auto-configuration of its
+ * own (unlike OpenCQRS's {@code framework-spring-boot-starter}) — it is a plain SDK. These beans are
+ * this project's own wiring, not a vendor-provided starter.
+ */
+@Configuration
+public class KurrentConfiguration {
+
+    @Value("${kurrentdb.connection-string}")
+    private String connectionString;
+
+    /**
+     * A single client instance is safe to share as a singleton across the whole application — it does
+     * not need to be opened/closed per request (see the client's own getting-started guide).
+     */
+    @Bean(destroyMethod = "shutdown")
+    public KurrentDBClient kurrentDBClient() throws ConnectionStringParsingException {
+        KurrentDBClientSettings settings = KurrentDBConnectionString.parseOrThrow(connectionString);
+        return KurrentDBClient.create(settings);
+    }
+
+    /**
+     * Separate client for managing/consuming persistent subscriptions — used by build-state-view and
+     * build-automation slices, not by build-state-change (which only appends/reads streams directly).
+     */
+    @Bean(destroyMethod = "shutdown")
+    public KurrentDBPersistentSubscriptionsClient kurrentDBPersistentSubscriptionsClient() throws ConnectionStringParsingException {
+        KurrentDBClientSettings settings = KurrentDBConnectionString.parseOrThrow(connectionString);
+        return KurrentDBPersistentSubscriptionsClient.create(settings);
+    }
+}

package/stacks/kurrent/templates/root/src/main/resources/application.properties

@@ -0,0 +1,14 @@
+spring.application.name=quickstart
+server.port=8080
+
+kurrentdb.connection-string=${KURRENTDB_CONNECTION_STRING:kurrentdb://localhost:2113?tls=false}
+
+spring.datasource.url=jdbc:postgresql://localhost:5432/quickstart
+spring.datasource.username=quickstart
+spring.datasource.password=quickstart
+spring.jpa.hibernate.ddl-auto=update
+
+spring.docker.compose.enabled=true
+spring.docker.compose.file=docker-compose.yml
+
+management.endpoint.health.show-components=always

package/stacks/kurrent/templates/root/src/main/resources/static/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Kurrent Quickstart</title>
+</head>
+<body>
+  <h1>Kurrent Quickstart</h1>
+  <p>Backend is running. Slices built from the event model board are wired up under their own REST paths.</p>
+</body>
+</html>

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-core-rules/SKILL.md

@@ -41,7 +41,7 @@ automation slice   = EVENT(s) → AUTOMATION → COMMAND → EVENT(s)
 
 A slice never mixes a COMMAND and a READMODEL — those are two different slice types (`state-change` and `state-view`), even when they belong to the same feature. Slices are independently deployable and only communicate with each other via events.
 
-Slices are not placed directly — they're **derived** from a completed model. Every COMMAND on the board implies a `state-change` slice, every READMODEL implies a `state-view` slice, every AUTOMATION implies an `automation` slice. `eventmodeling-slicing-event-models` makes that implicit structure explicit on the board once modeling is done; it never invents a slice that isn't already implied by an element that's there.
+Slices are not placed directly — they're **derived** from a completed model. Every COMMAND on the board implies a `state-change` slice, every READMODEL implies a `state-view` slice, every AUTOMATION implies an `automation` slice — **except** a `linkedTo` copy (see Linked Copies below), which implies no slice of its own: it's the same underlying COMMAND/EVENT/READMODEL reused elsewhere on the board, not a second independently-deployable thing, so only the origin node's column gets a `SLICE_BORDER`. `eventmodeling-slicing-event-models` makes that implicit structure explicit on the board once modeling is done; it never invents a slice that isn't already implied by an element that's there, and skips columns whose only COMMAND/READMODEL is a linked copy.
 
 ## Elements
 
@@ -116,7 +116,7 @@ When an element's natural column is already occupied by something else, insert a
 
 A later EVENT sometimes needs to change data an earlier READMODEL already shows on a SCREEN — e.g. a cancellation affecting an "active items" view placed several columns earlier. Wiring that later EVENT straight back into the existing READMODEL is never the fix: it's a backward connection, and the platform only accepts a backward `EVENT → READMODEL` edge when the READMODEL already has a `READMODEL → AUTOMATION` edge (the todo-list pattern — see Translation Chain below). A READMODEL that only feeds a SCREEN never qualifies for that exemption.
 
-Instead, place a **new READMODEL node** in a new column **immediately after** the later event's column, connect that event forward into it, and give it a matching SCREEN in that same new column — same screen name/title as the earlier one, showing the updated data, optionally re-marked/highlighted via `html-screen`'s Marks feature to call out what changed. Leave the earlier READMODEL/SCREEN instance exactly as it is — it's still what that earlier point in the timeline correctly showed. Never delete it, and never wire the new instance back to it: this isn't the `linkedTo` copy mechanism below (that's for reusing one fact across timelines) — it's a genuinely new node representing a genuinely later state.
+Instead, place a **new READMODEL node** in a new column **immediately after** the later event's column, then link it to the earlier READMODEL instance via the `linkedTo` copy mechanism below (`link_element`) — it *is* the same read model, carried forward to a later state, not an unrelated new one, so it uses the same copy mechanism as any other reused fact. Connect the later event forward into the linked copy, then update whichever field(s) that event actually changes (e.g. `status`) on the copy — the fields it inherited from the link that the new event doesn't touch stay as copied. Give it a matching SCREEN in that same new column — same screen name/title as the earlier one, showing the updated data, optionally re-marked/highlighted via `html-screen`'s Marks feature to call out what changed. A SCREEN can never itself be a `linkedTo` copy (the mechanism only supports COMMAND/EVENT/READMODEL), so the new SCREEN is placed as a plain node matching the earlier one's title, not linked. Leave the earlier READMODEL/SCREEN instance exactly as it is — it's still what that earlier point in the timeline correctly showed. Never delete it.
 
 See `eventmodeling-identifying-outputs` Step 5g for the full placement/wiring mechanics, and `place-element` Step 6 for the column-insertion mechanics.
 
@@ -126,6 +126,8 @@ A **linked copy** is a COMMAND/EVENT/READMODEL node that mirrors another node el
 
 To make one: place a normal new node of the same type (COMMAND/EVENT/READMODEL only) at the target spot, then link it to the origin (`link_element`, or the REST `.../nodes/:nodeId/link` fallback). This replaces the new node's `meta` with a full copy of the origin's and sets `meta.linkedTo` to the origin's node id — the authoritative pointer (a `data.linkedTo` also exists but is a rendering mirror only, not the source of truth). Wire the resulting copy to its own neighbors normally afterward.
 
+A linked copy is allowed to diverge from its origin afterward in the specific field(s) a newly-connected event actually drives — e.g. the "Updating a Read Model That Already Feeds a Screen" copy above, where `status` is updated post-link to the event's new value. The link establishes "this is the same underlying fact, not a duplicate" at creation time; it doesn't freeze the copy's fields identical to the origin's forever.
+
 Never delete the original (the node with no `linkedTo`) once copies of it exist — copies reference it, and removing it breaks every copy. `eventmodeling-checking-completeness` already treats any `linkedTo`-marked node as an intentional copy, never a duplicate or missing-slice gap to flag.
 
 See `place-element` Step 6a for the mechanical linking steps.

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-outputs/SKILL.md

@@ -314,7 +314,7 @@ For each view screen S that queries this read model as its primary read model:
 
 **View screens normally share the column of the (primary) read model they display** — either because they were placed there in Step 3, or because the read model was placed into the screen's own column just now (per the check above). A screen's own position is never moved to resolve a read model placement conflict — when the shared column isn't available, the **read model** gets a new column immediately before the screen's, not the other way around (this preserves the screen's narrative order from Step 3).
 
-**The same rule applies to `EVENT → READMODEL`** (shared statement: `eventmodeling-core-rules`'s "Updating a Read Model That Already Feeds a Screen"). If a later event needs to update data a read model already feeds to a SCREEN, do not connect that later event back into the existing read model — the platform only accepts an `EVENT → READMODEL` backward connection when the read model already has a `READMODEL → AUTOMATION` edge (the todo-list pattern from Step 4b, `eventmodeling-designing-automation-chains`). For any read model feeding a SCREEN, resolve the update the same way Step 5c resolves multi-component screens: place a **new copy of the read model** in a new column immediately after the later event's column, connect the later event forward into that copy, and place a matching copy of the same screen there — same title, updated data, optionally re-marked/highlighted via `html-screen`'s Marks feature. Never link the new copy back to the earlier read model instance.
+**The same rule applies to `EVENT → READMODEL`** (shared statement: `eventmodeling-core-rules`'s "Updating a Read Model That Already Feeds a Screen"). If a later event needs to update data a read model already feeds to a SCREEN, do not connect that later event back into the existing read model — the platform only accepts an `EVENT → READMODEL` backward connection when the read model already has a `READMODEL → AUTOMATION` edge (the todo-list pattern from Step 4b, `eventmodeling-designing-automation-chains`). For any read model feeding a SCREEN, resolve the update the same way Step 5c resolves multi-component screens: place a **new READMODEL node** in a new column immediately after the later event's column, then link it to the earlier read model instance (`link_element` — it's the same read model carried forward, not an unrelated new one; see `eventmodeling-core-rules`'s Linked Copies section). Connect the later event forward into the linked copy, then update the field(s) that event actually changes. Place a matching SCREEN in that same new column — same title, updated data, optionally re-marked/highlighted via `html-screen`'s Marks feature; a SCREEN can't be a `linkedTo` copy itself (COMMAND/EVENT/READMODEL only), so place it as a plain node matching the earlier screen's title.
 
 ### Step 5h — Wire connections after placing each READMODEL (and its SCREEN)
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-orchestrating-event-modeling/SKILL.md

@@ -122,7 +122,7 @@ The timeline must always progress left-to-right — this is the goal to design t
 
 **`EVENT → READMODEL` has exactly one exception, and it is narrow.** A read model that already carries a `READMODEL → AUTOMATION` edge — i.e. a todo-list read model feeding an automation, per `eventmodeling-designing-automation-chains` (Step 4b) — may also be fed by a later-column event closing an item it opened earlier. That accumulator shape is what the todo-list pattern exists for, and it is confirmed against the platform API (`learn-eventmodelers-api` §3 — `POST .../connections`). **Outside that one case, the platform rejects the connection, for good reason:** without it, a read model would become a moving target for whatever screen or scenario later reaches back into it.
 
-For every other read model — in particular one feeding a SCREEN rather than an AUTOMATION — never connect a later event back into it, no matter how convenient. If a later event needs to update what a screen already shows, resolve it the same way Step 5c resolves multi-component screens: place a **new copy of the read model** in a new column immediately after the later event's column, connect the later event forward into that copy, and place a matching copy of the same screen there (same title, updated data, optionally re-marked/highlighted per `html-screen`'s Marks feature). Never link the new copy back to the earlier instance.
+For every other read model — in particular one feeding a SCREEN rather than an AUTOMATION — never connect a later event back into it, no matter how convenient. If a later event needs to update what a screen already shows, resolve it the same way Step 5c resolves multi-component screens: place a **new READMODEL node** in a new column immediately after the later event's column, link it to the earlier instance (`link_element` — it's the same read model, not an unrelated new one; see `eventmodeling-core-rules`'s Linked Copies section), connect the later event forward into the linked copy, update the field(s) that event actually changes, and place a matching copy of the same screen there (same title, updated data, optionally re-marked/highlighted per `html-screen`'s Marks feature — a SCREEN can't itself be linked, so it's a plain node matching the earlier one's title).
 
 A wide fan-in read model (many connected events, one column) is a different problem with a different fix — see "one read model per component" and the >3-events heuristic above. It is never a justification for a backward arrow. The one real signal to treat as a prunable connection regardless of column position is a **connected event that isn't actually used by any field** on the read model.
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-slicing-event-models/SKILL.md

@@ -39,6 +39,8 @@ Walk the timeline column by column:
 - Every **READMODEL** → one `state-view` slice, named after the read model
 - Every **AUTOMATION** → one `automation` slice, named after the automation (or the command it issues)
 
+**Skip any column whose only COMMAND/READMODEL node has `meta.linkedTo` set** — it's a linked copy of a node elsewhere on the board (see `eventmodeling-core-rules`'s Linked Copies and Slices sections), not a second independently-deployable thing. Only the origin node's own column gets a slice.
+
 ---
 
 ## Step 1: Resolve the Timeline

package/stacks/modeling-kit/templates/.claude/skills/place-element/SKILL.md

@@ -226,7 +226,7 @@ Use this REST call (see the curl fallback below) when you don't already have fre
 | Any | Same element type | Stop and tell the user — true conflict, no safe default. |
 | Any | Different type but not a known pairing | Stop and tell the user. |
 
-**A later EVENT that needs to update a READMODEL already feeding a SCREEN is not a Step 6 occupancy case — it's a backward-connection trap.** Do not `set_connection` that EVENT into the existing READMODEL, even if the existing READMODEL's column is reachable. See `eventmodeling-core-rules`'s "Updating a Read Model That Already Feeds a Screen": place a **new** READMODEL (and a matching SCREEN) in a new column immediately after the event's column instead, and connect the event forward into that new pair.
+**A later EVENT that needs to update a READMODEL already feeding a SCREEN is not a Step 6 occupancy case — it's a backward-connection trap.** Do not `set_connection` that EVENT into the existing READMODEL, even if the existing READMODEL's column is reachable. See `eventmodeling-core-rules`'s "Updating a Read Model That Already Feeds a Screen": place a **new** READMODEL in a new column immediately after the event's column instead, link it to the existing READMODEL as a `linkedTo` copy (Step 6a below — it's the same read model, not an unrelated new one), connect the event forward into the linked copy, and give it a matching SCREEN in the same column (a plain node, not linked — SCREEN isn't a linkable type).
 
 **Insert immediately after** means: create the new column right after the current one, not by appending to the end. This keeps the read model visually adjacent to the event that drives it.
 

package/stacks/node/templates/build-kit/CLAUDE.md

@@ -57,6 +57,28 @@ When asked to build a slice, always follow this flow:
 
 After you are done, automatically run the tests for the slice that was edited.
 
+## Commit Scope Guard
+
+A pre-commit hook (`.githooks/pre-commit`, installed via `init --hooks` — see its own project's setup)
+runs `.build-kit/lib/check-commit-scope.cjs` on every commit that touches `src/slices/{context}/{slice}/`.
+It loads every check under `.build-kit/lib/checks/` and rejects the commit if any of them find a problem:
+
+- **blocked-paths** — `package.json`/lockfiles and `server.ts` are never touched by slice work
+- **slice-scope** — everything staged must be inside the slice folder or a documented exception:
+  `src/slices/{context}/{Context}Events.ts` or `src/common/loadPostgresEventstore.ts`
+- **append-only-migrations** — `migrations/V{n}__*.sql` may only be **added**, never edited
+- **test-file-present** — a changed Command/Projection/processor file needs a sibling `*.test.ts`
+- **no-invented-fields** — heuristic: flags a field used in code that isn't declared anywhere in
+  `.build-kit/.slices/{context}/{slice}/slice.json`
+- **spec-coverage** — heuristic: the test file needs at least as many `it(...)` blocks as slice.json
+  has `specifications[]` entries
+- **tsc-build** — `npx tsc --noEmit` must still pass
+
+If a commit is rejected, split it — commit the out-of-scope file separately from the slice work, or add
+the missing test/fix the field — rather than passing `--no-verify`. Run `npm run check:scope` any time
+you want to check staged files before committing. To add a new check, read
+`.build-kit/lib/checks/README.md` and drop in a file following its interface — no other wiring needed.
+
 ## Example Slice Structure
 
 ```