@eventmodelers/cli 2.0.44 → 2.0.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "2.0.44",
+  "version": "2.0.47",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/lib/ralph.js

@@ -14,7 +14,8 @@ import { execFileSync } from 'child_process';
 import { randomUUID } from 'crypto';
 import { createRealtimeAdapter, keepSubscribed } from './adapters/realtime-adapter.js';
 import { backoffMs, sleep } from './backoff.js';
-import { adoptAgentEdits, observeBoard, projectStatus, statusOf } from './slice-projection.js';
+import { adoptAgentEdits, applyBoardStatus, observeBoard, projectStatus, statusOf } from './slice-projection.js';
+import { coalesce } from './slice-refresh.js';
 import { fold, statusKey } from './slice-state.js';
 import { readEvents } from './slice-events.js';
 import { claimSlice, recordEvent, settleSlice, settleLeftoverClaims } from './slice-run.js';
@@ -364,7 +365,18 @@ async function fetchFullSlice(cfg, kitDir, sliceId) {
   }
 }
 
-async function handleSliceChanged(payload, cfg, kitDir) {
+// Re-reads of the slice list caused by other people's changes: a burst of events (an import, a bulk status
+// change) becomes one read per agent instead of one per event.
+const SLICE_REFRESH_DELAY_MS = 1500;
+const refreshSlices = coalesce(fetchAndPersistSlices, SLICE_REFRESH_DELAY_MS);
+
+// A slice:changed that only moved a slice's status carries everything the local files need — the other
+// fields of the payload are the ones the write set, so all of them null means none was touched. Anything
+// else (a title, assignee, ticket or feature, or a slice not listed yet) is read from the board.
+const isStatusOnly = (payload) =>
+  !!payload?.sliceStatus && payload.sliceTitle == null && payload.assignee == null && payload.ticketNumber == null && payload.feature == null;
+
+export async function handleSliceChanged(payload, cfg, kitDir, refresh = refreshSlices) {
   console.log(`[agent] slice:changed — slice="${payload.sliceTitle ?? payload.sliceId}" status="${payload.sliceStatus}"`);
   // This agent's own status writes (claim → InProgress, → Done, → Blocked) come straight back
   // as slice:changed. Queuing them only buys a turn in which the agent reads its own echo and
@@ -376,9 +388,12 @@ async function handleSliceChanged(payload, cfg, kitDir) {
     console.log(`[agent] Own write — not queued (slice="${payload.sliceTitle ?? payload.sliceId}" status="${payload.sliceStatus}")`);
     return;
   }
-  await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
-    console.error('[agent] Slice persist error:', err),
-  );
+  const appliedLocally = isStatusOnly(payload) && applyBoardStatus(kitDir, payload.sliceId, payload.sliceStatus, eventMeta(cfg));
+  if (!appliedLocally) {
+    await refresh(cfg, kitDir).catch((err) =>
+      console.error('[agent] Slice persist error:', err),
+    );
+  }
   // Slices in the kit's pickup status (Planned, or Waiting for UI kits) are handled by
   // onPlannedSlice directly — no task needed.
   if (statusKey(payload.sliceStatus) !== statusKey(readPickupStatus(kitDir))) {
@@ -464,6 +479,12 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', createAdap
     },
   });
 
+  // A slice:changed that never arrived (a dropped message the reconnect logic cannot see) would leave the
+  // local copy stale until the next change — read the whole list now and then to catch it up.
+  setInterval(() => {
+    refreshSlices(cfg, kitDir).catch((err) => console.error(`[agent] ${ts()} Scheduled slice reconcile failed:`, err));
+  }, 10 * 60 * 1000);
+
   setInterval(() => {
     refreshToken('scheduled 10min refresh').catch((err) => console.error(`[agent] ${ts()} Scheduled token refresh failed:`, err));
   }, 10 * 60 * 1000);

package/shared/build-kit/lib/slice-projection.js

