@eventmodelers/cli 1.0.153 → 1.0.155

package/README.md

@@ -155,6 +155,8 @@ npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude
 npx @eventmodelers/cli run --standalone             # same, plus acting on board changes unprompted — and needs no install at all
 npx @eventmodelers/cli run --standalone --board-id <uuid>  # …from any directory, against any board (see Power users)
 npx @eventmodelers/cli run --id <id> --name <label>  # override this run's agent identity (id + display name); `init --name` persists a name instead
+npx @eventmodelers/cli run --handover               # backend kit, this run only: finish slices that have a UI at `Handover` instead of `Done` (see Backend → UI handover)
+npx @eventmodelers/cli config --handover on|off      # persist that choice for the project (`handover` in .eventmodelers/config.json)
 npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/
 npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
 npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the slice matching this title
@@ -198,6 +200,10 @@ npx @eventmodelers/cli run --local
 
 and the agent starts building — `--local` skips platform config and credential lookup entirely, so it works straight out of `init` with nothing connected. Every TODO you fill in gets exercised on the next iteration against real slice data covering all four slice types (state change, state view, automation, translation), which is exactly the coverage a new stack's `build-*` skills need before it's worth promoting.
 
+**Backend → UI handover.** Besides the usual statuses a slice can be `Ready` (modeling done, waiting to be planned) and `Handover` (backend built, UI contract published, waiting for the UI kit). The flow is `Ready → Planned → InProgress → Handover → InProgress → Done`. Install with `init --handover` (or `re-init --handover`; switch later with `eventmodelers config --handover on|off`; for a single run `run --handover` overrides the setting without saving anything), which saves `"handover": true` in `.eventmodelers/config.json` — then a backend kit ends STATE_VIEW / STATE_CHANGE slices at `Handover` instead of `Done` (the `ui-contract` skill, Step 4, owns that rule); without the flag nothing changes: slices end at `Done`, exactly as before. A kit claims work from the status named in its `lib/kit.json` — `{ "pickupStatus": "Handover" }` for the `react` / `supabase-react` UI kits, absent (= `Planned`) for backend kits. A new UI kit ships that file and sets `Done` when its half is built; a new backend kit just invokes `ui-contract`. Needs a platform with the `Ready` / `Handover` statuses.
+
+**UI contract.** The scaffolded `build-state-view` / `build-state-change` skills already end by invoking the shared `ui-contract` skill, which publishes each slice's read (`GET`) or write (`POST`) contract — the endpoint's OpenAPI operation, as a ```` ```yaml ui-contract ```` block — as a `## UI Contract` section in the slice's feedback-lane markdown node (exported in `slice.json` `notes[]`, so a UI build kit can look it up directly). Two things are yours to decide: *where the contract is derived from* (point the `UI Contract` section of those skills at your stack's machine-readable API description, if it has one — the `node`/`supabase` stacks use their `@openapi` blocks via a `ui-contract-from-openapi.md` reference, taking the operation verbatim — otherwise the skill writes the equivalent OpenAPI operation from the route code), and, if you need a different shape or location, a whole-skill override: ship `.claude/skills/ui-contract/SKILL.md` in the stack's templates and it replaces the shared one (stack templates are applied after `shared/skills/`).
+
 Installing both a build stack and `init-modeling` into the same project reuses this one `.eventmodelers/config.json` — run whichever `init` command second and it finds the existing config already satisfies the required fields and skips straight past the credential prompt.
 
 ### The modeling agent — `run --modeling` and `--standalone`
@@ -649,6 +655,34 @@ Only prompts carrying this agent's id are worked. Anything untargeted is handed
 
 Pair it with `--id`: a `--standalone`/`--global` run mints a fresh id per run, so prompts addressed to the previous run's id are never claimed. `--exclusive` applies to the prompt queue only — a `--standalone` agent's self-directed turns are nobody's prompt, and it keeps taking them.
 
