@eventmodelers/cli 1.0.45 → 1.0.46

package/stacks/opencqrs/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/opencqrs/templates/root/pom.xml

@@ -0,0 +1,139 @@
+<?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>OpenCQRS Quickstart</name>
+    <version>0.0.1-SNAPSHOT</version>
+
+    <properties>
+        <java.version>21</java.version>
+        <opencqrs.version>2.0.0</opencqrs.version>
+        <spring-boot.version>4.1.0</spring-boot.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-webmvc</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>
+
+        <!-- Spring Integration JDBC: backs the distributed lock registry EventHandlingProcessor uses for
+             leader election (exactly one instance processes a given group+partition at a time) -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-integration</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.integration</groupId>
+            <artifactId>spring-integration-jdbc</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+
+        <!-- OpenCQRS framework: command/event handling, EventSourcingDB client, Spring Boot auto-configuration -->
+        <dependency>
+            <groupId>com.opencqrs</groupId>
+            <artifactId>framework-spring-boot-starter</artifactId>
+            <version>${opencqrs.version}</version>
+        </dependency>
+
+        <!-- Auto-starts docker-compose.yml services (EventSourcingDB, 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>com.opencqrs</groupId>
+            <artifactId>framework-test</artifactId>
+            <version>${opencqrs.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- Spring Boot 4 test slices: @DataJpaTest (build-state-view/build-automation) and
+             @WebMvcTest (build-state-change's rest-api-patterns.md) 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-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/opencqrs/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/opencqrs/templates/root/src/main/java/com/example/quickstart/config/CqrsConfiguration.java

@@ -0,0 +1,74 @@
+package com.example.quickstart.config;
+
+import com.opencqrs.framework.eventhandler.progress.JdbcProgressTracker;
+import com.opencqrs.framework.persistence.EventSource;
+import com.opencqrs.framework.types.PreconfiguredAssignableClassEventTypeResolver;
+import java.util.Map;
+import javax.sql.DataSource;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.integration.jdbc.lock.DefaultLockRepository;
+import org.springframework.integration.jdbc.lock.JdbcLockRegistry;
+import org.springframework.integration.jdbc.lock.LockRepository;
+import org.springframework.transaction.PlatformTransactionManager;
+
+@Configuration
+public class CqrsConfiguration {
+
+    /**
+     * Identifies this service as the publisher of every event it appends (the CloudEvents {@code source}
+     * field). One fixed value for the whole service — not per-slice.
+     */
+    @Bean
+    public EventSource eventSource() {
+        return new EventSource("tag://quickstart");
+    }
+
+    /**
+     * Maps every event's stored {@code type} string to its Java class explicitly. Required for production —
+     * the default {@code ClassNameEventTypeResolver} fallback uses the fully-qualified Java classname as the
+     * stored type, which breaks the moment a class is renamed or moved package, and can't interoperate with
+     * non-Java event producers.
+     *
+     * <p><strong>Every event type used by any slice must be registered here.</strong> build-state-change and
+     * build-automation both add a line when they introduce a new event — see their SKILL.md for the exact
+     * step. Naming convention: {@code "quickstart.{context}.{event-name}.v1"}, lowercase, dot-separated.
+     */
+    @Bean
+    public PreconfiguredAssignableClassEventTypeResolver eventTypeResolver() {
+        return new PreconfiguredAssignableClassEventTypeResolver(Map.ofEntries(
+                // "quickstart.{context}.{eventname}.v1", {EventClass}.class
+                ));
+    }
+
+    /**
+     * Distributed-lock leader election, backed by the {@code EVENTHANDLER_LOCK} table (see schema.sql) —
+     * ensures exactly one running instance processes events for a given processing group + partition at a
+     * time when this service is scaled to multiple instances.
+     */
+    @Bean
+    public DefaultLockRepository defaultLockRepository(DataSource dataSource) {
+        var result = new DefaultLockRepository(dataSource);
+        result.setPrefix("EVENTHANDLER_");
+        return result;
+    }
+
+    @Bean
+    public JdbcLockRegistry jdbcLockRegistry(LockRepository lockRepository) {
+        return new JdbcLockRegistry(lockRepository);
+    }
+
+    /**
+     * Durable checkpoint per processing group + partition (see {@code EVENTHANDLER_PROGRESS} in schema.sql),
+     * so a restart or fail-over resumes exactly where the previous instance left off instead of re-processing
+     * or skipping events. {@code setProceedTransactionally(true)} lets an {@code @EventHandling} method
+     * participate in the same transaction as the checkpoint update, making that handler's side effect and its
+     * checkpoint advance atomic together.
+     */
+    @Bean
+    public JdbcProgressTracker jdbcProgressTracker(DataSource dataSource, PlatformTransactionManager transactionManager) {
+        var result = new JdbcProgressTracker(dataSource, transactionManager);
+        result.setProceedTransactionally(true);
+        return result;
+    }
+}

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

@@ -0,0 +1,23 @@
+spring.application.name=quickstart
+server.port=8080
+
+esdb.server.uri=http://localhost:3000
+esdb.server.api-token=${ESDB_API_TOKEN:secret}
+
+spring.datasource.url=jdbc:postgresql://localhost:5432/quickstart
+spring.datasource.username=quickstart
+spring.datasource.password=quickstart
+
+# Applies schema.sql (lock + progress tables) on every startup; JPA-mapped read model tables
+# are handled by Hibernate below, not by schema.sql.
+spring.sql.init.mode=always
+spring.jpa.hibernate.ddl-auto=update
+
+spring.docker.compose.enabled=true
+spring.docker.compose.file=docker-compose.yml
+
+management.endpoint.health.show-components=always
+
+# In-memory command-handling cache is fine for a single instance / local dev. Revisit for
+# multi-instance production deployments (see docs.opencqrs.com's Event Handling Processor reference).
+opencqrs.command-handling.cache.type=in_memory

package/stacks/opencqrs/templates/root/src/main/resources/schema.sql

@@ -0,0 +1,19 @@
+-- Backing tables for the distributed-lock leader election (EVENTHANDLER_LOCK, used by JdbcLockRegistry)
+-- and the durable event-handling checkpoint (EVENTHANDLER_PROGRESS, used by JdbcProgressTracker) —
+-- see com.example.quickstart.config.CqrsConfiguration. Verified against OpenCQRS's own reference
+-- application (framework-spring-boot-autoconfigure); portable as-is to PostgreSQL.
+CREATE TABLE IF NOT EXISTS EVENTHANDLER_LOCK (
+    LOCK_KEY CHAR(36) NOT NULL,
+    REGION VARCHAR(100) NOT NULL,
+    CLIENT_ID CHAR(36),
+    CREATED_DATE TIMESTAMP NOT NULL,
+    EXPIRED_AFTER TIMESTAMP NOT NULL,
+    CONSTRAINT EVENTHANDLER_LOCK_PK PRIMARY KEY (LOCK_KEY, REGION)
+);
+
+CREATE TABLE IF NOT EXISTS EVENTHANDLER_PROGRESS (
+    GROUP_KEY VARCHAR(100) NOT NULL,
+    PARTITION_ID BIGINT NOT NULL,
+    EVENT_ID VARCHAR(100) NOT NULL,
+    CONSTRAINT EVENTHANDLER_PROGRESS_PK PRIMARY KEY (GROUP_KEY, PARTITION_ID)
+);

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

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>OpenCQRS Quickstart</title>
+</head>
+<body>
+  <h1>OpenCQRS 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/supabase/templates/build-kit/CLAUDE.md

@@ -58,6 +58,31 @@ 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}/`
+or a webhook's `supabase/functions/{fn}/index.ts`. 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 the webhook's own edge
+  function) or a documented exception: `src/slices/{context}/{Context}Events.ts`,
+  `src/common/loadPostgresEventstore.ts`, or `supabase/config.toml`
+- **append-only-migrations** — `supabase/migrations/V{n}__*.sql` may only be **added**, never edited
+- **test-file-present** — a changed Command/Projection/processor file needs a sibling `*.test.ts`
+  (webhook edge functions are tested via `supabase functions serve`, not a test file — exempt)
+- **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
 
 ```

package/stacks/supabase/templates/build-kit/lib/check-commit-scope.cjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+'use strict';
+
+// Runner for the slice commit-scope guard. Loads every check module from
+// ./checks/*.cjs and runs it against the currently staged changeset.
+//
+// Check interface (see ./checks/README.md for the full contract + a template):
+//   module.exports = {
+//     name: 'my-check',              // short id, shown in violation output
+//     skipIfAlreadyFailing: false,   // optional — skip this check once an earlier
+//                                    // one has already failed (use for slow checks)
+//     run(ctx) {
+//       return [{ path: 'some/file.ts', reason: 'why this is a problem' }];
+//     },
+//   };
+// `run()` returns an array of violations (empty array/undefined/null = pass).
+//
+// `ctx` passed to every check:
+//   changes        [{status, path}] — staged files (git status letter + path)
+//   touchesSlice    true — this commit touches src/slices/{context}/{slice}/**
+//                   (the runner already gates on this before loading checks)
+//   repoRoot        absolute path to the repo root
+//   SLICE_PATTERN   RegExp matching a path inside a slice's own folder
+//
+// Zero dependencies — plain Node, so it works from git's pre-commit hook
+// (see ../../.githooks/pre-commit), from `npm run check:scope`, or from CI.
+// Invoked as: node .build-kit/lib/check-commit-scope.cjs
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const SLICE_PATTERN = /^src\/slices\/[^/]+\/[^/]+\//;
+// A webhook slice is a self-contained edge function with no src/slices/ folder
+// of its own — still counts as "this is a slice commit" for the gate below.
+const WEBHOOK_FUNCTION_PATTERN = /^supabase\/functions\/[^/]+\/index\.ts$/;
+
+function stagedChanges() {
+  const out = execSync('git diff --cached --name-status --no-renames', { encoding: 'utf8' });
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [status, ...rest] = line.split('\t');
+      return { status: status[0], path: rest.join('\t') };
+    });
+}
+
+function loadChecks() {
+  const checksDir = path.join(__dirname, 'checks');
+  if (!fs.existsSync(checksDir)) return [];
+  return fs
+    .readdirSync(checksDir)
+    .filter((f) => f.endsWith('.cjs'))
+    .sort() // numeric filename prefixes (00-, 10-, ...) control run order
+    .map((f) => {
+      let mod;
+      try {
+        mod = require(path.join(checksDir, f));
+      } catch (err) {
+        console.error(`check-commit-scope: failed to load checks/${f} — ${err.message}`);
+        return null;
+      }
+      if (typeof mod?.run !== 'function') {
+        console.error(`check-commit-scope: skipping checks/${f} — does not export { name, run(ctx) }`);
+        return null;
+      }
+      return { file: f, name: mod.name || f, run: mod.run, skipIfAlreadyFailing: !!mod.skipIfAlreadyFailing };
+    })
+    .filter(Boolean);
+}
+
+function main() {
+  let changes;
+  try {
+    changes = stagedChanges();
+  } catch (err) {
+    console.error('check-commit-scope: could not read staged changes —', err.message);
+    process.exit(1);
+  }
+
+  if (changes.length === 0) process.exit(0);
+
+  const touchesSlice = changes.some((c) => SLICE_PATTERN.test(c.path) || WEBHOOK_FUNCTION_PATTERN.test(c.path));
+  if (!touchesSlice) process.exit(0); // not a slice commit — nothing to enforce
+
+  const ctx = {
+    changes,
+    touchesSlice,
+    repoRoot: execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim(),
+    SLICE_PATTERN,
+  };
+
+  const checks = loadChecks();
+  const violations = [];
+  const claimedPaths = new Set(); // first check to flag a path wins — avoids repeat noise
+
+  for (const check of checks) {
+    if (check.skipIfAlreadyFailing && violations.length > 0) continue;
+
+    let result;
+    try {
+      result = check.run(ctx) || [];
+    } catch (err) {
+      violations.push({ path: '(check error)', reason: `[${check.name}] threw: ${err.message}` });
+      continue;
+    }
+
+    for (const v of result) {
+      if (claimedPaths.has(v.path)) continue;
+      claimedPaths.add(v.path);
+      violations.push({ path: v.path, reason: `[${check.name}] ${v.reason}` });
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error('\n❌ commit blocked — slice commit-scope guard found issues:\n');
+    for (const v of violations) console.error(`  - ${v.path} — ${v.reason}`);
+    console.error('\nSee .build-kit/lib/checks/ for what each check enforces.\n');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+main();

package/stacks/supabase/templates/build-kit/lib/checks/00-blocked-paths.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+// Rejects a slice commit that touches shared infra which must never change from
+// slice work: the package manifest/lockfiles (no new/changed dependencies) and
+// server.ts (routes/processors are auto-discovered — never wired there by hand).
+
+const BLOCKED = [
+  {
+    pattern: /^(package(-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|npm-shrinkwrap\.json)$/,
+    reason: 'dependency/package manifest changes are not allowed from a slice commit',
+  },
+  {
+    pattern: /^server\.ts$/,
+    reason: 'server.ts is shared infra (routes/processors are auto-discovered) — never touched by slice work',
+  },
+];
+
+module.exports = {
+  name: 'blocked-paths',
+  run(ctx) {
+    const violations = [];
+    for (const { path: p } of ctx.changes) {
+      const hit = BLOCKED.find((b) => b.pattern.test(p));
+      if (hit) violations.push({ path: p, reason: hit.reason });
+    }
+    return violations;
+  },
+};

package/stacks/supabase/templates/build-kit/lib/checks/10-slice-scope.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+// Everything staged in a slice commit must be inside the slice's own folder (or
+// a webhook's self-contained edge function), or one of the documented
+// shared-infra exceptions a slice legitimately registers *into* (never rewrites
+// wholesale). See build-kit/lib/AGENT.md and the build-state-view/
+// build-automation/build-webhook SKILL.md files for what a compliant edit to an
+// exception file looks like. Migration files have their own dedicated check
+// (20-append-only-migrations.cjs), so they're allowed through here.
+
+const WEBHOOK_FUNCTION_PATTERN = /^supabase\/functions\/[^/]+\/index\.ts$/;
+
+const ALLOWED_EXCEPTIONS = [
+  /^src\/slices\/[^/]+\/[A-Za-z0-9]+Events\.ts$/, // per-context event union (append-only)
+  /^src\/common\/loadPostgresEventstore\.ts$/, // projection registration / schema.migrate()
+  /^supabase\/config\.toml$/, // webhook function registration (verify_jwt entry)
+];
+
+const MIGRATION_PATTERN = /^supabase\/migrations\/V\d+__.*\.sql$/;
+
+module.exports = {
+  name: 'slice-scope',
+  run(ctx) {
+    const violations = [];
+    for (const { path: p } of ctx.changes) {
+      if (ctx.SLICE_PATTERN.test(p)) continue;
+      if (WEBHOOK_FUNCTION_PATTERN.test(p)) continue;
+      if (MIGRATION_PATTERN.test(p)) continue;
+      if (ALLOWED_EXCEPTIONS.some((r) => r.test(p))) continue;
+      violations.push({ path: p, reason: 'outside src/slices/{context}/{slice}/ and not a documented exception' });
+    }
+    return violations;
+  },
+};