@@ -24,6 +24,42 @@ export function observeBoard(kitDir, boardSlices, meta, current = fold(readEvent
   return changed ? fold(readEvents(kitDir)) : state;
 }
 
+// The board's slice statuses as the slice list reports them (the backend's STATUS_MAP). 'Handover' is the
+// legacy name of Waiting. Undefined for anything else — the caller then reads the board instead of guessing.
+const BOARD_STATUSES = new Set(['Created', 'Ready', 'Done', 'InProgress', 'Blocked', 'Assigned', 'Review', 'Waiting', 'Planned', 'Informational']);
+export function normalizeBoardStatus(raw) {
+  if (raw === 'Handover') return 'Waiting';
+  return BOARD_STATUSES.has(raw) ? raw : undefined;
+}
+
+// Whether the slice is already in a context's index.json — a slice the agent has never listed has to be
+// fetched, because its title, type and context are not in a status event.
+function knowsSlice(kitDir, sliceId) {
+  const slicesDir = join(kitDir, '.slices');
+  if (!existsSync(slicesDir)) return false;
+  for (const ctx of readdirSync(slicesDir, { withFileTypes: true })) {
+    if (!ctx.isDirectory()) continue;
+    try {
+      const index = JSON.parse(readFileSync(join(slicesDir, ctx.name, 'index.json'), 'utf-8'));
+      if ((index.slices ?? []).some((e) => e.id === sliceId)) return true;
+    } catch { /* an unreadable index is left for the next full fetch to repair */ }
+  }
+  return false;
+}
+
+// A status change the board announced for a slice already on disk, applied without reading the board again:
+// the same two steps a full refresh takes for status — record what the board shows (observeBoard, after
+// adopting the agent's own edits), then project the log's status into the files — so a claim held here still
+// wins over the board's InProgress. Returns false when the slice is unknown or the status unrecognised; the
+// caller then falls back to a full refresh.
+export function applyBoardStatus(kitDir, sliceId, boardStatus, meta) {
+  const status = normalizeBoardStatus(boardStatus);
+  if (!sliceId || !status || !knowsSlice(kitDir, sliceId)) return false;
+  const state = observeBoard(kitDir, [{ id: sliceId, status }], meta, adoptAgentEdits(kitDir, fold(readEvents(kitDir)), meta));
+  projectStatus(kitDir, state);
+  return true;
+}
+
 // The build agent still records its outcome by editing a slice's status in index.json (until it has a
 // command of its own). While a slice is claimed the projection keeps that file equal to the log, so any
 // difference is the agent's edit — adopted as `agent-recorded`. This runs before every refresh and before

package/shared/build-kit/lib/slice-refresh.js

@@ -0,0 +1,35 @@
+// One refresh for a burst of requests. Every agent on a board re-reads the slice list when someone else
+// changes a slice, so an import or a bulk status change would otherwise read it once per event, per agent.
+//
+// request() resolves once a run that STARTED after the call has finished — a request made while a run is
+// already in flight gets a fresh run of its own, because the data that run read may predate it. Requests
+// within `delayMs` of each other share one run, which receives the arguments of the last request.
+
+export function coalesce(fn, delayMs) {
+  let waiters = [];
+  let timer = null;
+  let running = false;
+  let lastArgs = [];
+
+  const run = async () => {
+    timer = null;
+    running = true;
+    const batch = waiters;
+    waiters = [];
+    try {
+      await fn(...lastArgs);
+      for (const w of batch) w.resolve();
+    } catch (err) {
+      for (const w of batch) w.reject(err);
+    } finally {
+      running = false;
+      if (waiters.length && !timer) timer = setTimeout(run, delayMs);
+    }
+  };
+
+  return (...args) => new Promise((resolve, reject) => {
+    lastArgs = args;
+    waiters.push({ resolve, reject });
+    if (!running && !timer) timer = setTimeout(run, delayMs);
+  });
+}

package/shared/skills/learn-eventmodelers-api/references/mcp-tool-catalog.md

@@ -11,7 +11,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | Tool | Args | Purpose | REST equivalent |
 |---|---|---|---|
 | `list_boards` | — | List boards for the org | §1 `GET /api/boards` (org-scoped) |
-| `get_nodes` | `boardId`, `type?`, `name?`, `chapterId?`, `nodeIds?`, `projection?` (`"line"` \| `"fields"`) | List nodes, optionally by type and/or a partial case-insensitive title match. **Unscoped with full `meta` it is expensive** — about 2 KB per node, ~1 MB on a 500-node board — so always pass a filter or a projection. `chapterId` scopes to one timeline — prefer this over an unscoped board-wide call whenever the step is working within one chapter (the common case); `nodeIds` fetches a known, scattered subset in one call (e.g. re-verifying exactly the nodes just touched by a batch write) instead of a full `type` refetch; `projection: "line"` maps each match to `{id, type, title, fields}` — `fields` being just the attribute names; `projection: "fields"` to `{id, type, title, parentId, fields}` with the full field definitions (type, example, idAttribute, …) but no html, description, sketch or grid data. No `cellName` — an existing node is addressed by its `id`; when a cell address is needed (placing into a cell), read it from `get_board_outline`. No `sliceStatus` — take it per column from `get_board_outline` | §3 `GET .../nodes` (REST records carry no `cellName`, `projection=line`/`fields` included) |
+| `get_nodes` | `boardId`, `type?`, `name?`, `chapterId?`, `nodeIds?`, `projection?` (`"line"` \| `"fields"`) | List nodes, optionally by type and/or a partial case-insensitive title match. **A filter is required** — `type`, `name`, `chapterId` or `nodeIds`; a call without one is rejected (`NODES_FILTER_REQUIRED`) because it would load the whole board, and a `projection` alone does not count. Full `meta` is about 2 KB per node, so add a projection (`line` / `fields`) on top of the filter when you only need an overview. `chapterId` scopes to one timeline — prefer this over an unscoped board-wide call whenever the step is working within one chapter (the common case); `nodeIds` fetches a known, scattered subset in one call (e.g. re-verifying exactly the nodes just touched by a batch write) instead of a full `type` refetch; `projection: "line"` maps each match to `{id, type, title, fields}` — `fields` being just the attribute names; `projection: "fields"` to `{id, type, title, parentId, fields}` with the full field definitions (type, example, idAttribute, …) but no html, description, sketch or grid data. No `cellName` — an existing node is addressed by its `id`; when a cell address is needed (placing into a cell), read it from `get_board_outline`. No `sliceStatus` — take it per column from `get_board_outline` | §3 `GET .../nodes` (REST records carry no `cellName`, `projection=line`/`fields` included) |
 | `get_node` | `boardId`, `nodeId`, `projection?` (`"cells"` \| `"edges"`) | Get one node (no `cellName` — address it by `nodeId`; cell addresses come only from `get_board_outline`). `projection: "cells"` (CHAPTER nodes only) returns just `{rows, columns, cells}` instead of the full `timelineData` — use whenever only the grid/occupancy is needed, not the whole chapter; `projection: "edges"` returns just that node's inbound/outbound connections instead of `findNodeById`'s full record. Both are opt-in — omitting `projection` is the unchanged full response. An unknown id is a `NODE_NOT_FOUND` error | §3 `GET .../nodes/:nodeId` (REST returns the node as stored, without `cellName`; `404` carries `code: 'NODE_NOT_FOUND'`) |
 | `get_node_comments` | `boardId`, `nodeId` | List comments on a node | §1 `GET .../nodes/:nodeId/comments` |
 | `get_chat_attachment` | `boardId`, `sessionId`, `attachmentId` | The file a chat message came with — the message's `attachments` list `{id, type, ending}`. Images come back as images, a PDF as an embedded resource, csv / xml / txt / json as text. Only the agent the message was addressed to can read it (`CHAT_ATTACHMENT_NOT_FOUND`); needs the connection's `x-agent-id` (`CHAT_AGENT_REQUIRED`). Max 5 MB per file. | §15 `GET /api/org/:orgId/chat/sessions/:sessionId/attachments/:attachmentId` |
@@ -35,7 +35,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `place_element` | `boardId`, `timelineId`, `elements[]` (each `action?` = `create` (default) with `elementType`, `title`, `fields?`, `lane?`, `columnIndex?`, `autoConnect?` · `move` with `nodeId` + target `cellName` · `clear` with `nodeId` (preferred for an existing node) or `cellName`), `compact?` | Find/create an empty cell in the right lane and place a COMMAND/READMODEL/EVENT/AUTOMATION/MARKDOWN/TABLE. `action: "move"` puts an existing node of any type into that (empty) cell, moving it if it already sits elsewhere on the timeline; `action: "clear"` unplaces a node without deleting it (`delete_node` deletes) — pass its `nodeId` to empty the cell it sits in, or a `cellName`. These replace `drop_node_to_cell`, `move_node_in_timeline` and `clear_cell`, which still exist but are deprecated — don't use them. `fields` writes the element's attributes in the same call — don't follow a placement with a `submit_node_events` just to set them. A whole slice's or column run's worth goes in one call, applied in order so each entry sees the columns the previous one added; answers `{results}` (`compact: true` → `{nodeId, cellName, columnIndex}` per entry). `autoConnect: false` places without wiring to timeline neighbors — wire the edges yourself | — (MCP-only convenience; composes §2+§3) |
 | `list_slices` | `boardId`, `contextName?` | List slices (id, title, status). `contextName` restricts to one MODEL_CONTEXT (or timeline) — an unknown name is a `CONTEXT_NOT_FOUND` error, not an empty list | §8 `GET .../slicedata/slices` |
 | `get_slice_rework` | `boardId`, `contextId` | How much each slice of one context has been reworked: changes, steps backwards, and reopens after Done, most reworked first, plus planning metrics over them. `contextId` is a MODEL_CONTEXT or a timeline (a timeline resolves to the context it belongs to). Always per context — there is no board-wide form | §8 `GET .../reporting/rework/contexts/:contextId` |
-| `update_slice_status` | `boardId`, `newStatus`, plus exactly one of `sliceId` / `sliceTitle` | Change a SLICE_BORDER's `sliceStatus`. With a title there is no need to call `list_slices` first; an ambiguous title comes back with its candidates. A slice being created takes its status from `create_slice`/`create_slice_definition` instead | — (via `node:changed` event, §3) |
+| `update_slice_status` | `boardId`, `newStatus`, `statusReason?` (optional, but you should set it: one sentence — why; shown as an info icon in the planning view; stored as `meta.statusReason` next to `sliceStatus`), plus exactly one of `sliceId` / `sliceTitle` | Change a SLICE_BORDER's `sliceStatus`. With a title there is no need to call `list_slices` first; an ambiguous title comes back with its candidates. A slice being created takes its status from `create_slice`/`create_slice_definition` instead | — (via `node:changed` event, §3) |
 | `get_slice_data` | `boardId`, `contextName?`, `contextId?`, `sliceId?`, `projection?` (`"outline"` \| `"fields"` \| `"specs"`), `format?` | Full element graph for slices in a context. `projection` trims it first: `outline` = slice header + each element as `{id, title, type}`; `fields` = elements with fields and dependencies, no specs/comments/prompts; `specs` = specifications and storylines, no elements — prefer one over the full graph when only part is needed. `outline`/`specs` encode only as `json`, `yaml` or `toon` (other formats are a `PROJECTION_FORMAT_UNSUPPORTED` error); an unknown `sliceId` is `SLICE_NOT_FOUND` | §8 `GET /slicedata` |
 | `get_spec_info` | `boardId`, `timelineId`, `elementTypes?` | EVENT/COMMAND/READMODEL nodes valid in GWT steps. Pass `elementTypes` (subset of `EVENT`/`COMMAND`/`READMODEL`) to avoid pulling the full element list when only one or two types are needed — filtered server-side, not just after a full fetch | §6 `GET .../spec-info` |
 | `get_board_outline` | `boardId`, `chapterId` | One chapter's structure, compact: per-column node lists (`{id, type, title, lane, cellName}`) + a flat edge list, no HTML pages / field bodies / meta. `cellName` is each node's real cell address (column letter + row number) — the only read that returns cell names at all; use it when a placement needs a cell address. For an empty target cell, take the column's `letter` plus the lane's 1-based position in the outline's `lanes` list (e.g. `letter: "C"`, second lane → `C2`) — never convert array indexes yourself. The cheap "what is where and how is it wired" read — prefer over `get_nodes` (no projection) for orientation checks | — (MCP-only convenience) |

package/shared/skills/learn-eventmodelers-api/references/s03-nodes.md

@@ -66,12 +66,13 @@ interface NodeChangeEvent {
 ---
 
 ### GET `/api/org/:orgId/boards/:boardId/nodes`
-List all nodes on a board.
+List a board's nodes. **A filter is required**: a call with none of `type`, `name`, `chapterId`, `toplevel=true` or `cellId`/`colId` (with `timelineId`) is `400 NODES_FILTER_REQUIRED`, because it would load the whole board — a `projection` alone does not count. Read a board in parts: `toplevel=true` (the nodes in no chapter), then `chapterId` per chapter; or fetch known ids with `POST …/nodes/query`.
 
 **Query params** (each at most once — a repeated or nested param is `400 QUERY_PARAM_INVALID`):
 - `type?: ElementType` — exact match.
 - `name?: string` — partial, case-insensitive title match.
 - `chapterId?: string` — only nodes placed in this chapter (timeline).
+- `toplevel?: "true"` — only the nodes placed in no chapter (the chapters themselves, contexts, drawings); not combinable with `chapterId`, `cellId` or `colId` (`400 TOP_LEVEL_FILTER_CONFLICT`).
 - `projection?: "line" | "fields"` — `line`: compact `{id, type, title, fields?}` per node (`fields` = attribute names only, absent on nodes without fields); `fields`: `{id, type, title, parentId, fields?}` with the full field definitions as stored, but no html, description, sketch or grid data. Either instead of the full record. Neither form carries `cellName` — address existing nodes by `id`. Any other value is `400 PROJECTION_INVALID`.
 - `cellId?: string` — return only the node occupying this timeline cell (format `<rowId>-<colId>`). Requires `timelineId`. Empty array if the cell is unoccupied.
 - `colId?: string` — return every node occupying this column, across *all* rows of the timeline (e.g. to check for an existing COMMAND/READMODEL/SCREEN/AUTOMATION before placing one, since the server caps those at one per column even across separate lane rows). Requires `timelineId`. Combine with `type` to narrow to one element type.

package/shared/skills/request-feedback/SKILL.md

@@ -129,10 +129,12 @@ or contradictory — not just "please clarify this slice."
 
 ## Step 4 — Mark the slice Blocked
 
+Blocking is two things: the comment from Step 3 holds the full question, and the `statusReason` is its one-sentence summary (what is missing or contradictory) that people see as an exclamation-mark icon in the planning view and on the slice header. Set both — the reason is optional, but you should always give it here.
+
 Prefer MCP:
 
 ```
-mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "Blocked" }
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "Blocked", "statusReason": "<one sentence: what is missing>" }
 ```
 
 Also mark the slice 'blocked' locally in the index.json if possible.
@@ -149,10 +151,11 @@ curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
     "id": "<new-random-uuid>",
     "eventType": "node:changed",
     "nodeId": "<SLICE_NODE_ID>",
-    "changedAttributes": ["sliceStatus"],
+    "changedAttributes": ["sliceStatus", "statusReason"],
     "meta": {
       "type": "SLICE_BORDER",
-      "sliceStatus": "Blocked"
+      "sliceStatus": "Blocked",
+      "statusReason": "<one sentence: what is missing>"
     }
   }]'
 ```

package/shared/skills/update-slice-status/SKILL.md

@@ -17,6 +17,7 @@ From `$ARGUMENTS`, extract:
 |-------|---------------|---------|
 | `sliceName` | the slice title to update (case-insensitive match) | **required** |
 | `newStatus` | the target status value | **required** |
+| `statusReason` | ONE sentence saying why the status changes | optional, but you **should** set it |
 
 Valid status values (case-sensitive):
 
@@ -35,6 +36,13 @@ Valid status values (case-sensitive):
 
 If `newStatus` is not one of these exact values, stop and tell the user the valid options.
 
+### Give a reason (optional, but you should)
+
+`statusReason` is optional — a status change works without it — but whenever you change a status you **should** send one: **one sentence**, in plain words, saying *why* the status changes
+("Backend built and tested, UI contract published.", "Blocked: the order total rule is unclear.", "Reviewed and approved by Anna.").
+It is stored next to `sliceStatus` in the SLICE_BORDER's meta and shown to people as an exclamation-mark icon in the planning view and on the slice header,
+so write it for a person who was not watching. Say what happened, not the status name again. For `Blocked`, also post a comment with the details (see `request-feedback`) and let `statusReason` be its short summary. Don't leave an old reason in place when the status changes — send a new one each time.
+
 ---
 
 ## Step 2 — List all slices
@@ -69,13 +77,13 @@ Save the matched slice as:
 Prefer the MCP tool — it does the same `node:changed`/`sliceStatus` update in one call, no event envelope to hand-assemble:
 
 ```
-mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "<newStatus>" }
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "<newStatus>", "statusReason": "<one sentence: why>" }
 ```
 
 The tool also resolves the slice itself — pass `sliceTitle` (or `columnId`) instead of `sliceId` and the listing step above can be skipped entirely; an ambiguous title comes back with its candidates instead of a guess:
 
 ```
-mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceTitle": "Place Order", "newStatus": "<newStatus>" }
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceTitle": "Place Order", "newStatus": "<newStatus>", "statusReason": "<one sentence: why>" }
 ```
 
 A slice that is being *created* takes its status straight from `create_slice`/`create_slice_definition` (`status`) — don't create it and then call this.
@@ -91,10 +99,11 @@ curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
     "id": "<new-random-uuid>",
     "eventType": "node:changed",
     "nodeId": "<SLICE_NODE_ID>",
-    "changedAttributes": ["sliceStatus"],
+    "changedAttributes": ["sliceStatus", "statusReason"],
     "meta": {
       "type": "SLICE_BORDER",
-      "sliceStatus": "<newStatus>"
+      "sliceStatus": "<newStatus>",
+      "statusReason": "<one sentence: why>"
     }
   }]'
 ```
@@ -122,6 +131,7 @@ Tell the user:
 - **Slice**: the title that was updated
 - **Previous status**: `CURRENT_STATUS`
 - **New status**: `newStatus`