+### Backend → UI handover (`--handover`)
+
+A slice with a UI is only finished once two kits have each built their half: the backend kit builds the endpoint and publishes its contract, the UI kit builds the frontend against it. `--handover` makes the first kit stop at `Handover` instead of `Done`, so the second one can claim the slice.
+
+```bash
+npx @eventmodelers/cli init --stack node --handover   # persisted: "handover": true in .eventmodelers/config.json (also re-init)
+npx @eventmodelers/cli config --handover on           # switch it on later…
+npx @eventmodelers/cli config --handover off          # …or back off
+npx @eventmodelers/cli run --handover                 # this run only — writes nothing
+```
+
+| | Handover off (default) | Handover on |
+|---|---|---|
+| Backend kit, STATE_VIEW / STATE_CHANGE slice | ends at `Done` | publishes the UI contract, ends at `Handover` |
+| Backend kit, automation / translation | `Done` | `Done` — no UI counterpart |
+| UI kit (`react`, `supabase-react`) | claims `Handover` only | claims `Handover` only, sets `Done` when its UI is built |
+
+Flow: `Ready → Planned → InProgress → Handover → InProgress → Done`. Precedence for a run is `run --handover` over the project's `handover` setting; the runner states the effective value to the agent as a `Handover: on|off` line in its task, so the agent never has to work it out from `config.json`. `config --handover` writes to the project's config (the installed kit's project, else the nearest `.eventmodelers/config.json` up the tree — never the account-wide one in `~/`).
+
+**What to know before relying on it**
+
+- **UI kits only ever claim `Handover`.** Against a board whose backend finished slices at `Done`, a `react` / `supabase-react` kit has nothing to do and replies `NO_TASKS` — the backend side must run with handover on.
+- **Both sides need the new kit.** An already-installed backend kit keeps its old `ralph.js` and prompts and silently ignores `--handover` (slices still end at `Done`); `re-init` it to pick the feature up.
+- **The platform must know the `Ready` / `Handover` statuses.**
+- A kit declares what it claims in `lib/kit.json` — `{ "pickupStatus": "Handover" }`; absent means `Planned`.
+
+The contract itself is the shared `ui-contract` skill's job (see above); it also owns the rule for which status a slice ends at.
+
 ### Env vars and `--config` (scripted/CI installs)
 
 Every config field can be set via an `EVENTMODELERS_*` env var instead of the interactive prompts — these always win over whatever's in `config.json`, so a fully env-driven install never prompts for credentials or Claude execution settings:
@@ -759,7 +793,7 @@ npx @eventmodelers/cli uninstall --modeling-kit      # remove .agent-modeling-ki
 
 ### Adding a stack
 
-Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`, `request-feedback`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork.
+Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`, `request-feedback`, `ui-contract`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork. A stack overrides a shared skill by shipping one of the same name under its own `.claude/skills/` (e.g. a custom `ui-contract`).
 
 The demo model `init --demo` installs is shared the same way, in `shared/demo-slices/` — a verbatim `fetch --format json` tree (`current_context.json` plus `<context>/{context,index,config}.json` and `<slice>/slice.json`), copied as-is into the kit's `.slices/`. It's stack-agnostic board data, so a new stack gets `--demo` for free. To replace or extend it, `fetch` a context into an empty directory and copy the result in, then update `DEMO_CONTEXT_NAME`/`DEMO_SLICE_COUNT` in `cli.js` (used only for the line `init` prints).
 

package/cli.js

@@ -710,6 +710,18 @@ function findConfigInParents(startDir) {
   return existsSync(globalCandidate) ? globalCandidate : null;
 }
 
+// Where a project-level setting (`config --handover`, `--agent-tracing`) is written: the explicit
+// --config, else the installed kit's project, else the nearest project config up the tree — so it
+// lands in the file `run` merges in, even from a subdirectory — else this directory. The
+// account-wide ~/.eventmodelers/config.json is never a target: these are per-project policies.
+function projectConfigPath(cwd, kitDir, explicitConfig) {
+  if (explicitConfig) return resolve(explicitConfig);
+  if (kitDir) return join(dirname(kitDir), '.eventmodelers', 'config.json');
+  const found = findConfigInParents(cwd);
+  const globalPath = join(homedir(), '.eventmodelers', 'config.json');
+  return found && found !== globalPath ? found : join(cwd, '.eventmodelers', 'config.json');
+}
+
 function readJsonSafe(path) {
   if (!path || !existsSync(path)) return {};
   try {
@@ -983,9 +995,11 @@ async function installStack(stackKey, stackCfg, options = {}) {
       copyDirContents(claudeSkillsSrc, globalSkillsDir);
     } else {
       console.log('📦 Installing skills...');
-      copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
+      // Shared skills first, the stack's own templates last — so a build kit can override
+      // a shared skill (e.g. `ui-contract`) just by shipping a skill of the same name.
       copyDirContents(sharedSkills, join(targetDir, '.claude', 'skills'));
       if (isBridge) copyDirContents(sharedBridgeSkills, join(targetDir, '.claude', 'skills'));
+      copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
       claudeExtras = existsSync(join(templatesSource, '.claude'))
         ? readdirSync(join(templatesSource, '.claude')).filter((f) => f !== 'skills')
         : [];
@@ -1357,6 +1371,10 @@ async function configureCredentials({ config, configPath, targetDir, requiredFie
   if (!skipWrite) {
     writeFileSync(configPath, JSON.stringify(config, null, 2));
     console.log(`\n  ✓ Saved to ${relative(targetDir, configPath)}`);
+  } else if (overrides.handover) {
+    // A policy flag, not a credential — it must stick even when credentials were skipped.
+    writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), handover: true }, null, 2));
+    console.log(`  ✓ Handover on — saved to ${relative(targetDir, configPath)}`);
   }
   return config;
 }
@@ -3241,9 +3259,19 @@ const AGENT_NAME_OPTION = [
   'Human-readable name for the agent this kit runs (e.g. "ci-builder", "martins-laptop"), saved to config.json as `agentName` and sent with every heartbeat so the board shows a name instead of a bare uuid. Also settable via EVENTMODELERS_AGENT_NAME, and overridable for a single run with `run --name`.',
 ];
 
+// `--handover` is the project policy for how a backend build kit finishes a slice with a UI:
+// set, it ends STATE_VIEW / STATE_CHANGE slices at `Handover` (the UI kit builds the rest and sets
+// `Done`); unset, it ends at `Done`, exactly as before. Persisted as `handover: true` in the project's
+// config.json — the `ui-contract` skill (Step 4) reads it there. Switch it later with
+// `eventmodelers config --handover on|off`.
+const HANDOVER_OPTION = [
+  '--handover',
+  'Backend build kit: finish slices that have a UI at status `Handover` (UI build kit takes over, then sets `Done`) instead of `Done`. Saved as `handover: true` in .eventmodelers/config.json; without it slices end at `Done`. Turn it off later with `eventmodelers config --handover off`.',
+];
+
 function identityOverridesFromOpts(opts) {
   const agentName = typeof opts.name === 'string' ? opts.name.trim() : undefined;
-  return agentName ? { agentName } : {};
+  return { ...(agentName ? { agentName } : {}), ...(opts.handover ? { handover: true } : {}) };
 }
 
 credentialFlags(program
@@ -3262,7 +3290,8 @@ credentialFlags(program
   .option('--demo', 'Install a ready-made demo model into the kit\'s .slices/ — the "Understanding Eventsourcing" context (16 shopping-cart slices covering every slice type), in exactly the shape `fetch` writes, so the build skills and the agent loop have something real to work on before this project is connected to a board. Skipped if .slices/ already holds fetched slices. Off by default.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
-  .option(...AGENT_NAME_OPTION))
+  .option(...AGENT_NAME_OPTION)
+  .option(...HANDOVER_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
 
@@ -3384,7 +3413,8 @@ credentialFlags(program
   .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit) and wire it up via `git config core.hooksPath .githooks` — same as `init --hooks`, for turning it on after the fact without a full re-scaffold. Off by default.')
   .option('--global', 'Re-install skills into ~/.claude/skills/ instead of the project — defaults to however they were originally installed')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
-  .option(...AGENT_NAME_OPTION))
+  .option(...AGENT_NAME_OPTION)
+  .option(...HANDOVER_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
     const targetDir = process.cwd();
@@ -3686,6 +3716,7 @@ credentialFlags(program
   .option('--local', 'Skip platform config/credential lookup entirely and run the local-only loop (no board sync, no realtime agent) — even if .eventmodelers/config.json has credentials (build-kit stacks only)')
   .option('--dangerously-skip-permissions', 'Run the modeling agent\'s Claude process with --dangerously-skip-permissions, as before the lockdown: every tool call is approved — any shell command, curl to anywhere, any file the user can read or write, every MCP server the machine configures. Off by default because the agent takes chat messages and snippet clicks from any collaborator on the board; pass it only for a board whose collaborators you trust with your shell. Default Claude runner of --modeling/--standalone/--worker/--global only — not with --agent, --exec or --local-ai, which bring their own permission flags.')
   .option('--browser', 'Give the locked-down modeling agent a browser: the Playwright MCP server (npx @playwright/mcp) next to the eventmodelers one, for discover-storyboard. Off by default because a browser can reach any site, which the lockdown otherwise rules out. Default Claude runner only; --dangerously-skip-permissions already loads every MCP server the machine configures.')
+  .option('--handover', 'Backend build kit: for this run only, finish slices that have a UI at `Handover` instead of `Done` (same as the project setting `handover: true`, which `init --handover` / `config --handover on` save — this flag writes nothing). Without it the project setting applies; without both, slices end at `Done`.')
   .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
   .option('--id <id>', 'Pin the agent id this run identifies itself with on the platform. A project install otherwise mints one id per project and reuses it on every restart; --global/--standalone mints a fresh one per run, since two ad-hoc agents for one board must not share a row (the heartbeat is keyed on token + agent_id + agent_type, so the second would replace the first). Pass this when an agent has to keep ONE identity across restarts — a supervisor that already knows the id, or a board where it is the starred "preferred agent". Per-run only: nothing is written to disk.')
   .option('--name <name>', 'A human-readable name for this agent, sent with every heartbeat so the board shows which agent is live rather than a bare uuid (e.g. "ci-builder", "martins-laptop"). Per-run only, like --id: the persistent name is `agentName` in config.json (set via `init --name` / `init-config --name`), and this overrides it for one run without writing anything.')
@@ -3956,7 +3987,7 @@ credentialFlags(program
       // local-only branch even when .eventmodelers/config.json has valid credentials.
       // RALPH_AGENT_ID/RALPH_AGENT_NAME (--id/--name) are read in ralph.js's startRalph, so
       // they reach both node runners but not ralph.sh, which has no heartbeat to identify.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '', ...(typeof localAiTarget === 'string' ? { LOCAL_AI_TARGET: localAiTarget } : {}), ...(typeof opts.exec === 'string' ? { RALPH_EXEC_CMD: opts.exec } : {}) } });
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_HANDOVER: opts.handover ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '', ...(typeof localAiTarget === 'string' ? { LOCAL_AI_TARGET: localAiTarget } : {}), ...(typeof opts.exec === 'string' ? { RALPH_EXEC_CMD: opts.exec } : {}) } });
     } catch (err) {
       process.exit(err.status || 1);
     }
@@ -4174,7 +4205,9 @@ const SLICE_STATUSES = [
   { label: '🔄 InProgress', value: 'InProgress' },
   { label: '🔍 Review', value: 'Review' },
   { label: '🚫 Blocked', value: 'Blocked' },
+  { label: '🧭 Ready', value: 'Ready' },
   { label: '📅 Planned', value: 'Planned' },
+  { label: '🤝 Handover', value: 'Handover' },
   { label: 'ℹ️ Informational', value: 'Informational' },
 ];
 
@@ -4504,21 +4537,31 @@ program
 program
   .command('config')
   .description('Print the fully resolved config (merged across the directory hierarchy + EVENTMODELERS_* env vars), with the token masked')
+  .option('--handover <on|off>', "Turn the backend→UI handover on or off for this project (saved as `handover` in the project's .eventmodelers/config.json). On: a backend build kit ends slices that have a UI at `Handover`; off: at `Done`.")
   .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all. A non-Claude agent via run --exec is only traced when its command includes the harness's JSON output flag, e.g. \"codex exec --json --full-auto\".")
   .action((opts, command) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);
     const explicitConfig = command.optsWithGlobals().config;
 
+    if (opts.handover !== undefined) {
+      const value = String(opts.handover).toLowerCase();
+      if (!['on', 'off'].includes(value)) {
+        console.error('❌ --handover takes "on" or "off"');
+        process.exit(1);
+      }
+      const configPath = projectConfigPath(cwd, kitDir, explicitConfig);
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), handover: value === 'on' }, null, 2));
+      console.log(`✓ Handover ${value} — saved to ${relative(cwd, configPath) || configPath}\n`);
+    }
     if (opts.agentTracing !== undefined) {
       const value = String(opts.agentTracing).toLowerCase();
       if (!['on', 'off'].includes(value)) {
         console.error('❌ --agent-tracing takes "on" or "off"');
         process.exit(1);
       }
-      const configPath = explicitConfig
-        ? resolve(explicitConfig)
-        : join(kitDir ? dirname(kitDir) : cwd, '.eventmodelers', 'config.json');
+      const configPath = projectConfigPath(cwd, kitDir, explicitConfig);
       mkdirSync(dirname(configPath), { recursive: true });
       writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), agentTracing: value === 'on' }, null, 2));
       console.log(`✓ Agent tracing ${value} — saved to ${relative(cwd, configPath) || configPath}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.153",
+  "version": "1.0.155",
   "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/adapters/pocketbase-realtime-adapter.js

@@ -24,33 +24,59 @@ export async function createPocketBaseRealtimeAdapter(cfg, initialToken, deps =
   const pb = new PocketBase(cfg.pocketbaseUrl);
   pb.authStore.save(initialToken, null);
 
-  // One listener per topic; subscribe() replaces the topic's previous one (see realtime-adapter.js).
-  const listeners = new Map();
+  // The SDK adds one EventSource listener per subscribe() call — and keeps it when the call
+  // fails — so a flaky connection retrying per topic piles listeners up (Node warns at 11).
+  // Hence a single SDK subscription for the whole adapter, fanned out to topics here.
+  // subscribe() replaces the topic's previous handlers (see realtime-adapter.js).
+  const topics = new Map();
+  let sdkUnsubscribe = null;
+  let connecting = null;
+
+  const connect = async () => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        sdkUnsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
+          if (e.action !== 'create') return;
+          const entry = topics.get(e.record.topic);
+          entry?.handlers[e.record.event]?.(e.record.payload);
+        });
+        return;
+      } catch (err) {
+        // Drop the listener the failed call left behind before trying again.
+        await pb.collection(REALTIME_EVENTS_COLLECTION).unsubscribe('*').catch(() => {});
+        if (attempt >= RECONNECT_INTERVALS_MS.length) throw err;
+        topics.forEach((t) => t.onStatus?.(`RECONNECTING (attempt ${attempt + 1}/${RECONNECT_INTERVALS_MS.length}): ${err.message}`));
+        await new Promise((resolve) => setTimeout(resolve, RECONNECT_INTERVALS_MS[attempt]));
+      }
+    }
+  };
+
+  // Concurrent subscribe() calls share one in-flight connect — sdkUnsubscribe is only set
+  // after the await, so without this each would open its own SDK subscription.
+  const ensureSdkSubscription = () => {
+    if (sdkUnsubscribe) return Promise.resolve();
+    connecting ??= connect().finally(() => { connecting = null; });
+    return connecting;
+  };
+
   const remove = async (topic) => {
-    const unsubscribe = listeners.get(topic);
-    if (!unsubscribe) return;
-    listeners.delete(topic);
+    topics.delete(topic);
+    if (topics.size || !sdkUnsubscribe) return;
+    const unsubscribe = sdkUnsubscribe;
+    sdkUnsubscribe = null;
     await unsubscribe().catch(() => {});
   };
 
   return {
     async subscribe(topic, handlers, onStatus) {
-      await remove(topic);
-      for (let attempt = 0; ; attempt++) {
-        try {
-          const unsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
-            if (e.action !== 'create' || e.record.topic !== topic) return;
-            handlers[e.record.event]?.(e.record.payload);
-          });
-          listeners.set(topic, unsubscribe);
-          onStatus?.('SUBSCRIBED');
-          return;
-        } catch (err) {
-          if (attempt >= RECONNECT_INTERVALS_MS.length) throw err;
-          onStatus?.(`RECONNECTING (attempt ${attempt + 1}/${RECONNECT_INTERVALS_MS.length}): ${err.message}`);
-          await new Promise((resolve) => setTimeout(resolve, RECONNECT_INTERVALS_MS[attempt]));
-        }
+      topics.set(topic, { handlers, onStatus });
+      try {
+        await ensureSdkSubscription();
+      } catch (err) {
+        topics.delete(topic);
+        throw err;
       }
+      onStatus?.('SUBSCRIBED');
     },
     unsubscribe(topic) {
       return remove(topic);

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

@@ -242,7 +242,8 @@ async function fetchAndPersistSlices(cfg, kitDir) {
   if (!activeCtx || !contexts[activeCtx]) {
     // First run (or the current context disappeared): seed with a context that
     // has planned work, else the first one. This is the ONLY place we choose it.
-    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === 'planned'));
+    const pickup = readPickupStatus(kitDir).toLowerCase();
+    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === pickup));
     activeCtx = plannedCtx || Object.keys(contexts)[0] || 'default';
     writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
   }
@@ -400,11 +401,12 @@ async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
   await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
     console.error('[agent] Slice persist error:', err),
   );
-  // Planned slices are handled by onPlannedSlice directly — no task needed.
+  // Slices in the kit's pickup status (Planned, or Handover for UI kits) are handled by
+  // onPlannedSlice directly — no task needed.
   // queueAllStatuses opts out of that split entirely (e.g. bridge has no
   // onPlannedSlice consumer, so a lingering Planned slice would otherwise
   // never naturally clear its own trigger — see lib/ralph.js callers).
-  if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== 'planned') {
+  if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== readPickupStatus(kitDir).toLowerCase()) {
     await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
   }
 }
@@ -513,6 +515,17 @@ function hasPendingTasks(kitDir) {
   return readTasks(join(kitDir, 'tasks.json')).length > 0;
 }
 
+// The slice status this kit claims work from. A stack declares it in `lib/kit.json`
+// ({ "pickupStatus": "Handover" } for the UI kits, which build what a backend kit handed over);
+// absent means "Planned", the backend default.
+export function readPickupStatus(kitDir) {
+  try {
+    const s = JSON.parse(readFileSync(join(kitDir, 'lib', 'kit.json'), 'utf-8')).pickupStatus;
+    if (typeof s === 'string' && s.trim()) return s.trim();
+  } catch {}
+  return 'Planned';
+}
+
 function readCurrentContext(kitDir) {
   const ctxPath = join(kitDir, '.slices', 'current_context.json');
   if (!existsSync(ctxPath)) return null;
@@ -541,13 +554,14 @@ function getFirstPlannedSlice(kitDir) {
   try {
     others = readdirSync(slicesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
   } catch {}
+  const pickup = readPickupStatus(kitDir).toLowerCase();
   const candidates = [...(currentCtx ? [currentCtx] : []), ...others.filter((c) => c !== currentCtx)];
   for (const ctx of candidates) {
     const indexPath = join(slicesDir, ctx, 'index.json');
     if (!existsSync(indexPath)) continue;
     try {
       const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
-      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === 'planned');
+      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === pickup);
       if (!planned) continue;
       if (ctx !== currentCtx) {
         writeFileSync(join(slicesDir, 'current_context.json'), JSON.stringify({ name: ctx }, null, 2), 'utf-8');
@@ -673,11 +687,20 @@ async function runWithRetry(label, fn) {
 // alone, the agent read it as background, answered "what would you like me to help with?" with
 // no tool calls, and a Planned slice stayed Planned until the stuck-slice guard blocked it. So
 // every turn ends with the concrete request — here, once, for every runner.
-function taskRequest(planned = null) {
+// Whether a backend kit finishes UI-bearing slices at `Handover` instead of `Done`: this run's
+// `run --handover` (RALPH_HANDOVER) over the project's `handover` setting in config.json.
+export function resolveHandover(cfg) {
+  return process.env.RALPH_HANDOVER === '1' || cfg?.handover === true;
+}
+
+function taskRequest(planned = null, cfg = null, pickupStatus = 'Planned') {
   const task = planned
-    ? `build the Planned slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
+    ? `build the ${pickupStatus} slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
     : 'process the pending tasks in tasks.json';
-  return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n`;
+  // Stated explicitly so the agent never has to work it out from config.json: this run's effective
+  // value, which is what the `ui-contract` skill (Step 4) follows. UI kits (pickup Handover) ignore it.
+  const handover = planned && pickupStatus === 'Planned' ? `\nHandover: ${resolveHandover(cfg) ? 'on' : 'off'}\n` : '';
+  return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n${handover}`;
 }
 
 async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false) {
@@ -718,7 +741,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
         continue;
       }
 
-      const prompt = readFileSync(backendPromptFile, 'utf-8') + taskRequest(planned);
+      const prompt = readFileSync(backendPromptFile, 'utf-8') + taskRequest(planned, cfg, readPickupStatus(kitDir));
       if (credentialed) await fetchFullSlice(cfg, kitDir, planned.id);
       lastReply = null;
       const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, async () => { lastReply = await onPlannedSlice(prompt, {

package/shared/skills/connect/SKILL.md

@@ -289,7 +289,7 @@ Connecting is also where the session's read discipline starts. Every skill that
 
 The orientation read also tells you what you may write to. `get_board_outline` returns `sliceStatus` per column — a slice owns a column, so every element in that column shares its status. `get_nodes` does **not** carry it, so take it from the outline before any write:
 
-**Only a slice in `Created` may be written to.** Any other status — `Planned`, `Assigned`, `InProgress`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working on that slice: read its elements for context, but never change, move, rename or delete them, and never add scenarios, fields or examples to them. An element in a column with **no** `sliceStatus` is in no slice at all, which is not the same as locked — that one is writable.
+**Only a slice in `Created` may be written to.** Any other status — `Ready`, `Planned`, `Assigned`, `InProgress`, `Handover`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working on that slice: read its elements for context, but never change, move, rename or delete them, and never add scenarios, fields or examples to them. An element in a column with **no** `sliceStatus` is in no slice at all, which is not the same as locked — that one is writable.
 
 Never spend a `list_slices`/`get_slice_data` call to answer this; the outline already did.
 

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -644,7 +644,7 @@ Create a complete slice (1 column + its nodes automatically placed).
     interaction?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
     swimlane?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
   }
-  status?: 'Created' | 'Planned' | 'InProgress' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
 }
 ```
 
@@ -671,7 +671,7 @@ Create a standalone SLICE_BORDER node spanning an **existing** column. Unlike th
 {
   columnId: string   // id of an existing column on this timeline
   title: string      // slice title — always taken from this field, never derived
-  status?: 'Created' | 'Planned' | 'InProgress' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
   data?: Record<string, unknown>   // optional node.data payload
   meta?: Record<string, unknown>   // optional extra meta fields (type, colId, title are always set explicitly and cannot be overridden here)
 }
@@ -845,7 +845,8 @@ How much each slice of one context has been reworked — read-only, derived from
 for it.
 
 A slice's rework is read from its own SLICE_BORDER history. Going backwards means a step down the progress order
-(Created → Planned → Assigned → InProgress → Review → Done), or reaching `Blocked` from `Review`/`Done`;
+(Created → Ready → Planned → Assigned → InProgress → Handover → Review → Done), or reaching `Blocked` from
+`Handover`/`Review`/`Done`;
 `Informational` is never scored. `reopens` counts transitions leading away from `Done`, `changes` counts writes to the
 slice itself. This says nothing about edits to the elements inside a slice.
 
@@ -854,6 +855,7 @@ context (the same rule `slicedata` uses), so one that inherits a context is repo
 none is its own. Any other node type is rejected. Always scoped to one context; there is no board-wide form.
 
 **Response**: `200` — `{ contextId, contextName, metrics, slices[] }`, slices most reworked first.
+`metrics.progress` is where the slices stand now: `done`, `inProgress` (Assigned/InProgress/Review), `handover`, `ready`, `blocked`, `planned` (Planned/Created) as counts plus a `…Rate` share each, over the non-Informational slices, summing to 1.
 `slices[]` = `{ sliceId, title, status, changes, reopens, regressions, everReachedDone }`.
 `metrics` = `{ slices, everReachedDone, reopenedAfterDone, firstTimeRightRate, currentlyReopened, avgReopensPerSlice,
 avgChangesPerSlice }` — `firstTimeRightRate` is the share of the slices that reached Done and never came back, or
@@ -1172,11 +1174,12 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | to show several screens at once — a list, a gallery, a storyboard ("show me all screens of X") | `walkthrough`, one step per screen | nothing — selecting a step pans the canvas |
 | to answer where one piece of information comes from and where it ends up ("where is the customer email used?") | `dataJourney` | nothing — element names pan the canvas |
 | to show a diagram you drew yourself — a context map, a domain story, a sketch, any picture that isn't a chart | `svg` | nothing |
+| to show a UML or flow diagram you write as Mermaid — a sequence, flowchart, state, ER or class diagram | `mermaid` | nothing |
 | to lay out rows and columns — a comparison, a matrix (stressors × elements), a short list with a few attributes | `table` | nothing — linked cells pan the canvas |
 | to show a prototype you just built and uploaded (the `prototype` skill), running in the chat | `prototype` | nothing — **Full screen** opens the board's prototype player |
 | something the customer defined their own snippet type for (a risk card, a sign-off — see `list_snippet_types`) | `custom` | the clicked action's `answer`; `context.snippetReply.then` says what to do |
 
-`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `table` and `prototype` are display only and never wait for anything.
+`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `mermaid`, `table` and `prototype` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1225,6 +1228,8 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
   title?: string, caption?: string,
   links?: Array<{ nodeId: string, x: number, y: number,                           // ≤ 200 clickable areas over the picture, in the svg's viewBox coordinates;
                   width: number, height: number, title?: string }> }             // a click zooms the canvas to nodeId; title = tooltip (else the element's title)
