@jwilger/pi-development-system 0.85.0 → 0.87.0

package/README.md

@@ -20,13 +20,19 @@ plain words: when a prompt asks for new work, a fix or a review, the system adds
 naming the tool to use (`devsys_intake`, `devsys_review_start`). A `devsys` tool always shows
 what the current phase expects. When you say a slice is finished with no review round recorded,
 it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`,
-`/devsys-lens-review`, `/devsys-adr`) are shortcuts to the same tools.
+`/devsys-lens-review`, `/devsys-adr`, `/devsys-event-model`) are shortcuts to the same tools.
 
 Product planning has a skill (`product-planning`: brief, decision register, follow-ups,
 terminology, journeys). `devsys_lens_review` plans a review of the brief by five product lenses and
 writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
 a commit that shapes the architecture without one is stopped by the soft gate `adr.missing`.
 
+Event modelling has a skill (`event-modelling`: three slice patterns, Given/When/Then, completeness).
+`devsys_event_model_check` validates a directory of slice files (schema v1) and renders the swimlane
+Markdown or a Mermaid diagram; each profile's `gwt-tests` reference turns scenarios into failing tests.
+A dedicated extension that offers `event_model_validate`, or `event_model.provider` in
+`.development-system.toml`, replaces the builtin tool (`docs/event-model-extension-contract.md`).
+
 A slice has a life cycle: `implementing` → `reviewing` (when a review round starts) → `delivering`
 (review satisfied) → `idle`. Editing production source while delivering reopens `implementing`,
 and red-first stays on throughout. A push of a clean tree closes a delivered slice by itself (a commit
@@ -34,6 +40,10 @@ in `local-only` mode; CI is not awaited), and `devsys_finish_slice` closes it ex
 reason, abandons it. A plan's increments each end in a push, so each increment is its own slice: the
 next one starts with `devsys_intake`.
 
+`devsys_intake` does not interrupt autonomous work: Jev's size is used when Jev is at least 50%
+confident, and the user is asked to pick only when it is less sure (or unavailable). A size decided up
+front, such as in a goal's planning, is passed as `size` and skips the sizing question entirely (a `fix` still asks whether to waive review).
+
 With `codemode` enabled (`"defaultTools": ["+codemode"]` in pi settings), rarely used tools are
 reached through scripts and the `judge_*` Jev wrappers exist for scripts only; without codemode
 the rarely used tools are declared directly and the wrappers are absent.

package/extensions/development-system.ts

@@ -29,6 +29,7 @@ import { createJevHolder } from "../src/jev/holder.ts";
 import { createJudgeTools } from "../src/jev/judge-tools.ts";
 import { createAdrNewTool } from "../src/planning/adr-tool.ts";
 import { createBeginWorkTool } from "../src/planning/begin-tool.ts";
+import { registerEventModelProvider } from "../src/planning/event-model-provider.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
 import { createFinishSliceTool, registerSliceClose } from "../src/planning/slice-close.ts";
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
@@ -179,6 +180,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
   pi.registerTool(createAdrNewTool({ now: () => new Date() }));
+  registerEventModelProvider(pi);
   pi.registerTool(createFinishSliceTool({ state, exec }));
   pi.registerTool(
     createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/prompts/devsys-event-model.md

@@ -0,0 +1,11 @@
+---
+description: Model a capability as event-model slices and validate them
+argument-hint: "[directory of slice files, default docs/event-model]"
+---
+Event-model the work with the event-modelling skill.
+
+1. If a tool named `event_model_validate` exists, an event-model extension is installed: use it for validation and rendering instead of the builtin check, and follow its own prompt.
+2. Otherwise write one slice file per command, view or automation under the directory ($ARGUMENTS, default `docs/event-model`), in the schema the skill describes.
+3. Call `devsys_event_model_check` with that directory. Fix every error it reports; `render` asks for the derived Markdown or Mermaid view. Do not edit the derived views by hand.
+4. If the validator wants a fact the model does not have, ask the user. Never invent a policy, field or event to make validation pass.
+5. When the model is clean, write one failing test per Given/When/Then scenario with the profile's `references/gwt-tests.md`.

package/prompts/devsys-plan.md

@@ -9,4 +9,4 @@ Write the plan for the current work with the work-intake-and-slicing skill.
 3. Write each task so that someone who sees only that task could finish it. Never write `TBD`.
 4. Run `devsys_task_check` on every task record you wrote and fix each one until it says ready. Split any that come back too-big.
 5. Stop and ask the user to review the plan before any implementation starts. Do not start a goal yet: a goal tool may continue on its own and begin implementing before the review.
-6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the increment is built; it does nothing if the work is already implementing). A push of a clean, reviewed tree closes the slice, so each later increment starts with `devsys_intake`. Then, if a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
+6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the increment is built; it does nothing if the work is already implementing). A push of a clean, reviewed tree closes the slice, so each later increment starts with `devsys_intake`. Then, if a `create_goal` tool exists in this session, call it with the objective (name each increment's size in it, so every later `devsys_intake` passes `size` and nobody is asked to size it; a `fix` still asks the user whether to waive review) "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.

package/prompts/devsys-start.md

@@ -5,7 +5,7 @@ argument-hint: "<what you want done>"
 Start new work with the work-intake-and-slicing skill.
 
 1. Call `devsys_intake` with `request` set to: $ARGUMENTS (if empty, ask the user what they want done first).
-2. Show the user the proposed size and artifacts. The tool asks them to confirm or change the size.
+2. Show the user the size and artifacts. Jev sizes the work and intake proceeds without asking when it is at least 50% confident; only a less confident Jev makes the tool ask the user to pick. If the size is already decided (say, in a goal's or plan's up-front planning), pass it as `size` and nobody is asked to size it (a `fix` still asks whether to waive review).
 3. Produce the planning artifacts first (brief, decision register, journeys, event model, architecture, lens review, in that order, whichever are recommended), then the task record. `review` and `adr-if-needed` are not written up front: review happens on the finished slice, and an ADR when a decision needs one. To skip one, call `devsys_record_departure` with gate `artifact.skipped:<artifact>` and the reason; do not skip silently. The event model and architecture are recommendations, never gates.
 4. For `capability` and `product` the phase stays `planning` while you produce the artifacts and the plan. The single point where it changes is the user approving the whole plan: then call `devsys_begin_work` so the review and red-first gates switch on (it does nothing if already implementing).
-5. For a confirmed `fix` the user is also asked whether to skip fresh-context review (it is logged if they say yes; if no, the slice needs its review rounds). For `fix` and `change` the phase is already `implementing`: write the task record, then work it test-first.
+5. For a `fix` the user is also asked (when a user is present) whether to skip fresh-context review (it is logged if they say yes; if no, the slice needs its review rounds). For `fix` and `change` the phase is already `implementing`: write the task record, then work it test-first.

package/skills/event-modelling/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: event-modelling
+description: Model a capability as event-model slices (command, events, views, Given/When/Then) before building it, validate them, and turn each scenario into a failing test. Use when a capability or product has state changes, views or automations to design, when asked for an event model, or before writing tests for a command-and-event feature.
+---
+
+# Event modelling (lite)
+
+An event model says what happens (events), what causes it (commands), and what people see (views), one thin
+slice at a time. Here it is a set of small YAML or JSON files, one per slice, validated by
+`devsys_event_model_check` and turned into tests. Keep it small: model what the work needs, not the whole
+domain. If a repo has a dedicated event-model extension (a tool named `event_model_validate`), use that tool
+instead.
+
+## The three slice patterns
+
+| Pattern | Shape | Has |
+|---|---|---|
+| `state-change` | an actor issues a command and events record the result | `command`, `events`, `gwt` |
+| `state-view` | a view is built from events | `views` (each with `sources`), `gwt` optional |
+| `automation` | the system reacts to events with a command | `actor: system`, `command`, `events`, `gwt` (its `given` names the triggering events) |
+
+A slice file:
+
+```yaml
+id: slice.signin.c01
+pattern: state-change
+actor: user
+command: { name: SignIn, fields: { email: string, password: secret } }
+events:
+  - { name: SignedIn, fields: { userId: id, at: timestamp } }
+gwt:
+  - given: [{ event: UserRegistered, let: { email: "a@b.c" } }]
+    when: { command: SignIn, let: { email: "a@b.c", password: "pw" } }
+    then: [{ event: SignedIn }]
+```
+
+Views list `{ name, fields, sources: [event names] }`. Ids are unique and stable (`slice.<name>.<c|v|a><nn>`).
+
+## The seven steps
+
+1. **Brainstorm the events** in past tense (`UserRegistered`, `SignedIn`), in the order they happen.
+2. **Order them** into a story along time, and note which actor causes each.
+3. **Add the commands** that cause the events, with the fields the actor supplies.
+4. **Add the views** people read, naming the events each is built from.
+5. **Cut slices**: one file per command, view or automation, each independently buildable.
+6. **Write the scenarios**: Given (prior events), When (the one command), Then (events, an error, or a view).
+7. **Validate and fix**: run `devsys_event_model_check` and resolve every error.
+
+Put the files under `docs/event-model/` (or the directory the user names). Ask for the derived swimlane
+Markdown or a Mermaid diagram with `render`; never edit derived views by hand.
+
+## Given / When / Then
+
+- `given`: events that already happened, with the values (`let`) that matter. Empty means no history.
+- `when`: exactly one command, with its values. A `state-view` slice has none.
+- `then`: at least one expectation: an `event`, an `error` (kebab-case id), or a `view`.
+
+## Completeness
+
+The validator checks that information has an origin and a destination:
+
+- every field of a view appears in the fields of one of its source events (`missing-origin`);
+- every field a system-run command needs comes from a view or an earlier event (`missing-origin`);
+- every command produces at least one event (`missing-destination`);
+- every name that a scenario or view mentions exists in some slice (`unknown-ref`);
+- ids and names are unique (`duplicate-id`); scenarios have a `when` and a non-empty `then`
+  (`gwt-without-when`, `gwt-then-empty`); a slice's fields match its pattern (`pattern-field-mismatch`);
+- an event nothing reads is a warning (`orphan-event`): a view, a scenario or an automation should use it.
+
+## Never invent policy to satisfy the validator
+
+When a check fails because the model lacks a fact (where does this field come from? who sends this
+command?), that is a question for the user, not a gap to fill. Do not add a field, an event or a rule only so
+validation passes. Ask one question, record the answer in the model, and continue.
+
+## From scenarios to tests
+
+One failing test per scenario, with the gwt-tests reference of the active language profile
+(`profile-typescript` or `profile-rust`). No spec in the model without an equivalent in code, and no
+behaviour in code that the model does not cover. When they disagree, change the model first.
+
+## Skipping
+
+Event modelling is a planning artifact for `capability` and `product` work. Skipping it is a recorded
+departure: `devsys_record_departure` with gate `artifact.skipped:event-model` and why it does not
+fit (for example, no state changes or views to design).
+
+## Checklist
+
+- [ ] Every command, view and automation is its own slice file with a stable id
+- [ ] `devsys_event_model_check` reports 0 errors; warnings read and answered
+- [ ] No field, event or rule exists only to satisfy the validator
+- [ ] Each scenario has a failing test, written before the code

package/skills/profile-rust/SKILL.md

@@ -13,6 +13,7 @@ Read the reference you need, not all of them:
 - Errors: `references/errors.md`
 - Lints: `references/lints.md`
 - Tests and mutation testing: `references/tests.md`
+- Event-model scenarios as tests: `references/gwt-tests.md`
 
 ## Defaults
 

package/skills/profile-rust/references/gwt-tests.md

@@ -0,0 +1,14 @@
+# GWT scenarios to failing tests (Rust)
+
+An event-model slice lists Given/When/Then scenarios. Each is one test; no spec in the model without an
+equivalent in code.
+
+1. Name the test after the slice and scenario: `fn signin_after_registration_emits_signed_in()`, in a module named for the slice.
+2. **Given** the listed events become the history slice passed to the decide function (`&[Event]`, with the `let` values filled in).
+3. **When** the command is the input: call the pure `decide(&history, command)`, not a handler with I/O.
+4. **Then** events assert the returned `Vec<Event>`, `error` asserts the returned error variant (`matches!`), and `view` asserts the projection folded from the events.
+5. Run it and watch it fail before writing `decide` or the projection (RED), then make it pass.
+6. A scenario with an empty `given` is a command against no history; keep it as its own test.
+
+One failing `#[test]` per scenario. Do not loop over scenarios in one test, which hides which one failed.
+When code and model disagree, change the model first (the model is the spec), then the test.

