@eventmodelers/cli 1.0.45 → 1.0.47

package/stacks/modeling-kit/templates/.claude/skills/handle-comment/SKILL.md

@@ -21,20 +21,29 @@ From `$ARGUMENTS` or the calling skill's context, extract:
 | `nodeId` | UUID of the target node | **required** |
 | `text` | Comment text (place) or substring to match (resolve/delete) | required for `place`; used to look up comment when `commentId` is absent |
 | `commentId` | UUID of the comment to resolve/delete | preferred over `text` for resolve/delete |
-| `type` | `COMMENT`, `TASK`, or `QUESTION` | `QUESTION` (place only) |
-| `author` | Author identifier string | `agent` (place only) |
+| `type` | `COMMENT` or `TASK` | `COMMENT` (place only) |
+| `author` | Author identifier string | `agent-$CLAUDE_CODE_SESSION_ID` (place only) |
 | `boardId` | Board UUID | from `connect` skill (`BOARD_ID`) |
 
+Use the session env var, not the literal string `agent` — `CLAUDE_CODE_SESSION_ID` is set by the
+host for every session, so two agents working the same board at once post under distinguishable
+authors instead of an identical one. If the env var is unset (non-Claude-Code host), fall back to
+the literal `agent`.
+
+There is no `QUESTION` type at the API level — a question is just a `COMMENT` whose text happens
+to be phrased as a question. Callers that want to flag something as a question should word the
+`text` accordingly, not pass a special `type`.
+
 Route to the matching section below based on `action`.
 
 ---
 
 ## Action: place
 
-**Prefer MCP** — one call, `type` (`COMMENT`/`TASK`/`QUESTION`) passed straight through:
+**Prefer MCP** — one call, `type` (`COMMENT`/`TASK`) passed straight through:
 
 ```
-mcp__eventmodelers__add_comment { "boardId": "$BOARD_ID", "nodeId": "$NODE_ID", "text": "<text>", "type": "<COMMENT|TASK|QUESTION>", "author": "<author>" }
+mcp__eventmodelers__add_comment { "boardId": "$BOARD_ID", "nodeId": "$NODE_ID", "text": "<text>", "type": "<COMMENT|TASK>", "author": "<author>" }
 ```
 
 **Fallback (no MCP):** see `references/api-fallback.md` — "Action: place".

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