+{ kind: 'mermaid', source: string,                                               // Mermaid source, no ``` fence (≤ 60000 chars); the app draws it
+  title?: string, caption?: string }
 { kind: 'table', title?: string, caption?: string,
   columns: Array<string | { label: string, nodeId?: string,                      // 1–12; nodeId makes the header a link (a matrix with one column per element)
                             align?: 'left' | 'center' | 'right' }>,
@@ -1247,6 +1252,7 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 - **`dataJourney`** answers "where does X come from / where is X used?" for **one piece of information**, as a table: one stop per element it passes through, in flow order, each with its `role`, the field name there and the slice. A headline counts the roles ("Originates in 1 place, stored in 2 elements and used in 3 places"). Build it from the board — the `data-journey` skill (modeling kit) has the procedure; every `nodeId` must be a real id from this board, and a field the board doesn't carry is not a stop. Keep `text` to one line naming the data and where it originates.
 - **`svg`** is for a picture you draw yourself: give the root a `viewBox` (and `width`/`height` for its natural size), inline colours and fonts — it is shown as an image, so scripts, `<a>` links and external resources do nothing. To make parts of it clickable, list them in `links`: a rectangle in the viewBox coordinates you drew in plus the element it stands for (only real ids from this board); the app lays a clickable area over each that zooms the canvas there. Prefer `report` for numbers. A domain story (who does what with which work object) is an `svg` you draw — the `domain-story` skill (modeling kit) has the procedure and the drawing style. Every SVG snippet has a download-as-PNG button.
   - **"Place it on the board" after you drew an SVG always means: put that picture on the board as an image** — never rebuild it from elements (stickies, lanes, a timeline), never a SCREEN, never a new snippet. `place_image` with `imageBase64` = the SVG document itself, base64-encoded, `mimeType: "image/svg+xml"`, `title` = the snippet's title: it becomes an OUTLINE (the drawing tools' image element), free-floating at `x`/`y`, in no chapter and connected to nothing. Place it where the person says, else in free space next to the chapter it is about (`get_chapter_bounds`: right of or below it). Add a white background `<rect>` first if the SVG has none, or it is unreadable on a dark board. One SVG = one image. The image on the board has no clickable areas — `links` stay in the chat.