package/skills/profile-typescript/SKILL.md

@@ -13,6 +13,7 @@ Read the reference you need:
 - Result pattern: `references/errors.md`
 - tsconfig and biome: `references/lints.md`
 - Test layout: `references/tests.md`
+- Event-model scenarios as tests: `references/gwt-tests.md`
 
 ## Defaults
 

package/skills/profile-typescript/references/gwt-tests.md

@@ -0,0 +1,15 @@
+# GWT scenarios to failing tests (TypeScript)
+
+An event-model slice lists Given/When/Then scenarios. Each is one test; no spec in the model without an
+equivalent in code.
+
+1. Name the test after the slice and scenario: `test("slice.signin.c01: SignIn after UserRegistered emits SignedIn", ...)`.
+2. **Given** the listed events become the history the function receives (an array of event objects, with the `let` values filled in).
+3. **When** the command is the input: call the pure decide function (`decide(history, command)`), not a handler with I/O.
+4. **Then** events assert the returned events, `error` asserts the returned error `kind`, and `view` asserts the projection built from the events.
+5. Run it and watch it fail before writing the decide or project function (RED), then make it pass.
+6. A scenario with an empty `given` is a command against no history; keep it as its own test.
+
+One failing test per scenario, one `test(...)` each, in `test/<area>/<slice>.test.ts`. Do not merge scenarios
+into a table that hides which one failed. When code and model disagree, change the model first (the model is
+the spec), then the test.

