@eventmodelers/cli 1.0.163 → 2.0.1

package/README.md

@@ -92,7 +92,6 @@ your-project/
 │   ├── ralph-claude.js            ← realtime agent + task loop
 │   ├── ralph-local-ai.js          ← same, via a local/self-hosted model
 │   ├── ralph-exec.js              ← same, via an external agent command (Codex CLI, OpenCode, …)
-│   ├── ralph.sh                   ← bash-only loop (no realtime)
 │   ├── lib/                       ← stack-specific agent prompts + helpers
 │   └── .slices/                   ← board slices, written by `fetch`/`listen` (or pre-seeded by `init --demo`)
 ├── .claude/
@@ -149,7 +148,6 @@ npx @eventmodelers/cli run --local-ai [target]      # board work only via a loca
 npx @eventmodelers/cli run --agent <name>           # pick the agent: claude (default), opencode, codex, gemini — bare --agent lists them with their exact commands
 npx @eventmodelers/cli run --agent <name> --model <id>  # …on a given model: -m for opencode/codex/gemini, --model for Claude, LOCAL_AI_MODEL for --local-ai
 npx @eventmodelers/cli run --exec "<command>"        # manual fallback for any other harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
-npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue
 npx @eventmodelers/cli run --standalone             # same, plus acting on board changes unprompted — and needs no install at all
@@ -210,7 +208,7 @@ Installing both a build stack and `init-modeling` into the same project reuses t
 
 A modeling-kit install has one runtime: a warm Claude process the CLI keeps alive across
 turns and feeds directly over stdin, so a prompt typed (or spoken) on the board is picked up
-with no cold start and no `tasks.json` round trip.
+with no cold start and no task-queue round trip.
 
 ```bash
 npx @eventmodelers/cli run --modeling               # react to prompts sent to this board
@@ -273,7 +271,7 @@ pass `--model <id>` as usual.
 
 Claude and Gemini need a gateway (e.g. LiteLLM) in front of a non-native server, since they only speak their own protocol.
 
-`--agent`, `--exec`, `--local-ai` and `--bash` each pick the runner, so pass at most one of them —
+`--agent`, `--exec` and `--local-ai` each pick the runner, so pass at most one of them —
 any two together are rejected. For a local or self-hosted model use `--local-ai`, not `--agent`.
 
 To drive either one with a local model instead of Claude, see [Running the modeling agent on a local model](#running-the-modeling-agent-on-a-local-model).
@@ -524,40 +522,37 @@ npx @eventmodelers/cli init-modeling --global
 
 Everything else (the kit dir, project scaffold, credentials, MCP registration) still targets the current directory as usual — `--global` only changes where skills land.
 
-### Bridging to another spec framework
+### Syncing a context to Spec Kitty
 
-If you drive development with a different spec/task framework (Spec Kitty today; more later) instead of build-kit's own code generation, a **bridge** kit keeps that framework's artifacts in sync with the board instead of writing application code:
+If you drive development with Spec Kitty instead of build-kit's own code generation, `fetch` can restate a context for it in one shot:
 
 ```bash