+- **`mermaid`** is for a diagram you can write as text: a sequence diagram (`sequenceDiagram`), a flow (`flowchart LR`), states (`stateDiagram-v2`), an ER or class diagram. Send just the source; the app draws it, with a *Show source* toggle and a copy button, and shows the source when it has a syntax error — so keep the syntax plain (quote labels with special characters). Prefer it over a `code` block for any diagram: a `code` block with `language: "mermaid"` is drawn too, but `mermaid` says what you mean. It has no element links; for clickable parts draw an `svg`.
 - **`table`** is for anything that is rows and columns and not a chart: a comparison of options, an incidence matrix (rows = stressors, columns = elements, `true` where it hits), a short list with a few attributes per item. It computes nothing — totals are a row you add. Put element ids in `nodeId` (header or cell) so names are links; a row longer than the columns is cut, a shorter one padded, an empty one dropped. Prefer `report` for numbers you want *seen* as a trend or share, `dataJourney` for one piece of data's path.
 - **`prototype`** runs a prototype in the chat: the page the platform stored for `timelineId` (the `contextId` the `prototype` skill uploaded under — any timeline of that context works too), in a sandboxed iframe with **Restart** (empty event log) and **Full screen** (the same player as the timeline's ▶). Send it only after `upload` succeeded — before that it shows "No prototype has been built for this yet". The `text` is the short report of what was built; the prototype itself is the snippet.
 - A snippet is shown exactly as you send it — keep secrets and tokens out of `code` and `image`.

package/shared/skills/ui-contract/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: ui-contract
+description: Publish the slice's UI contract — the OpenAPI operation of its endpoint (read = GET, write/state-change = POST) — as its own `## UI Contract` section in the slice's MARKDOWN node in the feedback lane, which the slice export carries in `slice.json` `notes[]` — so the UI build kit finds the contract in one lookup instead of parsing the whole note. Called by every build-state-view / build-state-change skill after the endpoint is built. A build kit can override it by shipping its own `ui-contract` skill.
+---
+
+# UI Contract
+
+The UI build kit builds the frontend against what the backend slice **actually exposes**. This skill
+records that as a contract — the endpoint's **OpenAPI operation**, one per slice, in a fixed, machine-findable place.
+
+> Invoke `connect` first if not already connected (`BOARD_ID`). Prefer `mcp__eventmodelers__*` tools;
+> the REST equivalents are in `learn-eventmodelers-api`.
+>
+> **Override**: a build kit that needs a different contract shape or location ships its own
+> `.claude/skills/ui-contract/SKILL.md`. The kit's copy replaces this one at install time (stack
+> templates are applied after the shared skills). Callers only say "invoke `ui-contract`" — they never
+> restate the format.
+
+## When
+
+At the end of building a slice, **after** the endpoint exists (so the contract describes the real
+route, not the plan), before the final commit:
+
+| Slice type | Contract kind |
+|---|---|
+| `STATE_VIEW` (READMODEL) | **read** — `GET` |
+| `STATE_CHANGE` (COMMAND) | **write** — `POST` (a state change) |
+| `AUTOMATION` | none — no UI counterpart, skip |
+
+## Step 1 — Derive the OpenAPI operation from the built endpoint
+
+Never copy from the plan — the contract describes what was built. The contract **is** the endpoint's
+OpenAPI 3 operation (one path, one verb) — no second, hand-made shape.
+
+1. **Use the source the stack names.** If the calling `build-state-view` / `build-state-change`
+   skill's `## UI Contract` section points to the stack's machine-readable API description (e.g. the
+   handler's `@openapi` block), take that operation **verbatim** — see the stack's
+   `ui-contract-from-openapi.md`. Do not rewrite it.
+2. **Otherwise read the endpoint's route/handler code** and write the equivalent OpenAPI operation:
+   method, path, `parameters` (path / query / header), `requestBody` schema, and a response for the
+   success status and for every error status the handler really returns.
+3. **Trim to what a UI needs**: drop `tags`, internal notes and anything about storage or auth plumbing
+   (keep `security` if set). Keep `summary`, `description`, parameter/field `example`s and the response
+   descriptions — they carry the business meaning of each error status.
+4. **Cross-check against `slice.json`**: the request-body / response property names must equal the
+   command's / read model's `fields[]` (path parameters such as the generated id excepted). A mismatch
+   is an implementation bug — fix the code, don't publish a contract that disagrees with `slice.json`.
+
+## Step 2 — Write the `## UI Contract` section into the slice's MARKDOWN node
+
+1. **Find the node, creating whatever is missing** — never skip or fail because it doesn't exist yet:
+   1. `get_board_outline { boardId, chapterId }` → locate the slice's column and the chapter's
+      `feedback` lane. **No feedback lane** → create it: `add_lane { boardId, timelineId, lanes: [{ type: "feedback", label: "Notes" }] }`
+      (returns the `laneId`; a feedback lane sorts after the spec lane automatically).
+   2. Look for a `markdown` node in the feedback lane in the slice's column. **None** → create it with a
+      `node:created` event through `submit_node_events` (not `place_element` / cell-drop):
+      `{ "id": "<fresh uuid>", "eventType": "node:created", "nodeId": "<fresh uuid>", "chapterId": "<chapterId>",
+      "cellId": "<feedbackRowId>-<columnId>", "meta": { "type": "MARKDOWN", "title": "<slice title>",
+      "description": "## UI Contract\n\n…" } }` — the new node's body is just the section in the format of item 3 below.
+2. **Upsert only the section** (skip the read when you just created the node): read the node once (`get_node`), then replace the text from the
+   `## UI Contract` heading to the next `## ` heading (or end of file) — or append it when absent.
+   Leave every other section untouched. Write back `meta.description` via a `node:changed` event
+   (`submit_node_events`; the content lives in `description`, never `content`).
+3. **Section format** — exactly this, so it can be extracted with a single match:
+
+````markdown
+## UI Contract
+
+**READ** `GET /api/customers/{customerId}/reservation` — <one-line purpose>
+
+```yaml ui-contract
+/api/customers/{customerId}/reservation:
+  get:
+    summary: ...
+    parameters: [...]
+    responses: {...}
+```
+````
+
+`**READ**` for a `GET`, `**WRITE**` for a `POST`.
+
+**Formatting is part of the contract.** The note renders as Markdown, so `meta.description` must contain
+*real* line breaks — build the string with actual newlines (a multi-line string, or `\n` that the JSON
+parser turns into a newline), never a single line and never a literal backslash-`n` in the stored text.
+Blank line after the heading, blank line before and after the fenced block, the opening ```` ```yaml ui-contract ````
+and the closing ```` ``` ```` each on their own line, and the YAML keeps its indentation (2 spaces). After
+the write, read the node back once (`get_node`) and check that `description` has multiple lines and no
+literal `\n`; if it is flat, rewrite it before moving on.
+
+The fenced block whose info string is `ui-contract` is the single source: the operation alone, keyed by its path — no `openapi:`/`info:`/`servers:`
+wrapper, no restated table.
+
+## Step 3 — Nothing else to write
+
+The board is the single source. The slice export (`fetch` / `get_slice_data`, full projection) carries
+every MARKDOWN node of the slice's column as a plain string in `slice.json` `notes[]` (the
+`outline` / `fields` / `specs` projections leave `notes` out). The UI build kit therefore needs no
+extra file and no board call.
+
+## Step 4 — Completion status: `Handover` instead of `Done`
+
+A slice with a UI is only finished once the UI kit has built its half. Whether this build kit hands
+over is decided per run, in this order: the task request's `Handover: on|off` line (authoritative — the
+runner resolves `run --handover` over the project setting), else `"handover": true` in
+`.eventmodelers/config.json` (saved by `init --handover` / `eventmodelers config --handover on|off`).
+
+- **On** — the build kit's "set the slice to `Done`" for a STATE_VIEW / STATE_CHANGE slice means
+  **`Handover`** instead: after the contract is published and the commit/merge succeeded, via
+  `update-slice-status` (mirrored in the local `index.json`). The UI kit claims `Handover` slices and sets
+  `Done` when its UI is built.
+- **Off / unset** — nothing changes: `Done`.
+- Automations and translations have no UI → always `Done`.
+
+## How the UI build kit looks the contract up
+
+1. In the slice's `slice.json`, take the `notes[]` entry that contains a `## UI Contract` heading.
+   Ignore every other entry.
+2. In that entry, take the fenced block whose info string is `ui-contract` (```` ```yaml ui-contract ````)
+   and parse just that YAML — an OpenAPI operation keyed by its path: request = path/verb +
+   `parameters` + `requestBody`, success = the 2xx `responses` entry, errors = every non-2xx entry.
+   Ignore the rest of the note.
+3. No such entry → the backend slice isn't built yet, or the slice wasn't re-fetched since; re-fetch
+   once, and if still absent build against `slice.json` and note the assumption.
+
+## Re-running
+
+Idempotent: a rebuilt slice overwrites its own section; it never duplicates the
+section and never touches other sections of the note.