package/skills/work-intake-and-slicing/SKILL.md

@@ -16,7 +16,7 @@ Ask these in order and stop at the first yes:
 3. Does it change existing behaviour in one area? That is a `change`.
 4. Otherwise it is a `fix`.
 
-`/devsys-start` proposes a size with Jev and asks you to confirm. If you disagree, change it; the size is a judgement, not a rule.
+`/devsys-start` sizes the work with Jev and proceeds when Jev is at least 50% confident, saying so; below that it asks you to pick. If the size is already decided (a goal's planning, a plan's increment), pass it as `size` and nobody is asked to size it (a `fix` still asks whether to waive review). If you disagree with a size, change it; it is a judgement, not a rule.
 
 ## Artifacts follow size
 

package/src/context/status.ts

@@ -14,9 +14,8 @@ const ciLabel = (state: DevsysState): string | undefined => {
 };
 
 const activeReview = (state: DevsysState): string | undefined => {
-  // Without an active slice (before /devsys-start exists) show the most recent review instead of nothing.
-  const review =
-    state.activeSlice === undefined ? state.reviews?.at(-1) : reviewOf(state, state.activeSlice);
+  // No active slice, no review: a closed slice's last count would only mislead the next one.
+  const review = state.activeSlice === undefined ? undefined : reviewOf(state, state.activeSlice);
   return review === undefined ? undefined : reviewLabel(review);
 };
 

package/src/core/review-flow.ts

@@ -19,8 +19,9 @@ export const upsertReview = (state: DevsysState, review: ReviewState): DevsysSta
   return { ...state, reviews: [...others, review] };
 };
 
+/** Capped at the requirement: extra clean rounds (after a late change) are not progress past "done". */
 export const reviewLabel = (review: ReviewState): string =>
-  `review: ${cleanStreak(review)}/${review.required} clean`;
+  `review: ${Math.min(cleanStreak(review), review.required)}/${review.required} clean`;
 
 /**
  * Why a commit on this slice lacks a satisfied review, or `undefined` when the review is complete

package/src/planning/event-model-provider.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../state/config.ts";
+import { createEventModelCheckTool } from "./event-model-tool.ts";
+
+/** The name of the builtin tool; a provider extension offers `event_model_validate` instead. */
+export const EVENT_MODEL_TOOL = "devsys_event_model_check";
+const PROVIDER_TOOL = "event_model_validate";
+
+/**
+ * The builtin event-model-lite validator is for repos that have nothing better: it steps aside when the config
+ * names another provider, or when an extension registers `event_model_validate` (see
+ * docs/event-model-extension-contract.md).
+ */
+export function usesBuiltinEventModel(provider: string, toolNames: readonly string[]): boolean {
+  return provider === "builtin" && !toolNames.includes(PROVIDER_TOOL);
+}
+
+/**
+ * Registers the builtin tool at session start, when every extension's tools are known and the repo's config
+ * can be read: neither is available while the extension loads.
+ */
+export function registerEventModelProvider(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx) => {
+    const config = await loadConfig(ctx.cwd);
+    const provider = config.ok ? config.value.eventModel.provider : "builtin";
+    const names = pi.getAllTools().map((tool) => tool.name);
+    if (usesBuiltinEventModel(provider, names)) {
+      pi.registerTool(createEventModelCheckTool());
+    } else if (!names.includes(PROVIDER_TOOL)) {
+      ctx.ui.notify(
+        `event_model.provider is "${provider}" but no ${PROVIDER_TOOL} tool is loaded: install that extension, or set provider = "builtin" to use ${EVENT_MODEL_TOOL}.`,
+        "warning",
+      );
+    }
+  });
+}