-npx @eventmodelers/cli init --bridge --target spec-kitty
-npx @eventmodelers/cli bridge
+npx @eventmodelers/cli fetch --context Ticketing --spec-kitty
 ```
 
-`init --bridge` installs a `.bridge-kit/` (mirrors `.build-kit/`'s realtime + task-queue loop) plus only the skills for the chosen `--target` (`shared/bridge/<target>/`) — a `spec-kitty` bridge never installs Kiro's skills, and vice versa. `bridge` starts the loop: on every board slice change (not just "Planned", unlike build-kit), it regenerates that framework's spec artifacts from the current board state. It doesn't build code and doesn't claim slices.
-
-For `spec-kitty`, that sync is deterministic and stops well short of writing Spec Kitty's own artifacts — `lib/adapters/spec-kitty-adapter.js` fetches full slice detail and restates it as a plain markdown mission brief (one section per slice, its scenarios verbatim, nothing invented), then calls `spec-kitty intake --force` to install it at `.kittify/mission-brief.md`. It deliberately doesn't create the mission, write `spec.md`, or author work packages — Spec Kitty's own `/spec-kitty.specify` → `/spec-kitty.plan` → `/spec-kitty.tasks` pipeline does that, because those steps need real judgment (work package boundaries, which files a WP owns, which agent profile fits) that only makes sense with actual codebase context, which this adapter doesn't have. What it replaces is Spec Kitty's *interactive discovery interview*: `/spec-kitty.specify`'s own "Brief Context Detection" step reads `.kittify/mission-brief.md` when present and extracts requirements from it instead of asking the user, so the event model — not a live Q&A — becomes the input. No LLM call happens in this adapter's own path, and `bridge` picks it automatically whenever a target has one (`--claude` forces the Claude runner instead). Targets without a static adapter yet fall back to Claude re-running `bridge-<target>-specify`; pass `--local-ai` for the local-model runner instead (same caveat as build-kit's `--local-ai`: `lib/local-ai-agent.js` is shared as-is).
+That sync is deterministic and stops well short of writing Spec Kitty's own artifacts — `lib/adapters/spec-kitty-adapter.js` fetches full slice detail and restates it as a plain markdown mission brief (one section per slice, its scenarios verbatim, nothing invented), then calls `spec-kitty intake --force` to install it at `.kittify/mission-brief.md`. It deliberately doesn't create the mission, write `spec.md`, or author work packages — Spec Kitty's own `/spec-kitty.specify` → `/spec-kitty.plan` → `/spec-kitty.tasks` pipeline does that, because those steps need real judgment (work package boundaries, which files a WP owns, which agent profile fits) that only makes sense with actual codebase context, which this adapter doesn't have. What it replaces is Spec Kitty's *interactive discovery interview*: `/spec-kitty.specify`'s own "Brief Context Detection" step reads `.kittify/mission-brief.md` when present and extracts requirements from it instead of asking the user, so the event model — not a live Q&A — becomes the input. No LLM call happens in this adapter.
 
-Don't want the standing loop at all? `fetch` can call the same adapter for a single one-shot sync, no `.bridge-kit/` install required:
-
-```bash
-npx @eventmodelers/cli fetch --context Ticketing --spec-kitty
-```
+`spec-kitty init` (Spec Kitty's own project setup) has to have already been run in the project root — the adapter checks for `.kittify/` first and stops with the exact command to run if it's missing, rather than failing deep inside a cryptic `spec-kitty` CLI error. After the sync, run `/spec-kitty.specify` in your coding agent to turn the brief into an actual mission (the plain `spec-kitty specify` CLI command only scaffolds — brief detection is in the agent-driven prompt).
 
-Either way, `spec-kitty init` (Spec Kitty's own project setup) has to have already been run in the project root — the adapter checks for `.kittify/` first and stops with the exact command to run if it's missing, rather than failing deep inside a cryptic `spec-kitty` CLI error. After the sync, run `/spec-kitty.specify` in your coding agent to turn the brief into an actual mission (the plain `spec-kitty specify` CLI command only scaffolds — brief detection is in the agent-driven prompt).
+(The standing bridge loop — `init --bridge` / `bridge` — is retired for now.)
 
-### Overriding the executor with a hook
+### Reading the event log
 
-Claude is only the default — some teams don't want an AI agent in this loop at all, e.g. they'd rather just commit + push the board export and let a CI pipeline own the actual translation. `--hook` replaces the AI executor with an arbitrary shell command, run once per batch of slice changes:
+Everything an agent does to a slice, a task, a prompt or a learning is an event in the kit's log (`.build-kit/events/` and `events.log`, or `.agent-modeling-kit/` for a modeling agent). `eventmodelers events` decodes it in the terminal — one line per event, with the slice's title and the first four characters of the agent that wrote it:
 
 ```bash
