@eventmodelers/cli 1.0.119 → 1.0.120

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.119",
+  "version": "1.0.120",
   "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

@@ -5,6 +5,7 @@
 //   onTask(prompt) — called when tasks.json has entries
 //   onPlannedSlice(prompt, slice) — called when .slices/ has a "Planned" entry (omit to skip);
 //     `slice` ({sliceId, sliceTitle, context, ticketNumber, boardId, attempt}) lets a runner record what building it cost.
+//     May resolve with the agent's final reply — quoted in the note if the slice ends up auto-blocked.
 
 import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, renameSync } from 'fs';
 import { join, dirname } from 'path';
@@ -590,11 +591,14 @@ const MAX_PLANNED_ATTEMPTS = Number(process.env.RALPH_MAX_PLANNED_ATTEMPTS) || 2
 
 // Marks a stuck slice Blocked (locally, and on the board if credentialed) and
 // records why, so the loop can move on instead of looping or exiting.
-async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
+// `lastReply` is the build agent's final message on the last attempt (when the runner reports one),
+// so the note says what actually happened instead of only listing what might have.
+async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts, lastReply) {
   const now = new Date().toISOString();
   const reason = `Ralph loop picked up this slice ${attempts} times in a row without its status ever leaving ` +
     `"Planned" — the build agent kept declining to build it, or kept building it but its own status change kept ` +
-    `getting reverted (e.g. a failed check). Auto-blocked to stop the loop from retrying it forever.`;
+    `getting reverted (e.g. a failed check). Auto-blocked to stop the loop from retrying it forever.` +
+    (lastReply ? ` Build agent's last reply: "${String(lastReply).replace(/\s+/g, ' ').trim().slice(0, 500)}"` : '');
 
   const indexPath = join(kitDir, '.slices', planned.ctx, 'index.json');
   let folder;
@@ -662,7 +666,7 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
   console.error(`[ralph] ${reason} Marked "${planned.title}" (id=${planned.id}) as Blocked — moving on.`);
 }
 
-// Returns true once fn succeeds; false for a turn that timed out (see lib/turn.js). A timeout
+// Returns true once fn succeeds (fn's own result is the caller's to capture); false for a turn that timed out (see lib/turn.js). A timeout
 // is not retried in place: re-running the same hung turn every 60s would spin forever without
 // the stuck-slice guard ever seeing it, so it goes back to ralphLoop, which recounts the slice.
 // Any other failure is retried in place, with backoff (30s → 10min) so a harness that keeps
@@ -696,6 +700,8 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
   // Tracks consecutive sightings of the same Planned slice id — see
   // MAX_PLANNED_ATTEMPTS above.
   let stuckSlice = { id: null, count: 0 };
+  // The build agent's final reply on the most recent planned-slice turn — quoted in the Blocked note.
+  let lastReply = null;
 
   while (true) {
     let didWork = false;
@@ -715,7 +721,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
         : { id: planned.id, count: 1 };
 
       if (stuckSlice.count > MAX_PLANNED_ATTEMPTS) {
-        await blockStuckSlice(kitDir, cfg, credentialed, planned, stuckSlice.count);
+        await blockStuckSlice(kitDir, cfg, credentialed, planned, stuckSlice.count, lastReply);
         stuckSlice = { id: null, count: 0 };
         didWork = true;
         continue;
@@ -723,14 +729,15 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
 
       const prompt = readFileSync(backendPromptFile, 'utf-8');
       if (credentialed) await fetchFullSlice(cfg, kitDir, planned.id);
-      const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
+      lastReply = null;
+      const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, async () => { lastReply = await onPlannedSlice(prompt, {
         sliceId: planned.id,
         sliceTitle: planned.title,
         context: planned.ctx,
         ticketNumber: planned.ticketNumber,
         boardId: cfg.boardId ?? null,
         attempt: stuckSlice.count,
-      }));
+      }); });
       if (built) console.log(`[ralph] Slice build complete — waiting for next slice`);
       if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;

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