package/src/planning/event-model-render.ts

@@ -0,0 +1,81 @@
+import type { Slice } from "./slice-schema.ts";
+
+/** Derived views of an event model: a swimlane table with scenarios, and a diagram. Never edited by hand. */
+
+const values = (let_: Record<string, unknown> | undefined): string => {
+  const entries = Object.entries(let_ ?? {});
+  return entries.length === 0
+    ? ""
+    : ` (${entries.map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ")})`;
+};
+
+type Scenario = Slice["gwt"][number];
+
+const scenarioLines = (g: Scenario): string[] => [
+  ...g.given.map((x) => `- Given ${x.event}${values(x.let)}`),
+  ...(g.when ? [`- When ${g.when.command}${values(g.when.let)}`] : []),
+  ...g.then.map((t) => {
+    if ("error" in t) return `- Then error ${t.error}`;
+    if ("view" in t) return `- Then view ${t.view}${values(t.let)}`;
+    return `- Then ${t.event}${values(t.let)}`;
+  }),
+];
+
+const cell = (text: string): string => (text === "" ? "" : ` ${text} `);
+
+const row = (s: Slice): string =>
+  `|${[
+    s.id,
+    s.pattern,
+    s.actor,
+    s.command?.name ?? "",
+    s.events.map((e) => e.name).join(", "),
+    s.views.map((v) => v.name).join(", "),
+  ]
+    .map(cell)
+    .join("|")}|`
+    .replace(/\|\|/g, "| |")
+    .replace(/\| \|\|/g, "| | |");
+
+/** The swimlane table (one row per slice), then each slice's scenarios as Given/When/Then lists. */
+export function renderModelMarkdown(slices: readonly Slice[]): string {
+  const table = [
+    "| Slice | Pattern | Actor | Command | Events | Views |",
+    "|---|---|---|---|---|---|",
+    ...slices.map(row),
+  ];
+  const sections = slices.flatMap((s) => [
+    `## ${s.id}`,
+    "",
+    ...s.gwt.flatMap((g, i) => [`Scenario ${i + 1}`, "", ...scenarioLines(g), ""]),
+  ]);
+  return `${[...table, "", ...sections].join("\n").trimEnd()}\n`;
+}
+
+/** Mermaid node ids hold letters, digits and underscores; the label carries the real name. */
+const label = (name: string): string => `"${name.replace(/"/g, "#quot;")}"`;
+
+/**
+ * Commands to the events they produce, and events to the views that read them. Ids are numbered per name
+ * (not derived from it), so names that differ only in punctuation or script are never merged into one node.
+ */
+export function renderMermaid(slices: readonly Slice[]): string {
+  const ids = new Map<string, string>();
+  const node = (prefix: string, name: string): string => {
+    const key = `${prefix}:${name}`;
+    const id = ids.get(key) ?? `${prefix}${ids.size + 1}`;
+    ids.set(key, id);
+    return `${id}[${label(name)}]`;
+  };
+  const lines = ["flowchart LR"];
+  for (const s of slices) {
+    if (s.command) {
+      for (const e of s.events)
+        lines.push(`  ${node("c", s.command.name)} --> ${node("e", e.name)}`);
+    }
+    for (const v of s.views) {
+      for (const source of v.sources) lines.push(`  ${node("e", source)} --> ${node("v", v.name)}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/planning/event-model-tool.ts

@@ -0,0 +1,92 @@
+import { readdir, readFile } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve } from "node:path";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { renderMermaid, renderModelMarkdown } from "./event-model-render.ts";
+import { parseSlice, type Slice, type SliceFormat, validateModel } from "./slice-schema.ts";
+
+const Parameters = Type.Object({
+  dir: Type.String({
+    description: "Directory of slice files (.yaml, .yml, .json), inside the repository.",
+  }),
+  render: Type.Optional(
+    Type.Union([Type.Literal("markdown"), Type.Literal("mermaid")], {
+      description: "Also return the derived swimlane Markdown or Mermaid diagram.",
+    }),
+  ),
+});
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+const FORMATS: Record<string, SliceFormat> = { ".yaml": "yaml", ".yml": "yaml", ".json": "json" };
+
+const insideRepo = (cwd: string, target: string): boolean => {
+  const rel = relative(cwd, target);
+  return !(rel.startsWith("..") || isAbsolute(rel));
+};
+
+type Loaded = { slices: Slice[]; problems: string[]; files: number };
+
+async function loadSlices(dir: string, names: readonly string[]): Promise<Loaded> {
+  const slices: Slice[] = [];
+  const problems: string[] = [];
+  for (const name of names) {
+    const format = FORMATS[extname(name)];
+    if (format === undefined) continue;
+    const parsed = parseSlice(await readFile(join(dir, name), "utf8"), format);
+    if (parsed.ok) slices.push(parsed.value);
+    else problems.push(`${name}: ${parsed.error.message}`);
+  }
+  return { slices, problems, files: slices.length + problems.length };
+}
+
+const derived = (
+  slices: readonly Slice[],
+  render: Static<typeof Parameters>["render"],
+): string[] => {
+  if (render === "markdown") return [renderModelMarkdown(slices)];
+  if (render === "mermaid") return [renderMermaid(slices)];
+  return [];
+};
+
+/**
+ * `devsys_event_model_check`: validates a directory of event-model-lite slices (schema v1) and can derive
+ * the Markdown or Mermaid view. A dedicated event-model extension replaces it (see
+ * docs/event-model-extension-contract.md).
+ */
+export function createEventModelCheckTool(): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_event_model_check",
+    label: "Check event model",
+    description:
+      "Validate a directory of event-model slice files (schema v1: pattern, command, events, views, Given/When/Then) for unknown references, missing origins and destinations, empty scenarios and orphan events; optionally render the swimlane Markdown or a Mermaid diagram.",
+    promptSnippet: "Validate event-model slices and render the derived views",
+    parameters: Parameters,
+    async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const dir = resolve(ctx.cwd, params.dir);
+      if (!insideRepo(ctx.cwd, dir)) return reply(`${params.dir} is outside the repository`, true);
+      let names: string[];
+      try {
+        names = (await readdir(dir)).sort();
+      } catch {
+        return reply(`cannot read ${params.dir}: no such directory`, true);
+      }
+      const { slices, problems, files } = await loadSlices(dir, names);
+      if (files === 0) return reply(`no slice files (.yaml, .yml, .json) in ${params.dir}`, true);
+      const issues = validateModel(slices);
+      const warnings = issues.filter((i) => i.severity === "warning").length;
+      const errors = issues.length - warnings + problems.length;
+      const lines = [
+        `${slices.length} slices, ${errors} errors, ${warnings} warnings`,
+        ...problems.map((p) => `- parse-error (error) ${p}`),
+        ...issues.map((i) => `- ${i.code} (${i.severity}) ${i.slice}: ${i.message}`),
+      ];
+      const report = lines.join("\n");
+      return reply([report, ...derived(slices, params.render)].join("\n\n"), errors > 0);
+    },
+  };
+}

package/src/planning/intake-tool.ts

@@ -13,13 +13,27 @@ import type { Jev } from "../jev/client.ts";
 import { judgeSizing } from "../jev/questions/sizing.ts";
 import { appendDecision } from "../state/decision-log.ts";
 import type { SessionState } from "../state/session-state.ts";
-import { phaseFor, proposeArtifacts, renderProposal, sliceSlug, uniqueSlice } from "./intake.ts";
+import {
+  decideSize,
+  phaseFor,
+  proposeArtifacts,
+  renderProposal,
+  type SizeDecision,
+  sliceSlug,
+  uniqueSlice,
+} from "./intake.ts";
 
 const Parameters = Type.Object({
   request: Type.String({ description: "What the user asked for, in their words." }),
   repoSummary: Type.Optional(
     Type.String({ description: "One or two sentences on the repository, if known." }),
   ),
+  size: Type.Optional(
+    Type.String({
+      description:
+        "fix, change, capability or product, when the size is already decided (for example during a goal's up-front planning). Skips Jev's sizing question and the user's.",
+    }),
+  ),
 });
 
 const SIZES: readonly Sizing[] = ["fix", "change", "capability", "product"];
@@ -62,6 +76,9 @@ async function declinedToReplace(
   const { activeSlice, phase } = before;
   const inFlight = phase === "implementing" || phase === "reviewing" || phase === "delivering";
   if (activeSlice === undefined || !inFlight) return undefined;
+  if (!ctx.hasUI) {
+    return `Slice "${activeSlice}" is still ${phase}; replacing it needs the user's yes, and there is no UI to ask. Intake cancelled; slice "${activeSlice}" is unchanged.`;
+  }
   const go = await ctx.ui.confirm(
     "Slice already in flight",
     `Slice "${activeSlice}" is still ${phase}. Its uncommitted or unpushed changes would ship under the new slice's rules. Start new work anyway?`,
@@ -69,6 +86,28 @@ async function declinedToReplace(
   return go ? undefined : `Intake cancelled; slice "${activeSlice}" is unchanged.`;
 }
 
+type Chosen = { readonly sizing: Sizing } | { readonly stop: string; readonly isError: boolean };
+
+/** A decided size passes through; an undecided one asks the user (headless: stops with the proposal). */
+async function chooseSize(
+  ctx: ExtensionContext,
+  decision: SizeDecision,
+  proposalFor: (size: Sizing) => ReturnType<typeof proposeArtifacts>,
+): Promise<Chosen> {
+  if (decision.kind === "decided") return { sizing: decision.size };
+  const { basis, proposed } = decision;
+  const proposal = renderProposal({ sizing: proposed, basis, proposal: proposalFor(proposed) });
+  if (!ctx.hasUI) {
+    return { stop: `${proposal}\nHeadless: proposal only, not applied.`, isError: false };
+  }
+  const picked = await ctx.ui.select(`Size this work (${basis})`, sizeChoices(proposed));
+  if (picked === undefined) {
+    return { stop: `${proposal}\nIntake cancelled; nothing changed.`, isError: false };
+  }
+  const parsed = parseSizing(picked);
+  return isParseError(parsed) ? { stop: parsed.message, isError: true } : { sizing: parsed };
+}
+
 const waiverNote = (sizing: Sizing, departed: string | undefined): string => {
   if (departed !== undefined)
     return `\nRecorded in ${departed}: you waived fresh-context review for this fix.`;
@@ -108,7 +147,7 @@ async function fixWithoutReview(
   return path;
 }
 
-/** `devsys_intake`: Jev proposes a size and artifact set; the user confirms; state moves to the first phase. */
+/** `devsys_intake`: Jev (or the caller) sizes the work; only a doubtful Jev asks the user; state moves to the first phase. */
 export function createIntakeTool(deps: {
   pi: ExtensionAPI;
   state: SessionState;
@@ -119,36 +158,39 @@ export function createIntakeTool(deps: {
     label: "Start work",
     description:
       "Size a request (fix, change, capability, product) and list the planning artifacts that size needs. " +
-      "The user confirms the size; then phase, sizing and the active slice are set. Call at the start of any non-trivial work.",
+      "Jev sizes the work and the user is asked only when Jev is under 50% confident; pass `size` when it is already decided. Then phase, sizing and the active slice are set. Call at the start of any non-trivial work.",
     promptSnippet: "Size new work and propose the planning artifacts it needs",
     parameters: Parameters,
     exposure: "model-only",
     async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
       const request = params.request.trim();
       if (request === "") return reply("request must not be empty", true);
-      const judged = await judgeSizing(deps.jev(ctx), {
-        request,
-        repoSummary: params.repoSummary ?? "",
-      });
-      const proposedSize: Sizing = judged.ok ? judged.value.sizing : "change";
-      const basis = judged.ok
-        ? `Jev judged ${judged.value.sizing} (confidence ${judged.value.confidence.toFixed(2)}).`
-        : `Jev unavailable (${judged.error.kind}); defaulted to change.`;
-      const artifactNeed = judged.ok ? judged.value.artifactNeed : {};
+      const given = params.size === undefined ? undefined : parseSizing(params.size.trim());
+      if (given !== undefined && isParseError(given)) return reply(given.message, true);
+      const judged =
+        given === undefined
+          ? await judgeSizing(deps.jev(ctx), { request, repoSummary: params.repoSummary ?? "" })
+          : undefined;
+      const decision = decideSize(
+        given,
+        judged?.ok ? judged.value : undefined,
+        judged?.ok === false ? judged.error.kind : "not asked",
+      );
+      const artifactNeed = judged?.ok ? judged.value.artifactNeed : {};
       const proposalFor = (size: Sizing) => proposeArtifacts(size, artifactNeed);
-      const proposal = renderProposal({
-        sizing: proposedSize,
-        basis,
-        proposal: proposalFor(proposedSize),
-      });
-      if (!ctx.hasUI) return reply(`${proposal}\nHeadless: proposal only, not applied.`);
-      const picked = await ctx.ui.select(`Size this work (${basis})`, sizeChoices(proposedSize));
-      if (picked === undefined) return reply(`${proposal}\nIntake cancelled; nothing changed.`);
-      const sizing = parseSizing(picked);
-      if (isParseError(sizing)) return reply(sizing.message, true);
+      const chosen = await chooseSize(ctx, decision, proposalFor);
+      if ("stop" in chosen) return reply(chosen.stop, chosen.isError);
+      const { sizing } = chosen;
       const before = deps.state.get();
       const keep = await declinedToReplace(ctx, before);
-      if (keep !== undefined) return reply(`${proposal}\n${keep}`);
+      if (keep !== undefined) {
+        const proposal = renderProposal({
+          sizing,
+          basis: decision.basis,
+          proposal: proposalFor(sizing),
+        });
+        return reply(`${proposal}\n${keep}`);
+      }
       const slice = uniqueSlice(sliceSlug(request), slicesInUse(before)) as SliceRef;
       deps.state.update((s) => ({
         ...s,
@@ -156,9 +198,14 @@ export function createIntakeTool(deps: {
         sizing,
         activeSlice: slice,
       }));
-      const waived = sizing === "fix" ? await askToWaiveReview(ctx, request, slice) : false;
+      const waived =
+        sizing === "fix" && ctx.hasUI ? await askToWaiveReview(ctx, request, slice) : false;
       const departed = waived ? await fixWithoutReview(deps, ctx, slice) : undefined;
-      const final = renderProposal({ sizing, basis, proposal: proposalFor(sizing) });
+      const final = renderProposal({
+        sizing,
+        basis: decision.basis,
+        proposal: proposalFor(sizing),
+      });
       const note = waiverNote(sizing, departed);
       return reply(`${final}\nPhase: ${phaseFor(sizing)}. Active slice: ${slice}.${note}`);
     },

package/src/planning/intake.ts

@@ -71,3 +71,36 @@ export const renderProposal = (input: {
   );
   return lines.join("\n");
 };
+
+/** Jev confidence below this asks the human; at or above it intake proceeds with Jev's size. */
+const ASK_BELOW = 0.5;
+
+export type SizeDecision =
+  | { readonly kind: "decided"; readonly size: Sizing; readonly basis: string }
+  | { readonly kind: "ask"; readonly proposed: Sizing; readonly basis: string };
+
+/**
+ * Pure: who sizes the work. A size given up front (the caller, e.g. a goal's planning, already
+ * decided) wins; otherwise Jev decides when it is confident enough; only a doubtful or missing
+ * judgement asks the human, with Jev's size (or `change`) as the proposal.
+ */
+export function decideSize(
+  given: Sizing | undefined,
+  judged: { readonly sizing: Sizing; readonly confidence: number } | undefined,
+  unavailable: string,
+): SizeDecision {
+  if (given !== undefined) {
+    return { kind: "decided", size: given, basis: `Size given up front: ${given}.` };
+  }
+  if (judged === undefined) {
+    return {
+      kind: "ask",
+      proposed: "change",
+      basis: `Jev unavailable (${unavailable}); defaulted to change.`,
+    };
+  }
+  const said = `Jev judged ${judged.sizing} (confidence ${judged.confidence.toFixed(2)})`;
+  return judged.confidence >= ASK_BELOW
+    ? { kind: "decided", size: judged.sizing, basis: `${said}; proceeding without asking.` }
+    : { kind: "ask", proposed: judged.sizing, basis: `${said}, too unsure to proceed alone.` };
+}

package/src/planning/slice-schema.ts

@@ -0,0 +1,312 @@
+import { type Static, Type } from "typebox";
+import Value from "typebox/value";
+import { parse as parseYaml } from "yaml";
+import { err, ok, type Result } from "../core/result.ts";
+import { type ParseError, parseError } from "../core/types.ts";
+
+/**
+ * Event-model lite, slice schema v1 (plan Appendix D). One slice is one command-to-events step, one
+ * view over events, or one automation; Given/When/Then scenarios say what it must do. The schema is
+ * deliberately small: a validator that needs more than this to pass is asking for invented policy.
+ */
+
+const Fields = Type.Record(Type.String(), Type.String());
+const Values = Type.Record(Type.String(), Type.Unknown());
+const Name = Type.String({ minLength: 1 });
+
+const SlicePattern = Type.Union([
+  Type.Literal("state-change"),
+  Type.Literal("state-view"),
+  Type.Literal("automation"),
+]);
+
+const EventDecl = Type.Object({ name: Name, fields: Fields }, { additionalProperties: false });
+const ViewDecl = Type.Object(
+  { name: Name, fields: Fields, sources: Type.Array(Name) },
+  { additionalProperties: false },
+);
+const Given = Type.Object(
+  { event: Name, let: Type.Optional(Values) },
+  { additionalProperties: false },
+);
+const When = Type.Object(
+  { command: Name, let: Type.Optional(Values) },
+  { additionalProperties: false },
+);
+const Then = Type.Union([
+  Type.Object({ event: Name, let: Type.Optional(Values) }, { additionalProperties: false }),
+  Type.Object({ error: Name }, { additionalProperties: false }),
+  Type.Object({ view: Name, let: Type.Optional(Values) }, { additionalProperties: false }),
+]);
+const Scenario = Type.Object(
+  // biome-ignore lint/suspicious/noThenProperty: "then" is the Given/When/Then key the slice schema (plan Appendix D) defines; these objects are never awaited.
+  { given: Type.Array(Given), when: Type.Optional(When), then: Type.Array(Then) },
+  { additionalProperties: false },
+);
+
+const SliceSchema = Type.Object(
+  {
+    id: Name,
+    pattern: SlicePattern,
+    actor: Name,
+    command: Type.Optional(
+      Type.Object({ name: Name, fields: Fields }, { additionalProperties: false }),
+    ),
+    events: Type.Optional(Type.Array(EventDecl)),
+    views: Type.Optional(Type.Array(ViewDecl)),
+    gwt: Type.Optional(Type.Array(Scenario)),
+  },
+  { additionalProperties: false },
+);
+
+type Raw = Static<typeof SliceSchema>;
+
+/** A parsed slice: the optional lists are present, empty when the file left them out. */
+export type Slice = Omit<Raw, "events" | "views" | "gwt"> & {
+  events: Static<typeof EventDecl>[];
+  views: Static<typeof ViewDecl>[];
+  gwt: Static<typeof Scenario>[];
+};
+
+export type SliceFormat = "json" | "yaml";
+
+/** One slice from JSON or YAML text; a schema violation names the path and the rule it broke. */
+export function parseSlice(text: string, format: SliceFormat): Result<Slice, ParseError> {
+  let data: unknown;
+  try {
+    data = format === "json" ? JSON.parse(text) : parseYaml(text);
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    // The yaml library appends a code frame; the first line is the reason, and a report is one line per issue.
+    return err(parseError(`not valid ${format}: ${reason.split("\n")[0]}`));
+  }
+  const first = Value.Errors(SliceSchema, data)[0];
+  if (first !== undefined) {
+    return err(
+      parseError(`${first.instancePath === "" ? "/" : first.instancePath}: ${first.message}`),
+    );
+  }
+  const raw = data as Raw;
+  return ok({ ...raw, events: raw.events ?? [], views: raw.views ?? [], gwt: raw.gwt ?? [] });
+}
+
+type ValidationCode =
+  | "duplicate-id"
+  | "unknown-ref"
+  | "missing-origin"
+  | "missing-destination"
+  | "gwt-without-when"
+  | "gwt-then-empty"
+  | "orphan-event"
+  | "pattern-field-mismatch";
+
+export type ValidationIssue = {
+  code: ValidationCode;
+  /** An orphan event may be a deliberate end of the line; everything else is a hole in the model. */
+  severity: "error" | "warning";
+  slice: string;
+  message: string;
+};
+
+const issue = (
+  code: ValidationCode,
+  slice: string,
+  message: string,
+  severity: ValidationIssue["severity"] = "error",
+): ValidationIssue => ({ code, severity, slice, message });
+
+function duplicates(slices: readonly Slice[]): ValidationIssue[] {
+  const seen = {
+    id: new Set<string>(),
+    command: new Set<string>(),
+    event: new Set<string>(),
+    view: new Set<string>(),
+  };
+  const out: ValidationIssue[] = [];
+  const claim = (kind: keyof typeof seen, name: string, slice: string): void => {
+    if (seen[kind].has(name)) {
+      out.push(issue("duplicate-id", slice, `the ${kind} "${name}" is declared more than once`));
+    }
+    seen[kind].add(name);
+  };
+  for (const s of slices) {
+    claim("id", s.id, s.id);
+    if (s.command) claim("command", s.command.name, s.id);
+    for (const e of s.events) claim("event", e.name, s.id);
+    for (const v of s.views) claim("view", v.name, s.id);
+  }
+  return out;
+}
+
+type Model = {
+  events: Map<string, Record<string, string>>;
+  views: Map<string, Record<string, string>>;
+  usedEvents: Set<string>;
+};
+
+const indexModel = (slices: readonly Slice[]): Model => {
+  const events = new Map<string, Record<string, string>>();
+  const views = new Map<string, Record<string, string>>();
+  const usedEvents = new Set<string>();
+  for (const s of slices) {
+    for (const e of s.events) events.set(e.name, e.fields);
+    for (const v of s.views) {
+      views.set(v.name, v.fields);
+      for (const source of v.sources) usedEvents.add(source);
+    }
+    for (const g of s.gwt) for (const given of g.given) usedEvents.add(given.event);
+  }
+  return { events, views, usedEvents };
+};
+
+function shape(s: Slice): ValidationIssue[] {
+  const problems: string[] = [];
+  if (s.pattern === "state-view") {
+    if (s.views.length === 0) problems.push("a state-view needs at least one view");
+    if (s.command) problems.push("a state-view has no command");
+    if (s.events.length > 0) problems.push("a state-view declares no events; its sources do");
+  } else {
+    if (!s.command) problems.push(`a ${s.pattern} needs a command`);
+    if (s.views.length > 0) problems.push(`a ${s.pattern} declares no views`);
+    if (s.pattern === "automation" && s.actor !== "system") {
+      problems.push('an automation is run by the actor "system"');
+    }
+  }
+  return problems.map((p) => issue("pattern-field-mismatch", s.id, p));
+}
+
+function commandOrigins(s: Slice, model: Model): ValidationIssue[] {
+  if (!s.command || s.actor !== "system") return [];
+  const known = new Set<string>();
+  for (const fields of model.views.values()) for (const f of Object.keys(fields)) known.add(f);
+  for (const g of s.gwt) {
+    for (const given of g.given) {
+      for (const f of Object.keys(model.events.get(given.event) ?? {})) known.add(f);
+    }
+  }
+  return Object.keys(s.command.fields)
+    .filter((f) => !known.has(f))
+    .map((f) =>
+      issue("missing-origin", s.id, `command field "${f}" comes from no view or triggering event`),
+    );
+}
+
+function viewIssues(s: Slice, model: Model): ValidationIssue[] {
+  const out: ValidationIssue[] = [];
+  for (const view of s.views) {
+    const carried = new Set<string>();
+    for (const source of view.sources) {
+      const fields = model.events.get(source);
+      if (fields === undefined) {
+        out.push(
+          issue(
+            "unknown-ref",
+            s.id,
+            `view "${view.name}" reads event "${source}", which no slice declares`,
+          ),
+        );
+      } else {
+        for (const f of Object.keys(fields)) carried.add(f);
+      }
+    }
+    for (const f of Object.keys(view.fields)) {
+      if (!carried.has(f)) {
+        out.push(
+          issue(
+            "missing-origin",
+            s.id,
+            `view field "${f}" of "${view.name}" is carried by none of its source events`,
+          ),
+        );
+      }
+    }
+  }
+  return out;
+}
+
+function whenIssues(s: Slice, g: Slice["gwt"][number], where: string): ValidationIssue[] {
+  if (s.pattern === "state-view") {
+    return g.when === undefined
+      ? []
+      : [issue("pattern-field-mismatch", s.id, `${where} of a state-view has no when`)];
+  }
+  if (g.when === undefined) return [issue("gwt-without-when", s.id, `${where} has no when`)];
+  if (g.when.command === s.command?.name) return [];
+  const own = s.command?.name ?? "command";
+  return [
+    issue(
+      "unknown-ref",
+      s.id,
+      `${where} runs command "${g.when.command}", not this slice's ${own}`,
+    ),
+  ];
+}
+
+function thenIssues(
+  s: Slice,
+  g: Slice["gwt"][number],
+  where: string,
+  model: Model,
+): ValidationIssue[] {
+  if (g.then.length === 0) return [issue("gwt-then-empty", s.id, `${where} expects nothing`)];
+  return g.then.flatMap((t) => {
+    if ("event" in t && !model.events.has(t.event)) {
+      return [
+        issue("unknown-ref", s.id, `${where} expects event "${t.event}", which no slice declares`),
+      ];
+    }
+    if ("view" in t && !model.views.has(t.view)) {
+      return [
+        issue("unknown-ref", s.id, `${where} expects view "${t.view}", which no slice declares`),
+      ];
+    }
+    return [];
+  });
+}
+
+function scenarioIssues(s: Slice, model: Model): ValidationIssue[] {
+  return s.gwt.flatMap((g, i) => {
+    const where = `scenario ${i + 1}`;
+    const given = g.given
+      .filter((x) => !model.events.has(x.event))
+      .map((x) =>
+        issue("unknown-ref", s.id, `${where} gives event "${x.event}", which no slice declares`),
+      );
+    return [...whenIssues(s, g, where), ...given, ...thenIssues(s, g, where, model)];
+  });
+}
+
+function ownIssues(s: Slice, model: Model): ValidationIssue[] {
+  const missingDestination =
+    s.pattern !== "state-view" && s.command && s.events.length === 0
+      ? [issue("missing-destination", s.id, `command "${s.command.name}" produces no events`)]
+      : [];
+  const orphans = s.events
+    .filter((e) => !model.usedEvents.has(e.name))
+    .map((e) =>
+      issue(
+        "orphan-event",
+        s.id,
+        `event "${e.name}" feeds no view and starts no scenario`,
+        "warning",
+      ),
+    );
+  return [
+    ...shape(s),
+    ...missingDestination,
+    ...commandOrigins(s, model),
+    ...viewIssues(s, model),
+    ...scenarioIssues(s, model),
+    ...orphans,
+  ];
+}
+
+/**
+ * Checks a whole model: names are unique, every reference resolves, and information is complete (every
+ * view field has an event origin, every system command field a source). Judges nothing the model does
+ * not say: a hole is reported, never filled.
+ */
+export function validateModel(slices: readonly Slice[]): ValidationIssue[] {
+  const model = indexModel(slices);
+  return [...duplicates(slices), ...slices.flatMap((s) => ownIssues(s, model))];
+}