-npx @eventmodelers/cli init --bridge --target spec-kitty --hook "git add .slices && git commit -m sync && git push"
-npx @eventmodelers/cli bridge
+npx @eventmodelers/cli events                          # the build kit of this project, else its modeling kit
+npx @eventmodelers/cli events --type claimed,settled   # only these event types
+npx @eventmodelers/cli events --slice "Add item"       # a slice by id prefix or part of its title
+npx @eventmodelers/cli events --tag ci --last 20       # by tag; only the last 20 that remain
+npx @eventmodelers/cli events --state                  # what the log folds to: slices, queue, open prompts, learnings
+npx @eventmodelers/cli events --json                   # the raw events, one per line (pipe to jq)
+npx @eventmodelers/cli events --follow                 # keep printing as events are appended
+npx @eventmodelers/cli events --kit ../other/.build-kit   # another kit's log, from anywhere
+npx @eventmodelers/cli events --global                 # the global install's log (~/.eventmodelers/kit): what runs without a project install wrote
+npx @eventmodelers/cli events --global --board c2b3b7da   # that log mixes every board; --board keeps one (an id prefix)
 ```
 
-`init --bridge --hook` persists the command to `.bridge-kit/bridge.json` — a plain, **committed** file (unlike `.eventmodelers/config.json`, which is gitignored for credentials) since the hook is project policy meant to be shared by every teammate and CI runner, not per-machine state. `bridge --hook "<command>"` overrides it for a single run without touching that file. Only one executor runs per invocation — `--local-ai`, `--hook`, and `--claude` are mutually exclusive.
-
-The hook command runs with `BRIDGE_TASK_COUNT`, `BRIDGE_SLICE_ID`/`_TITLE`/`_STATUS` (the most recent change in the batch), and `BRIDGE_BATCH_FILE` (path to the full batch as JSON) in its environment. It's invoked once per batch, not once per slice — any change that arrives while the hook is still running is left queued for the next batch rather than dropped.
-
 ### Claude execution & config resolution
 
 During install you can optionally point the agent at a local LLM server instead of the default
@@ -630,7 +625,7 @@ npx @eventmodelers/cli init-config --name ci-builder     # name the agent this c
 
 ### Naming an agent
 
-Every agent identifies itself to the platform with an `agentId`, and the board's live-agent view shows that bare uuid. A **project install** mints one on first use and reuses it on every restart (`agentIds` in the project root's `.eventmodelers/config.json`). A **standalone/global run** mints a fresh one per run instead: nothing stops two ad-hoc agents running for one board, and since the heartbeat is keyed on `(token, agentId, agentType)`, a shared id would make the second agent replace the first — one agent visible however many are running, and their board writes indistinguishable.
+Every agent identifies itself to the platform with an `agentId`, and the board's live-agent view shows it. An agent keeps **one id**: a **project install** mints it on first use (`agentIds` in the project root's `.eventmodelers/config.json`), a **standalone/global run** keeps one per board and repo — the directory it is started in — in `~/.eventmodelers/agent-ids.json`. It is the same agent on every restart, with its chat sessions, its star on the board and the prompts it holds. Two live processes must not share an id (the heartbeat is keyed on `(token, agentId, agentType)`, so the second would replace the first, and its start-up recovery would hand back the first one's prompts), so each run takes a small lock on its id (`.eventmodelers/locks/` in the project, `~/.eventmodelers/locks/` globally); if another live process already holds it, this run gets a fresh id and, unless you named it, an instance-marked name (`cart-service (modeling) · 3f9a`). `--id` is used as given, with no such check — for a second agent on purpose, or a supervisor that knows the id it wants. Without a name an agent shows as `<repo> (<type>)`, the repo being the `origin` remote's name or the folder.
 
 `--name` gives an agent a readable label instead of the uuid — accepted by `init`, `re-init`, and `init-config`, saved into `config.json` as `agentName`, and sent with every heartbeat from then on:
 
@@ -763,7 +758,7 @@ npx @eventmodelers/cli re-init --modeling            # refresh the modeling kit
 npx @eventmodelers/cli re-init --stack supabase      # override which stack to refresh from (manifest missing/stale, or switching stacks)
 ```
 
-`re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of.
+`re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/skills without re-scaffolding a project you've since built on top of.
 
 You don't have to remember to: on startup every command prints a 💡 hint (on stderr) when a newer CLI is on npm, or when a kit in the current directory was installed by an older CLI than the one running — naming the exact `re-init` command to run. The npm lookup happens at most once a day (cached in `~/.eventmodelers/update-check.json`, 1.5 s timeout, silent when offline). Set `EVENTMODELERS_NO_UPDATE_CHECK=1` to turn it off; it is also off when `CI` is set.
 

package/RELEASE_NOTES.md