@@ -376,9 +376,9 @@ Count inbound edges where `target === COMMAND_NODE_ID` and the source node is ty
 mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "source": "<extra-issuer-node-id>", "target": "<COMMAND_NODE_ID>", "action": "remove" }
 ```
 
-If it's not clear which edge is the deliberate one (e.g. neither source sits in the COMMAND's own column), do not guess — leave both edges and post a `QUESTION` comment on the COMMAND node via `handle-comment` instead, describing the ambiguity.
+If it's not clear which edge is the deliberate one (e.g. neither source sits in the COMMAND's own column), do not guess — leave both edges and post a comment on the COMMAND node via `handle-comment` instead, describing the ambiguity.
 
-**Fallback (no MCP)**: there is no documented single-purpose REST endpoint for edge removal outside `/nodes/events`. Connect MCP via the `connect` skill first; if that's genuinely not possible, skip the auto-fix and post a `QUESTION` comment on the COMMAND node flagging the double issuer for manual resolution instead of fabricating a payload.
+**Fallback (no MCP)**: there is no documented single-purpose REST endpoint for edge removal outside `/nodes/events`. Connect MCP via the `connect` skill first; if that's genuinely not possible, skip the auto-fix and post a comment on the COMMAND node flagging the double issuer for manual resolution instead of fabricating a payload.
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: wdyt
-description: Business analyst exploration of an event model board. Reads all slices, analyzes them from a business perspective, and posts questions/observations as QUESTION-type comments on relevant nodes. Findings about a relationship between elements or a cluster of elements are always additionally drawn on the canvas (arrows, group loops) — comments carry every textual question, drawings carry every visual/structural hint.
+description: Business analyst exploration of an event model board. Reads all slices, analyzes them from a business perspective, and posts questions/observations as comments on relevant nodes. Findings about a relationship between elements or a cluster of elements are always additionally drawn on the canvas (arrows, group loops) — comments carry every textual question, drawings carry every visual/structural hint.
 ---
 
 # WDYT — What Do You Think?
@@ -113,17 +113,17 @@ Each of these four is inherently about a relationship or cluster of elements, so
 
 The two channels have a strict division of labor, always applied the same way — never swap them:
 
-- **Every textual question is a comment.** If the finding is "what happens / who does this / what do we expect" about a single element, it is worded and lives only in a `QUESTION` comment. Never draw a text callout on the canvas to carry a question — that content belongs in 4.1, full stop.
+- **Every textual question is a comment.** If the finding is "what happens / who does this / what do we expect" about a single element, it is worded and lives only in a comment. Never draw a text callout on the canvas to carry a question — that content belongs in 4.1, full stop.
 - **Every visual/structural hint is a drawing.** If the finding is inherently about *where things are relative to each other* — a relationship between two elements, or a cluster of elements sharing one concern — it is always additionally drawn on the canvas (4.2), not left as text alone. This isn't a selective "top 3" step; it's determined by the shape of the finding itself: relational or clustered → draw it, every time.
 
 ### 4.1 Comments (every textual question, always)
 
-For each question you want to ask, post it as a `QUESTION`-type comment on the most relevant node (the COMMAND, EVENT, SCREEN, or READMODEL the question is about). If a question is about the whole slice rather than a specific element, post it on the first/primary EVENT of the slice.
+For each question you want to ask, post it as a comment on the most relevant node (the COMMAND, EVENT, SCREEN, or READMODEL the question is about). If a question is about the whole slice rather than a specific element, post it on the first/primary EVENT of the slice.
 
 Use the `handle-comment` skill with `action=place` to post each comment. Pass:
 - `nodeId` — the UUID of the element the question is about
 - `text` — your question (one sentence, plain business language)
-- `type` — `QUESTION`
+- `type` — `COMMENT` (there is no separate question type — the text itself carries the question)
 - `author` — `wdyt`
 
 The comment API has no batch endpoint — `handle-comment` sends one request per comment. Fire them sequentially.
@@ -137,7 +137,7 @@ Use `POST /api/org/{orgId}/boards/{boardId}/drawing/draw` (auth headers same as
 - **Arrow** (`kind: "path"`, `arrowEnd: true`) — the concern is about a missing or unclear relationship *between two elements* (e.g. "does this event actually reach this automation?"). Draw a straight line from one element's position to the other's. `path` is `M 0 0 L <dx> <dy>` in the box's own local coordinates; `x`/`y`/`width`/`height` describe that box in canvas space (so `width`/`height` = the delta between the two elements' positions). Get element positions from the slice data already loaded in Step 2 (or `GET .../nodes/{nodeId}` if not present).
 - **Group loop** (`kind: "rect"`, drawn around a computed bounding box) — the concern spans a *cluster* of elements together (e.g. "this whole flow assumes nothing ever fails"). There's no dedicated group endpoint — union the elements' own `x`/`y`/`width`/`height` (plus some padding) yourself and draw one `rect` around that box via `.../drawing/draw`. This is a visual grouping only — unrelated to the `MODEL_CONTEXT` node type; never touch a `modelContext` field to satisfy this.
 
-Every arrow/group loop is paired with a `QUESTION` comment on the relevant node(s) from 4.1 — the drawing makes the concern visible at a glance on the canvas itself, the comment carries the actual worded question. Post both; neither replaces the other.
+Every arrow/group loop is paired with a comment on the relevant node(s) from 4.1 — the drawing makes the concern visible at a glance on the canvas itself, the comment carries the actual worded question. Post both; neither replaces the other.
 
 A finding about a single element with no relational or cluster dimension gets a comment only — don't manufacture an arrow or loop for it just to add a drawing.
 

package/stacks/modeling-kit/templates/kit/AGENTS.md

@@ -4,7 +4,7 @@ Reusable learnings accumulated while processing prompts for this board. Append n
 ones in a compressed, reusable form; only add if not already covered here.
 
 - `/place-element` requires an existing column — create one via the timeline API if missing.
-- `/wdyt` posts QUESTION comments onto nodes — use for analysis only, not modifications.
+- `/wdyt` posts comments onto nodes — use for analysis only, not modifications.
 - The `board_id`, `timeline_id`, and `organization_id` from each prompt provide full context — pass them to skills that need them.
 - If a prompt's `context.timelineId` is present and non-null, it overrules the prompt's own `timeline_id` field — it's the chapter the user was pointing at on the canvas, which can differ from whatever chapter the prompt/voice session was scoped to. Resolve `TIMELINE_ID` from `context.timelineId` first, falling back to `timeline_id` only when it's absent, before passing it to any skill.
 - Same pattern for node references: if a prompt's `context.selectedNodes` array is present and non-empty, its first entry overrules the prompt's own `node_id` field (e.g. for `/handle-comment`'s `nodeId`) — it reflects the actual canvas selection at prompt time, whereas `node_id` is only set when the prompt originated from a specific node/comment.

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -42,9 +42,9 @@ At the start of every session, read `.agent-modeling-kit/AGENTS.md` if it exists
 5. **Invoke the matched skill — never substitute direct tool calls for it.** Execute the prompt using the skill matched in the Skill Selection table below, passing the resolved `TIMELINE_ID`, `NODE_ID`, and `CELL_ID` from step 3 as that skill's `timelineId`/node-reference/`cellName` arguments (not the raw `timeline_id`/`node_id` fields, and not a cell reference parsed from the prompt text). For a skill like `/place-element` that accepts a `cellName`, pass the resolved `CELL_ID` as `cellName` whenever it's present — skip parsing the prompt text for a cell reference entirely in that case.
 
    `mcp__eventmodelers__*` tools (and the REST fallback) are building blocks a skill calls *internally* once you've invoked it — they are not a substitute for invoking the skill. Being able to see `mcp__eventmodelers__get_node`/`create_slice`/etc. in your tool list does not mean you should reach for them directly to satisfy a prompt that matches a row in the Skill Selection table: e.g. "add the next slice" always goes through `/eventmodeling-slicing-event-models` (falling through to `/add-next-slice` when nothing existing is left to slice) or `/place-element`, even though technically a couple of raw MCP calls could produce something on the board. The skill is what encodes the actual domain reasoning (which node type follows which, naming, field derivation, dependency notes) — a raw tool call skips all of that and produces a shallower result even when it "works." Only call MCP/REST directly when no row in the table matches the prompt's intent at all.
-   **Questioning rule**: you are running autonomously — no human is available to answer questions. If you need clarification, do not pause or ask interactively — post a `QUESTION`-type comment (`/handle-comment` with `action=place`, `type=QUESTION`) on the most relevant node. Then:
+   **Questioning rule**: you are running autonomously — no human is available to answer questions. If you need clarification, do not pause or ask interactively — post a comment (`/handle-comment` with `action=place`, `type=COMMENT`) on the most relevant node. Then:
    - If a reasonable default interpretation exists, continue with it.
-   - If it doesn't — the prompt is ambiguous enough that any guess risks doing the wrong thing — stop instead of guessing. Skip straight to step 6 and mark the prompt `DONE` with a comment explaining what's unclear and pointing to the `QUESTION` comment you just posted. Never leave a prompt neither progressed nor closed.
+   - If it doesn't — the prompt is ambiguous enough that any guess risks doing the wrong thing — stop instead of guessing. Skip straight to step 6 and mark the prompt `DONE` with a comment explaining what's unclear and pointing to the comment you just posted. Never leave a prompt neither progressed nor closed.
 6. **Mark the prompt as finished** — invoke `/update-prompt-status` with this turn's `prompt_id`, `newStatus=DONE`, and a `comment` that summarizes what you actually did (e.g. "Added the OrderPlaced event and wired it to the read model"). Do this once, right after the work is done — not per skill call within the turn.
 7. If this turn has a `comment_id` field, invoke `/handle-comment` with `action=resolve`, `nodeId` from the resolved `NODE_ID` (step 3), `commentId` from `comment_id`.
 8. Append a progress entry to `progress.txt` — see the Progress Entry Format below. Fill in the `Learnings` line with anything reusable noticed this turn (pattern, gotcha, useful context), or "none".

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

@@ -51,12 +51,34 @@ When asked to build a slice, always follow this flow:
    - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
    - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
 3. Invoke the matching skill and follow its instructions completely. Do not deviate.
-4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code.
+4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
 5. Run quality checks (`npm run build`, then the slice tests only).
 6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`.
 
 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
 
 ```

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

@@ -0,0 +1,123 @@
+#!/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\/[^/]+\/[^/]+\//;
+
+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));
+  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/node/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/node/templates/build-kit/lib/checks/10-slice-scope.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Everything staged in a slice commit must be inside the slice's own folder, 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 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 ALLOWED_EXCEPTIONS = [
+  /^src\/slices\/[^/]+\/[A-Za-z0-9]+Events\.ts$/, // per-context event union (append-only)
+  /^src\/common\/loadPostgresEventstore\.ts$/, // projection registration / schema.migrate()
+];
+
+const MIGRATION_PATTERN = /^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 (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;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/20-append-only-migrations.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+// migrations/V{n}__*.sql may only be ADDED, never modified or deleted — migrations
+// are append-only; a fix belongs in a new migration, not an edit to an old one.
+
+const MIGRATION_PATTERN = /^migrations\/V\d+__.*\.sql$/;
+
+module.exports = {
+  name: 'append-only-migrations',
+  run(ctx) {
+    const violations = [];
+    for (const { status, path: p } of ctx.changes) {
+      if (!MIGRATION_PATTERN.test(p)) continue;
+      if (status !== 'A') {
+        violations.push({ path: p, reason: 'existing migrations are append-only; add a new V{n} file instead of editing this one' });
+      }
+    }
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/30-test-file-present.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+// A slice commit that adds/changes a command handler, projection, or processor
+// must also include a *.test.ts for that slice — catches the agent skipping the
+// matching build skill's test step (build-state-change Step 4 / build-state-view
+// Step 5 / build-automation's DeciderSpecification tests).
+
+const { execSync } = require('child_process');
+
+const IMPLEMENTATION_FILE = /^src\/slices\/([^/]+)\/([^/]+)\/(?:[A-Za-z0-9]+Command|[A-Za-z0-9]+Projection|processor(?:-[A-Za-z0-9]+)?)\.ts$/;
+
+module.exports = {
+  name: 'test-file-present',
+  run(ctx) {
+    const sliceDirs = new Set();
+    for (const { path: p } of ctx.changes) {
+      const m = IMPLEMENTATION_FILE.exec(p);
+      if (m) sliceDirs.add(`src/slices/${m[1]}/${m[2]}`);
+    }
+    if (sliceDirs.size === 0) return [];
+
+    let tracked = [];
+    try {
+      tracked = execSync('git ls-files -- src/slices', { cwd: ctx.repoRoot, encoding: 'utf8' })
+        .split('\n')
+        .filter(Boolean);
+    } catch {
+      // best-effort — fall through with whatever's staged
+    }
+    const known = new Set([...tracked, ...ctx.changes.map((c) => c.path)]);
+
+    const violations = [];
+    for (const dir of sliceDirs) {
+      const hasTest = [...known].some((f) => f.startsWith(`${dir}/`) && f.endsWith('.test.ts'));
+      if (!hasTest) {
+        violations.push({
+          path: dir,
+          reason: 'no *.test.ts found for this slice — command handlers/projections/processors need test coverage',
+        });
+      }
+    }
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/40-no-invented-fields.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// Heuristic: flags a field name used in a slice's Command/ReadModel type literal
+// that doesn't appear anywhere in that slice's own slice.json. Not a real
+// TS/schema-aware check (no parser dependency) — it regex-extracts the fields
+// declared inside `Command<'Name', { ... }, ...>` and `type XReadModel = { ... }`
+// literals, so unusual formatting (nested object/array field types, nonstandard
+// generics) can slip past undetected. It only ever adds violations for fields it
+// is confident about; when slice.json can't be found/parsed for a slice, that
+// slice's files are skipped entirely rather than guessed at.
+
+const fs = require('fs');
+const path = require('path');
+const { findSliceJson, normalize } = require('../util/find-slice.cjs');
+
+const COMMON_ALLOWED = new Set(
+  ['id', 'userId', 'correlationId', 'causationId', 'streamName', 'type', 'data', 'metadata', 'createdAt', 'updatedAt', 'timestamp'].map(normalize),
+);
+
+const TYPE_LITERALS = [
+  /(?:Command|Event)<\s*'[^']+'\s*,\s*{([^}]*)}/g,
+  /type\s+[A-Za-z0-9_]+ReadModel\s*=\s*{([^}]*)}/g,
+];
+
+const FIELD_LINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\??\s*:/gm;
+
+function collectDeclaredFields(node, out) {
+  if (Array.isArray(node)) {
+    for (const item of node) collectDeclaredFields(item, out);
+  } else if (node && typeof node === 'object') {
+    if (typeof node.name === 'string' && ('type' in node || 'optional' in node)) {
+      out.add(normalize(node.name));
+    }
+    for (const key of Object.keys(node)) collectDeclaredFields(node[key], out);
+  }
+}
+
+module.exports = {
+  name: 'no-invented-fields',
+  run(ctx) {
+    const bySlice = new Map(); // "context/SliceName" -> { context, sliceName, files: [] }
+
+    for (const { path: p } of ctx.changes) {
+      if (!p.endsWith('.ts') || p.endsWith('.test.ts')) continue;
+      const m = /^src\/slices\/([^/]+)\/([^/]+)\//.exec(p);
+      if (!m) continue;
+      const key = `${m[1]}/${m[2]}`;
+      if (!bySlice.has(key)) bySlice.set(key, { context: m[1], sliceName: m[2], files: [] });
+      bySlice.get(key).files.push(p);
+    }
+
+    const violations = [];
+
+    for (const { context, sliceName, files } of bySlice.values()) {
+      const slice = findSliceJson(ctx.repoRoot, context, sliceName);
+      if (!slice) continue; // can't verify — don't block
+
+      const declared = new Set();
+      collectDeclaredFields(slice, declared);
+      if (declared.size === 0) continue; // slice.json shape not recognized — don't block
+
+      for (const file of files) {
+        let content;
+        try {
+          content = fs.readFileSync(path.join(ctx.repoRoot, file), 'utf8');
+        } catch {
+          continue; // deleted/unreadable — nothing to check
+        }
+
+        for (const pattern of TYPE_LITERALS) {
+          pattern.lastIndex = 0;
+          let typeMatch;
+          while ((typeMatch = pattern.exec(content))) {
+            FIELD_LINE.lastIndex = 0;
+            let fieldMatch;
+            while ((fieldMatch = FIELD_LINE.exec(typeMatch[1]))) {
+              const raw = fieldMatch[1];
+              const norm = normalize(raw);
+              if (COMMON_ALLOWED.has(norm) || declared.has(norm)) continue;
+              violations.push({
+                path: file,
+                reason: `field "${raw}" is not declared anywhere in slice.json for this slice — check for an invented field`,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/50-spec-coverage.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+// Heuristic: a slice's *.test.ts must have at least as many `it(...)` blocks as
+// slice.json has `specifications[]` entries. Doesn't verify each spec is
+// actually tested (that would need matching scenario content, not just count),
+// just that nobody's silently short a test case. Skipped (not blocked) when
+// slice.json can't be found or has no specifications[] array.
+
+const fs = require('fs');
+const path = require('path');
+const { findSliceJson } = require('../util/find-slice.cjs');
+
+const TEST_FILE = /^src\/slices\/([^/]+)\/([^/]+)\/[^/]+\.test\.ts$/;
+const IT_BLOCK = /\bit(?:\.(?:only|skip))?\s*\(/g;
+
+module.exports = {
+  name: 'spec-coverage',
+  run(ctx) {
+    const violations = [];
+
+    for (const { path: p } of ctx.changes) {
+      TEST_FILE.lastIndex = 0;
+      const m = TEST_FILE.exec(p);
+      if (!m) continue;
+      const [, context, sliceName] = m;
+
+      const slice = findSliceJson(ctx.repoRoot, context, sliceName);
+      if (!slice || !Array.isArray(slice.specifications) || slice.specifications.length === 0) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(path.join(ctx.repoRoot, p), 'utf8');
+      } catch {
+        continue; // deleted — nothing to check
+      }
+
+      const specCount = slice.specifications.length;
+      const itCount = (content.match(IT_BLOCK) || []).length;
+
+      if (itCount < specCount) {
+        violations.push({
+          path: p,
+          reason: `slice.json declares ${specCount} specification(s) but this test file only has ${itCount} it(...) block(s)`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/90-tsc-build.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+// The project must still typecheck after the slice change. Uses the project's
+// own `typescript` devDependency via `npx tsc --noEmit` — no new dependency,
+// but it does mean this check needs node_modules already installed (same
+// prerequisite `npm run build` already has).
+
+const { execSync } = require('child_process');
+
+module.exports = {
+  name: 'tsc-build',
+  skipIfAlreadyFailing: true, // slow — don't bother once the commit is rejected already
+  run(ctx) {
+    try {
+      execSync('npx tsc --noEmit', { cwd: ctx.repoRoot, stdio: 'pipe' });
+      return [];
+    } catch (err) {
+      const output = String(err.stdout || err.message || '').trim().split('\n').slice(0, 20).join('\n');
+      return [{ path: '(tsc --noEmit)', reason: `TypeScript build failed:\n${output}` }];
+    }
+  },
+};

package/stacks/node/templates/root/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Installed via setup-env.sh (`git config core.hooksPath .githooks`), so this file
+# is versioned and shared by every clone instead of living only in .git/hooks/.
+set -e
+
+repo_root=$(git rev-parse --show-toplevel)
+script="$repo_root/.build-kit/lib/check-commit-scope.cjs"
+
+if [ -f "$script" ]; then
+  node "$script"
+fi

package/stacks/node/templates/root/package.json

@@ -7,7 +7,8 @@
     "dev": "node --env-file=.env --require ts-node/register server.ts",
     "build": "tsc",
     "start": "NODE_ENV=production node --env-file=.env --require ts-node/register server.ts",
-    "test": "tsx --test 'src/**/*.test.ts'"
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "check:scope": "node .build-kit/lib/check-commit-scope.cjs"
   },
   "dependencies": {
     "@event-driven-io/emmett": "^0.42.1-alpha.1",

package/stacks/node/templates/root/setup-env.sh

@@ -50,4 +50,10 @@ FLYWAY_PASSWORD=${DB_PASSWORD}
 EOF
 
 echo ""
-echo ".env created successfully."
+echo ".env created successfully."
+
+if [ -f .githooks/pre-commit ] && git rev-parse --git-dir >/dev/null 2>&1; then
+  chmod +x .githooks/pre-commit 2>/dev/null || true
+  git config core.hooksPath .githooks
+  echo "Configured git to use .githooks/ (slice commit-scope guard)."
+fi