@@ -80,14 +80,19 @@ function describeToolUse(block) {
 // `slice` is set for a planned-slice build (see startRalph) — the only turns that are traced.
 function runClaude(prompt, slice = null) {
   return new Promise((resolve, reject) => {
-    const proc = spawn('claude', [...claudeArgs, '-p', inlineHeader + prompt], {
+    // The prompt goes in on stdin, never as a `-p` argument: on Windows a multi-line argv entry
+    // is cut at its first newline, so `claude` saw only the connect header, answered "I don't see
+    // a request" and the slice stayed Planned until the stuck-slice guard blocked it.
+    const proc = spawn('claude', [...claudeArgs, '-p'], {
       cwd: projectDir,
-      stdio: ['inherit', 'pipe', 'inherit'],
+      stdio: ['pipe', 'pipe', 'inherit'],
       env: claudeEnv,
     });
+    proc.stdin.end(inlineHeader + prompt);
     const turn = superviseTurn(proc, { timeoutMs, label: 'Claude turn', log: (line) => console.error(`[ralph] ${line}`) });
 
     let buffer = '';
+    let reply = null;
     proc.stdout.on('data', (chunk) => {
       buffer += chunk.toString();
       const lines = buffer.split('\n');
@@ -107,6 +112,7 @@ function runClaude(prompt, slice = null) {
             }
           }
         } else if (msg.type === 'result') {
+          reply = msg.result ?? null;
           console.log(`done (${msg.duration_ms}ms${msg.total_cost_usd ? `, $${msg.total_cost_usd.toFixed(4)}` : ''})`);
           if (slice) tracer.record({...slice, status: msg.is_error ? 'error' : 'ok'}, usageFromClaudeResult(msg));
         }
@@ -116,7 +122,7 @@ function runClaude(prompt, slice = null) {
     proc.on('close', (code) => {
       const timeout = turn.timeoutError();
       if (timeout) reject(timeout);
-      else if (code === 0) resolve();
+      else if (code === 0) resolve(reply);
       else reject(new Error(`Claude exited ${code}`));
     });
     proc.on('error', reject);

package/stacks/bridge/templates/bridge/ralph-claude.js

@@ -26,11 +26,13 @@ const claudeEnv = cfg.anthropicBaseUrl
 
 function runClaude(prompt) {
   return new Promise((resolve, reject) => {
-    const proc = spawn('claude', [...claudeArgs, '-p', inlineHeader + prompt], {
+    // Prompt on stdin, not as a `-p` argument — Windows cuts a multi-line argv entry at its first newline.
+    const proc = spawn('claude', [...claudeArgs, '-p'], {
       cwd: projectDir,
-      stdio: 'inherit',
+      stdio: ['pipe', 'inherit', 'inherit'],
       env: claudeEnv,
     });
+    proc.stdin.end(inlineHeader + prompt);
     proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Claude exited ${code}`))));
     proc.on('error', reject);
   });

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

@@ -40,7 +40,9 @@ Either way, append a row to the chapter's *Analysis history* (see *The analysis
 
 ## Step 1 — Is there a running UI? (once, when the analysis starts)
 
-Ask once, before reading the sources, and only when starting fresh (no chapters from this analysis yet): *"Is there a running instance I can inspect? URL, and a login or test account if needed."* Wait for the answer. Record it (URL or "no running UI") in each chapter's `Legacy Sources` note and reuse it on later passes. Skip it when the request already answers it.
+Ask once, when starting fresh (no chapters from this analysis yet): *"Is there a running instance I can inspect? URL, and a login or test account if needed."* The question is **optional, not a gate**: post it at the start, then **continue straight away** with the code analysis (Pass 0) without waiting for the answer. Until an answer arrives, work from the code alone and record `running UI: not answered yet` in each chapter's `Legacy Sources` note. Skip the question when the request already answers it.
+
+When the answer arrives later: a URL (and login) → start the UI analysis then — walk it via `discover-storyboard` (see the *UI* lens), add its screens as evidence and use its click path to confirm or correct the order already derived from the code; "no running UI" → nothing to do. Either way, update the `Legacy Sources` note with the answer and reuse it on later passes.
 
 Ask again mid-way only when it helps — typically when the order isn't clear from the code: *"I can't tell the order of these steps from the code. Is there a running UI I can use to check? Otherwise, here are my questions: …"*
 
@@ -63,12 +65,14 @@ Naming, what to model and the anti-patterns are in `eventmodeling-core-rules` (r
 Every pass reads the code through the same four lenses; each produces *hypotheses* to put to the person, never elements on its own. Read only as deep as the current layer needs.
 
 1. **API** (look hardest here) — REST controllers, routes, handlers, message listeners, scheduled jobs, outbound clients. Each entry point is a candidate **screen + command** (a person writes), **screen + read model** (a person reads) or **automation** (jobs, listeners, calls to other systems). Request/response payloads hint at fields; the caller hints at who triggers it.
-2. **Tests** — test names, fixtures, assertions. Names reveal the business vocabulary; arrange/act/assert becomes Given/When/Then; error cases reveal the rules that matter. Fixtures are the source of realistic example values.
+2. **Tests** — test names, fixtures, assertions. Names reveal the business vocabulary; arrange/act/assert is a *hint* for Given/When/Then, not its shape — which element goes into Given, When and Then is decided by `eventmodeling-elaborating-scenarios`, never by the test's structure (see *Scenarios* below); error cases reveal the rules that matter. Fixtures are the source of realistic example values.
 3. **Persistence** (look hardest here, too — *what gets saved*) — entities, tables, migrations, repositories. Every write is a candidate **event**. Writes show which state changes exist (→ events); relations show aggregate boundaries; status/enum columns show lifecycles; derived or joined queries show read models. Tables are evidence, never elements.
-4. **UI** — templates, views, components, forms, navigation. Forms and buttons are where a person triggers a command; list and detail pages are read models; the page order is the flow; visible labels are the business words. Whether a running UI exists is asked in **Step 1**. Without one, rely on the other three lenses and ask where the order stays unclear.
+4. **UI** — templates, views, components, forms, navigation. Forms and buttons are where a person triggers a command; list and detail pages are read models; the page order is the flow; visible labels are the business words. Whether a running UI exists is asked in **Step 1** — without waiting for the answer. Until there is a URL, rely on the other three lenses and ask where the order stays unclear.
 
    **With a URL, walk it via `discover-storyboard`** (URL already known — don't ask again; pass the flow as guidance and ask for screenshots). Its click path is the *proposed* order and its screens go into the chapter as evidence; confirm both against the API and persistence lenses. Submit forms only against a local or test system, or after the person agrees.
 
+   **Screens: HTML, except real screenshots.** A plain `SCREEN` node is used for exactly one thing — a screenshot Playwright took of the running UI (`contentType: "image"`). Every other screen — built from the templates, views and controllers, or for a step the running UI didn't show — is an `HTML_SCREEN` via `/html-screen` (`create_screen` with `contentType: "html"` and real pages: the template's labels, fields and buttons). Never a sketch, never a plain `SCREEN` without a screenshot on it.
+
 If the code is a generic engine (templates, schemas, configurable entities), model one real case it handles, not the engine (see *Concrete Over Generic* in `eventmodeling-core-rules`).
 
 Where the lenses disagree (a route nobody calls, a table never written, a test for removed behaviour, a screen with no backend), that is a question for the person — not something to model.
@@ -94,17 +98,17 @@ Rules of thumb: every API call is either a screen-driven command/read or an auto
 ## Progressive elaboration — all chapters first, then one chapter per pass
 
 ### Pass 0 — all chapters, high level
-1. Read the sources broadly through the four lenses to spot the business workflows — walking the running UI from Step 1 via `discover-storyboard` if there is one.
+1. Read the sources broadly through the four lenses to spot the business workflows — don't wait for the Step 1 answer; walk the running UI via `discover-storyboard` once a URL has been given (also when it arrives after Pass 0).
 2. Group them into chapters and create them as `eventmodeling-brainstorming-events` (§ *Group events by workflow* / *Create one chapter per group*) does — a chapter is a user journey, never one endpoint, controller or CRUD operation. Code is split by operation (`OwnerController#initCreationForm`, `#processFindForm`, `#showOwner`, `#processUpdateOwnerForm`); the story is not — registering, finding, viewing and updating an owner are **one** chapter. Order the chapters per `eventmodeling-plotting-events`; ask where it is unclear. Add the **Decisions** lane, put the `Legacy Sources` note into **column 0** (see *The analysis log*), then sketch only the milestones (titles only) **from column 1 on**.
 3. Report the chapters and **ask which chapter to start with**. Never pick for them.
 
 ### Pass N — detail the chosen chapter
 1. Work **in the chapter the person picked**, reusing what is already there. Model the **whole workflow**, not its first slice, by running the step skills on it in order:
    - `eventmodeling-plotting-events` — the events in business order, start to outcome;
-   - `eventmodeling-storyboarding-events` — what the person sees after each event (e.g. *Owner Registered* → owner details page → add a pet);
+   - `eventmodeling-storyboarding-events` — what the person sees after each event (e.g. *Owner Registered* → owner details page → add a pet). Every screen it places is an `HTML_SCREEN` (see *Screens* in the *UI* lens): skip its interview (the code answers it) and never take its sketch path;
    - `eventmodeling-identifying-inputs` / `eventmodeling-identifying-outputs` — commands and read models;
    - `eventmodeling-designing-automation-chains` / `eventmodeling-translating-external-events` — jobs, listeners, webhooks, outbound calls;
-   - `eventmodeling-elaborating-scenarios` — rules from the tests (layer 1+ only).
+   - `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).
 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.
@@ -119,7 +123,7 @@ Repeat until the person says stop. Chapters not chosen stay at high level.
 |-------|----------|--------|----------|-----------|---------|
 | **0 — High level** | one chapter per flow, business milestones as slices | none | none | none | none |
 | **1 — Flow** | real command / event / read model sequence of one flow | only identifying and business-critical | one per key element | happy path + the one or two rules that matter | only where a person decides |
-| **2+ — Deeper** | sub-flows, alternate paths, automations | full business field set incl. optional/list | realistic values from tests and fixtures | error cases and edge rules from the tests | sketches where a decision needs them |
+| **2+ — Deeper** | sub-flows, alternate paths, automations | full business field set incl. optional/list | realistic values from tests and fixtures | error cases and edge rules from the tests | HTML screens where a decision needs them (screenshots only from the running UI) |
 
 Never add detail that belongs to a deeper layer. Every element must trace to sources you read or an answer the person gave. **Deeper never means more technical** — it means more business: decisions, rules, failure modes.
 
@@ -228,7 +232,7 @@ Element `description`s still carry their own short code reference. The feedback
 
 **When this run has a chat** (`CHAT_SESSION_ID` is set — the request came from the board's chat), a question the person answers with a pick is a **snippet** (`post_chat_message` with `snippet`; shapes in `/learn-eventmodelers-api` § 16 *Chat snippets*); an open question stays text. Without a chat, ask in prose.
 
-This overrides the `tasks`-snippet chat mode of `/timeline`. **Snippets are not a confirmation gate.** Never post a `tasks` snippet to let the person tick what you derived from the code — you build that directly (see *Principles*). Use a snippet only when you genuinely need the person (the Step 1 question about a running UI comes first, as plain text, and only when the analysis starts):
+This overrides the `tasks`-snippet chat mode of `/timeline`. **Snippets are not a confirmation gate.** Never post a `tasks` snippet to let the person tick what you derived from the code — you build that directly (see *Principles*). Use a snippet only when you genuinely need the person (the Step 1 question about a running UI comes first, as plain text, when the analysis starts — then continue with the code analysis without waiting for the answer):
 
 1. **Order** — *"Which comes first?"* → a `poll` with the candidate orders; *"I'd put A before B — right?"* → a `confirm`.
 2. **Unclear business requirement** — the code leaves it open or contradicts itself (*"Can a visit be cancelled?"*, *"Is the specialty optional?"*) → a `confirm` or `poll` with your hypothesis; an open answer stays text.
@@ -253,7 +257,7 @@ One question per message, with the best hypothesis attached. The answer arrives
 | Given/When/Then scenarios from the tests | `/eventmodeling-elaborating-scenarios` |
 | Add or rename attributes along a chain | `/attributes` |
 | Realistic example data from tests and fixtures | `/examples` |
-| A screen where a person decides | `/html-screen` (wireframe sketch only on explicit request: `/storyboard-screen`) |
+| A screen where a person decides | `/html-screen` — always HTML; a plain SCREEN only for a Playwright screenshot of the running UI (see *UI* lens), never `/storyboard-screen` |
 | Set a slice's status | `/update-slice-status` |
 | Record a decision with its code reference | *Recording decisions* (MARKDOWN note in the **Decisions** feedback lane) |
 | Open questions, unresolved code-vs-user conflicts | `/wdyt`, `/handle-comment` |
@@ -261,7 +265,16 @@ One question per message, with the best hypothesis attached. The answer arrives
 | Validate before reporting completion | `/eventmodeling-validating-event-models-checklist` |
 | Any endpoint or element type not covered above | `/learn-eventmodelers-api` |
 
-Scenarios: only business rules found in tests and comments — not simple validations ("must be a number"). Only create a storyline when the person explicitly asks.
+### Scenarios
+
+*Which* rules to write is specific to legacy code: only business rules found in tests and comments — not simple validations ("must be a number"). Only create a storyline when the person explicitly asks.
+
+*How* to write them is not — read `eventmodeling-elaborating-scenarios` before the first scenario and follow it; a test translated line by line is how wrong scenarios end up on the board. In particular:
+
+- **What goes into Given, When and Then** — per command and per read model: § *1. Command Scenarios*, § *2. Command Scenarios - State Validation*, § *3. View Scenarios*, § *3b. List-type Read Model Scenarios*, § *4. Error Path Scenarios* (worked examples in its `references/examples.md`).
+- **Which elements may appear in a step** — only those `get_spec_info` returns for the timeline: § *Post Scenarios to Board* → *Step 2 — Load valid step elements* and *Step 3 — Resolve step IDs*. A test's mocks, repositories or setup calls are never steps.
+- **Rejections** — § *Step 4c — Error/rejection scenarios*.
+- **Before reporting** — its § *Quality Checklist*.
 
 ---