+- **Reason**: `statusReason` (if set)
 - **Node ID**: `SLICE_NODE_ID`
 - **Outcome**: `SUCCESS`, `ALREADY_IN_STATUS` (another agent got there first — see above), or `ERROR`
 - **Any errors**: raw API message if something failed for a reason other than `ALREADY_IN_STATUS`

package/stacks/modeling-kit/templates/.claude/skills/analyze-code-base/SKILL.md

@@ -116,6 +116,7 @@ Rules of thumb: every API call is either a screen-driven command/read or an auto
    - `eventmodeling-designing-automation-chains` / `eventmodeling-translating-external-events` — jobs, listeners, webhooks, outbound calls;
    - `eventmodeling-elaborating-scenarios` — rules from the tests (layer 1+ only), built exactly as that skill says (see *Scenarios* below).
    Feed each skill what the lenses and the mapping table give you; ask only where the code stops (see *Step 1* when the order is unclear).
+   **Screens and scenarios are part of the pass — never skip them.** A chapter with only events, commands and read models is not detailed yet. Every command and read model a person uses gets its `HTML_SCREEN` (storyboarding step), and every command gets at least its happy-path scenario from `eventmodeling-elaborating-scenarios`. Never report "not done: screens, scenarios, tests, UI" and ask for the next chapter; run those steps first. If a step truly can't be done (e.g. no tests to mine for a rule), say why in the chapter's decision rows, but still place the screens and the happy-path scenario.
 2. Stay within the layer's detail budget (below). Every placement batch carries its decision rows (see *Recording decisions*).
 3. Re-space the chapters (see *Keeping chapters apart*) after every batch.
 4. Append this pass's row to the chapter's *Analysis history*.