@@ -1,6 +1,24 @@
-## Unreleased
+## v2.0.0
+
+### Architecture: the kit now runs on an event log
+The CLI's local state used to live in mutable files — `tasks.json` as the queue, `progress.txt` as the learnings journal, a `.claim.json` claim record, and status edited in place in `index.json`/`slice.json`. Concurrent writers, a stale board refresh or a crash could each leave those files disagreeing with the board or with each other (the failure modes are written down in `slice-state-learnings.md`). 2.0.0 replaces all of it with **event sourcing**: everything an agent does to a slice, a task, a prompt or a learning is an immutable event appended to a log, and every other file is a projection folded from that log.
+
+- **The store.** One JSON file per event under `.build-kit/events/` (`.agent-modeling-kit/` for the modeling agent), written whole before its id is appended to `events.log`; the index line is what commits the event, so concurrent writers cannot tear the log whatever the event size. Events carry tags and `agent_id`/`organization_id`/`board_id` metadata. The store is git-ignored, and the loop's git rules now live in `.git/info/exclude` and `.git/info/attributes`, so starting an agent never dirties the tracked tree.
+- **A pure core.** `fold` derives status, claim, pending outcome, attempts, blocked state, the task queue, open prompts and learnings from the event list; `decideSettle` and `decideRecovery` turn that into push/discard/release actions. Side effects sit around the fold, not inside it.
+- **Slice lifecycle as events.** The loop claims a slice (`claimed`/`claim-confirmed`), settles it after the build by executing `decideSettle` (push the recorded outcome, or discard the attempt, record `attempt-failed` and put the slice back to its pickup status), and settles claims left by dead processes at the top of every iteration. Board refreshes are recorded as `board-observed`, so a stale refresh during a build can no longer revert what the agent recorded. The build agent records its outcome with `eventmodelers slice-status <status>`; the loop owns the status on the board.
+- **Attempts and auto-blocks come from the log**, not from an in-memory map, so a restart no longer hands a stuck slice a fresh budget.
+- **The task queue is the log.** A slice change arrives as `task-queued` (a newer change to the same slice replaces its task); the loop replays the log for the oldest task, hands it to the agent and appends `task-done`. A change landing mid-turn is just another event.
+- **Prompts are journaled.** `prompt-received`/`prompt-finished` bracket every prompt the modeling agent takes; on start, what a crash left open is looked up on the platform and handed back unless it already finished. Recovery asks the platform who holds a prompt (`claimed_by`) rather than tracking process ids.
+- **Learnings are events.** `eventmodelers learn` records one (topic, tags, scope; duplicates skipped) and `learn --retract` withdraws it; `learnings` lists them. `AGENTS.md` is rendered from the events and adopts lines added by hand, so regenerating never loses them. After `RALPH_CURATE_AFTER` (default 10) new learnings, a curator turn that can only merge and retract tidies the list (`learning-merged`, `learnings-curated`).
+- **Look at it.** `eventmodelers events` decodes the log in the terminal — one line per event with the slice title and the writing agent; `--type`, `--slice`, `--tag`, `--last`, `--json`, `--state` (what the log folds to), `--follow`, `--kit`, `--global` and `--board` narrow or redirect it.
+- **One agent id, one live process.** A standalone run keeps a stable agent id per board and repo, and takes an exclusive lock on it, so two processes never share an id, a heartbeat row or each other's prompts. A global install records nothing, so one board's learnings never surface in another's.
+
+### Breaking changes
+- `tasks.json` is gone. Nothing reads or writes a queue file any more; the stacks' `prompt.md` files lose their queue steps and the `IDLE` reply, and `AGENT.md` is now a reference.
+- `progress.txt` is gone. Learnings go through `eventmodelers learn`, a failed attempt is read from the slice's `lastAttempt`, and a block reason lives on its event.
+- `run --bash` (the bash-only loop: `ralph.sh`, `lib/agent.sh`, `realtime-agent.js`) is retired. The flag is still recognised, only to say so.
+- The bridge kit is retired: `init --bridge` (with `--target`/`--hook`), the `bridge` command and `uninstall --bridge-kit`. `fetch --spec-kitty` keeps working on its own.
 
-### Features
 - `run --modeling`/`run --standalone` accept `--local-ai`, so the modeling agent can be driven by a local or self-hosted model instead of Claude. It was previously rejected as a build-kit-only flag, which conflated two different things: `--bash`/`--exec` select a *queue* the modeling loop has no equivalent of, while `--local-ai` selects a *model*. Both wire dialects are supported — `--local-ai` (bare) or `--local-ai ollama` for Ollama's native `POST /api/chat`, and `--local-ai vllm`/`lmstudio`/`llamacpp` for the OpenAI-compatible `POST /v1/chat/completions` that vLLM, LM Studio, llama.cpp-server, TGI and SGLang serve; anything else OpenAI-compatible works via `LOCAL_AI_URL`. The loop itself is untouched: the prompt queue, the standalone board-change lane and its damping, the idle review and the platform's full MCP tool set all behave as before, because everything Claude-specific already sat behind a single `runTurn(text)` seam. What a local model cannot bring along is the part that is not a wire format — the skills (`/place-element`, `/timeline`, `eventmodeling-*`) and the subagent fan-out are Claude Code features — so a self-directed turn does the most valuable piece of work itself, inline, and the board rules it needs come from the new runner's system prompt (`lib/modeling-local-ai.js`) instead of `.agent-modeling-kit/CLAUDE.md`. `--max-agents` is ignored in this mode. Ollama's `num_ctx` is raised to 49152 by default (the MCP tool schemas alone are ~16k tokens, well past Ollama's 4096 default, which would silently truncate the tool block), with a warning when the schemas still fill >60% of it and a turn cap of 24 tool iterations.
 
 - `run --non-interactive` never asks anything: the board and credentials that resolve from flags, `EVENTMODELERS_*` env vars and the config files are final, and an incomplete set fails the run with the reason instead of being interviewed for. A missing TTY already implied this, which covered CI and most supervisors, but not a container started with `-it` or a loop started from a terminal — stdin is a TTY nobody is watching, and the run stopped on the board confirmation or the credentials question forever. `EVENTMODELERS_TOKEN` also now answers the credentials question on its own, the way `EVENTMODELERS_BOARD_ID` always answered the board question: an env var that outranks every config file makes asking where the credentials come from moot. The README gains a container recipe, including the two things a container needs that a laptop already had — a writable HOME for the global kit and per-board credentials, and a `LOCAL_AI_URL` that isn't `localhost`.