trekoon 0.4.5 → 0.4.7

package/docs/commands.md

@@ -10,7 +10,7 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `trekoon help [command]`
 - `trekoon quickstart`
 - `trekoon epic <create|expand|list|show|search|replace|update|delete|progress>`
-- `trekoon session [--epic <epic-id>]`
+- `trekoon session [--epic <epic-id>] [--item <id>]`
 - `trekoon suggest [--epic <epic-id>]`
 - `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete|claim>`
 - `trekoon subtask <create|create-many|list|search|replace|update|delete|claim>`
@@ -94,11 +94,11 @@ Board mutations from any source — board UI, CLI in another shell, or another
 worktree — propagate to every connected client through the SSE stream. The CLI
 side is driven by a WAL-watcher that diffs the snapshot when
 `.trekoon/trekoon.db-wal` changes; in-process mutations publish deltas
-directly. PATCH endpoints accept `If-Match: <version>` for optimistic
-concurrency; RFC 7232 strong or `W/`-prefixed weak ETag forms are accepted,
-but the `*` wildcard is not. A stale value returns `409` with
-`currentVersion` and `providedVersion`. Missing `If-Match` is allowed for
-back-compat.
+directly. PATCH endpoints require `If-Match: <version>` for optimistic concurrency; RFC
+7232 strong or `W/`-prefixed weak ETag forms are accepted, but the `*`
+wildcard is not. A stale value returns `409` with `currentVersion` and
+`providedVersion`. A missing `If-Match` header returns `428 Precondition
+Required` with error code `precondition_required`.
 
 Repos that already have an ignored `.trekoon/board` directory keep those files
 on disk, but current Trekoon versions no longer read, create, refresh, or
@@ -179,6 +179,25 @@ Rules:
 - Subtask cascade is accepted for consistency but just updates one subtask
 - Success response includes `data.cascade` with changed/unchanged IDs and counts
 
+## Epic create and expand
+
+### Temp-key rules
+
+Temp keys in `--task` and `--subtask` share one flat namespace per `epic create` / `epic expand` invocation — reusing a key across any two records in the same call fails the batch. Prefix subtask keys with the parent task key to keep them unique (e.g. `task-a-sub-1` under `task-a`).
+
+`task create-many` and `subtask create-many` use their own scoped namespaces, independent of each other and of `epic create`.
+
+Escape any literal `|` inside field values as `\|`. A single bare `|` in a spec without an explicit `|<status>` field silently pushes the trailing text into the status slot — creation succeeds and the record only breaks on the next status update. Multi-pipe constructs like `||` fail loudly on the field-count check. See the planning skill for the full pipe-escape rules.
+
+```bash
+trekoon epic create \
+  --title "Launch" \
+  --task "task-a|First task|Description|todo" \
+  --task "task-b|Second task|Description|todo" \
+  --subtask "@task-a|task-a-sub-1|First subtask|Description|todo" \
+  --subtask "@task-b|task-b-sub-1|Second subtask|Description|todo"
+```
+
 ## Status machine
 
 Statuses: `todo`, `in_progress`, `done`, `blocked`. The hyphenated `in-progress`
@@ -288,6 +307,19 @@ trekoon session --epic <epic-id>
 
 Scopes session readiness to a specific epic instead of the full tracker.
 
+## Session item resolve
+
+```bash
+trekoon --toon session --item <id>
+```
+
+Resolves any epic/task/subtask id in one call. Returns
+`item: { id, kind, parentEpicId, entity, readiness, suggestedNext }` where
+`kind` is one of `epic|task|subtask`, `entity` is the same shape as
+`epic show --all` / `task show --all` / `subtask show`, and `readiness` is
+scoped to `parentEpicId`. Replaces the legacy
+`epic show || task show || subtask show` fallback cascade.
+
 ## Suggest
 
 ```bash

package/docs/machine-contracts.md

@@ -648,6 +648,7 @@ any `ok: false` response will be one of the following strings.
 | `outside_repo_target` | Skill install target path is outside the repository root. |
 | `permission_denied` | File-system permission denied for the requested path. |
 | `precondition_failed` | `If-Match` precondition header did not match the entity's current version. Error details include `currentVersion` and `providedVersion`. |
+| `precondition_required` | `If-Match` header is required on a PATCH route but was omitted. |
 | `row_not_found` | Sync resolve target row no longer exists in the database. |
 | `status_transition_invalid` | Requested status transition is not permitted by the status machine. |
 | `stream_unavailable` | SSE snapshot stream is not available (board not initialised or shutting down). |

package/docs/quickstart.md

@@ -93,11 +93,15 @@ trekoon --toon epic create \
   --description "Ship one-shot planning workflows" \
   --task "task-a|First task|First description|todo" \
   --task "task-b|Second task|Second description|todo" \
-  --subtask "@task-a|sub-a|First subtask|Subtask description|todo" \
+  --subtask "@task-a|sub-a-first|First subtask|Subtask description|todo" \
   --dep "@task-b|@task-a" \
-  --dep "@sub-a|@task-a"
+  --dep "@sub-a-first|@task-a"
 ```
 
+All temp keys (task and subtask) must be unique across the whole command — they share one flat namespace. Prefix subtask keys with the parent task key to stay unique.
+
+Escape any literal `|` inside field values as `\|`. A bare `|` on a spec without an explicit `|<status>` field silently pushes trailing text into the status slot (e.g. `Verify: bun test foo | tail` lets `tail` become the status, and creation still succeeds). Specs that already pass `|<status>` fail loudly on the same input. See the planning skill for full rules.
+
 This is better than sequential creates because later records can reference
 earlier ones with `@temp-key`, and you get one atomic operation with mappings
 and counts in the response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",

package/src/board/assets/state/actions.js

@@ -377,7 +377,14 @@ export function createBoardActions(options) {
         description: String(formData.get("description") || "").trim(),
         status: normalizeStatus(String(formData.get("status") || "todo")),
       };
-      api.patchTask(taskId, updates, (snapshot) => updateTaskInSnapshot(snapshot, taskId, updates, normalizeSnapshot));
+      // No eager version capture: api.patchTask resolves the If-Match version
+      // lazily at queue fire time so back-to-back edits on the same task see
+      // the post-success version landed via mutation response or SSE delta.
+      api.patchTask(
+        taskId,
+        updates,
+        (snapshot) => updateTaskInSnapshot(snapshot, taskId, updates, normalizeSnapshot),
+      );
     },
     submitSubtaskForm(subtaskId, formData) {
       const updates = {
@@ -386,7 +393,11 @@ export function createBoardActions(options) {
         status: normalizeStatus(String(formData.get("status") || "todo")),
       };
       syncState({ selectedSubtaskId: subtaskId });
-      api.patchSubtask(subtaskId, updates, (snapshot) => updateSubtaskInSnapshot(snapshot, subtaskId, updates, normalizeSnapshot));
+      api.patchSubtask(
+        subtaskId,
+        updates,
+        (snapshot) => updateSubtaskInSnapshot(snapshot, subtaskId, updates, normalizeSnapshot),
+      );
     },
     submitCreateSubtask(taskId, formData) {
       const input = {
@@ -456,20 +467,31 @@ export function createBoardActions(options) {
       }
       // Drag/drop is a status change only; do not mutate selection or modal state,
       // otherwise dropping a card while another task modal is open hijacks it.
-      api.patchTask(taskId, { status: nextStatus }, (snapshot) => updateTaskInSnapshot(snapshot, taskId, { status: nextStatus }, normalizeSnapshot));
+      // If-Match version resolved lazily by api.patchTask at fire time.
+      api.patchTask(
+        taskId,
+        { status: nextStatus },
+        (snapshot) => updateTaskInSnapshot(snapshot, taskId, { status: nextStatus }, normalizeSnapshot),
+      );
     },
     changeEpicStatus(epicId, newStatus) {
       const normalizedStatus = normalizeStatus(newStatus);
-      api.patchEpic(epicId, { status: normalizedStatus }, (snapshot) => {
-        const epic = snapshot.epics.find(e => e.id === epicId);
-        if (epic) epic.status = normalizedStatus;
-        return snapshot;
-      });
+      api.patchEpic(
+        epicId,
+        { status: normalizedStatus },
+        (snapshot) => {
+          const epic = snapshot.epics.find(e => e.id === epicId);
+          if (epic) epic.status = normalizedStatus;
+          return snapshot;
+        },
+      );
     },
     bulkSetStatus(epicId, newStatus) {
       const normalizedStatus = normalizeStatus(newStatus);
-      api.cascadeEpicStatus(epicId, normalizedStatus, (snapshot) =>
-        cascadeEpicStatusInSnapshot(snapshot, epicId, normalizedStatus, normalizeSnapshot),
+      api.cascadeEpicStatus(
+        epicId,
+        normalizedStatus,
+        (snapshot) => cascadeEpicStatusInSnapshot(snapshot, epicId, normalizedStatus, normalizeSnapshot),
       );
     },
     toggleEpicStatusFilter(status) {

package/src/board/assets/state/api.js

@@ -140,6 +140,57 @@ export function computeInverseDelta(previousSnapshot, optimisticSnapshot) {
   return inverse;
 }
 
+/**
+ * Filter an inverse delta produced by computeInverseDelta so we don't undo
+ * concurrent SSE-pushed advances that landed on the same entity while a
+ * mutation was in flight. Any record whose live snapshot `version` is strictly
+ * greater than the optimistic `ifMatchVersion` we sent is dropped from the
+ * `restored` arrays — the server-pushed state stays.
+ *
+ * If `optimisticVersion` is undefined/null/not-a-number we conservatively
+ * return the inverse delta unchanged (back-compat: legacy mutations without an
+ * If-Match version can't be reasoned about, so the original behavior wins).
+ *
+ * @param {object} inverseDelta - Inverse delta from computeInverseDelta.
+ * @param {object|null|undefined} currentSnapshot - Latest store snapshot.
+ * @param {number|null|undefined} optimisticVersion - The version we sent as If-Match.
+ * @returns {object}
+ */
+export function stripUpToDateEntitiesFromInverse(inverseDelta, currentSnapshot, optimisticVersion) {
+  if (typeof optimisticVersion !== "number" || !Number.isFinite(optimisticVersion)) {
+    return inverseDelta;
+  }
+  if (!inverseDelta || typeof inverseDelta !== "object") {
+    return inverseDelta;
+  }
+
+  const next = { ...inverseDelta };
+  for (const collection of SNAPSHOT_COLLECTIONS) {
+    const restored = inverseDelta[collection];
+    if (!Array.isArray(restored) || restored.length === 0) continue;
+
+    const liveRecords = Array.isArray(currentSnapshot?.[collection]) ? currentSnapshot[collection] : [];
+    const liveById = indexById(liveRecords);
+    const filtered = restored.filter((record) => {
+      if (!record || typeof record !== "object" || typeof record.id !== "string") return true;
+      const live = liveById.get(record.id);
+      const liveVersion = typeof live?.version === "number" ? live.version : null;
+      if (liveVersion === null) return true;
+      // Drop the restore when the live snapshot's version has already advanced
+      // past what we sent — an SSE delta or another mutation reconciliation
+      // moved this record forward and the user must see that.
+      return !(liveVersion > optimisticVersion);
+    });
+
+    if (filtered.length === 0) {
+      delete next[collection];
+    } else if (filtered.length !== restored.length) {
+      next[collection] = filtered;
+    }
+  }
+  return next;
+}
+
 async function readJsonPayload(response) {
   const text = await response.text();
   if (text.length === 0) {
@@ -208,6 +259,61 @@ function createTimeoutError(method, path, timeoutMs) {
   return error;
 }
 
+/**
+ * Normalize a caller-supplied entity version into a bare integer suitable for
+ * the If-Match header. The server accepts a bare integer, a quoted ETag, or a
+ * W/-prefixed weak ETag (RFC 7232 §3.1) — we emit the bare integer form for
+ * simplicity. Returns null when the caller didn't pass a usable version
+ * (preserves back-compat with older callers that omit the argument).
+ *
+ * Logs a single console.warn when a non-null/non-undefined input is rejected so
+ * a regression silently dropping the If-Match header is easy to spot in dev.
+ */
+function normalizeIfMatchVersion(version) {
+  if (version === undefined || version === null) {
+    return null;
+  }
+  if (typeof version === "number" && Number.isFinite(version) && version >= 0 && Number.isInteger(version)) {
+    return String(version);
+  }
+  try {
+    console.warn(`normalizeIfMatchVersion: ignoring non-integer/negative version ${JSON.stringify(version)} — If-Match header will be omitted`);
+  } catch {
+    // best-effort logging only
+  }
+  return null;
+}
+
+const ENTITY_KIND_COLLECTION = {
+  epic: "epics",
+  task: "tasks",
+  subtask: "subtasks",
+};
+
+/**
+ * Look up the current version of an entity from the live store snapshot.
+ *
+ * Resolved lazily at queue-executor fire time (rather than at action-enqueue
+ * time) so a second mutation enqueued while the first is in flight reads the
+ * post-success version — the server-acked snapshot landed via mutation
+ * response or SSE delta before processNext shifts the next mutation off the
+ * queue. Without this lazy read, rapid double-edits would carry stale
+ * If-Match versions and 409.
+ *
+ * @param {object} storeState - The live `model.store` mutable state object.
+ * @param {"epic"|"task"|"subtask"} kind
+ * @param {string} id
+ * @returns {number|undefined}
+ */
+function getCurrentVersion(storeState, kind, id) {
+  const collection = ENTITY_KIND_COLLECTION[kind];
+  if (!collection) return undefined;
+  const records = storeState?.snapshot?.[collection];
+  if (!Array.isArray(records)) return undefined;
+  const record = records.find((entry) => entry?.id === id);
+  return typeof record?.version === "number" ? record.version : undefined;
+}
+
 /**
  * Create a serial mutation queue.
  *
@@ -222,7 +328,7 @@ function createTimeoutError(method, path, timeoutMs) {
  * }}
  */
 export function createMutationQueue(model, rerender) {
-  /** @type {Array<{ mutationId: string, optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
+  /** @type {Array<{ mutationId: string, optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string, resolveIfMatch?: function }>} */
   const queue = [];
   let processing = false;
   /** @type {Array<() => void>} */
@@ -255,6 +361,19 @@ export function createMutationQueue(model, rerender) {
       // the request was in flight survive a rollback.
       let inverseDelta = null;
 
+      // Resolve the If-Match version LAZILY at fire-time so a queued
+      // second mutation on the same entity sees the post-success version that
+      // landed via mutation response or SSE delta. Capturing at enqueue time
+      // would 409 every rapid double-edit.
+      let ifMatchVersion;
+      if (typeof mutation.resolveIfMatch === "function") {
+        try {
+          ifMatchVersion = mutation.resolveIfMatch();
+        } catch {
+          ifMatchVersion = undefined;
+        }
+      }
+
       try {
         if (typeof mutation.optimistic === "function") {
           const previousSnapshot = model.store.snapshot;
@@ -269,7 +388,7 @@ export function createMutationQueue(model, rerender) {
           rerender();
         }
 
-        const data = await mutation.request();
+        const data = await mutation.request({ ifMatchVersion });
 
         if (data?.snapshot) {
           model.replaceSnapshot(data.snapshot);
@@ -285,20 +404,42 @@ export function createMutationQueue(model, rerender) {
           ? { type: "success", message: mutation.successMessage }
           : null;
       } catch (error) {
-        // Revert only the entities this mutation touched. Any unrelated
-        // entities updated by concurrent server deltas remain intact.
-        if (inverseDelta) {
-          model.applySnapshotDelta(inverseDelta);
+        const isStaleVersion = error?.code === "precondition_failed";
+
+        // Revert only the entities this mutation touched, but ALSO drop any
+        // entity whose live store version has already advanced past the
+        // optimistic version we sent: that means an SSE delta (or another
+        // queued mutation reconciliation) landed mid-flight and clobbering it
+        // with the pre-optimistic record would lose the user's most recent
+        // server-authoritative state.
+        const adjustedInverseDelta = inverseDelta
+          ? stripUpToDateEntitiesFromInverse(inverseDelta, model.store?.snapshot, ifMatchVersion)
+          : null;
+
+        if (adjustedInverseDelta) {
+          model.applySnapshotDelta(adjustedInverseDelta);
         }
 
-        const message = error instanceof Error ? error.message : String(error);
-        model.store.notice = {
-          type: "error",
-          title: "Action failed",
-          message,
-          retryLabel: "Retry",
-          retryMutationId: mutation.mutationId,
-        };
+        if (isStaleVersion) {
+          // Typed `stale_version` notice — no retry button because replaying
+          // the optimistic payload against the post-advance state would 409
+          // again. The user needs to refresh to compose against latest.
+          model.store.notice = {
+            type: "warning",
+            code: "stale_version",
+            title: "Stale update",
+            message: "Updated by another session — refresh to load the latest version.",
+          };
+        } else {
+          const message = error instanceof Error ? error.message : String(error);
+          model.store.notice = {
+            type: "error",
+            title: "Action failed",
+            message,
+            retryLabel: "Retry",
+            retryMutationId: mutation.mutationId,
+          };
+        }
 
         if (typeof mutation.onError === "function") {
           mutation.onError(error);
@@ -368,7 +509,18 @@ export function createApi(model, options) {
         }
       },
       onError(error) {
-        lastFailedMutation = tagged;
+        // Stale-version 409s are NOT retryable — the captured optimistic
+        // payload was composed against pre-advance state and replaying it
+        // would 409 again. Skip lastFailedMutation so the retry path can't
+        // even be invoked, and surface the typed stale_version notice (which
+        // does not carry a retry button) so the UI stays consistent.
+        if (error?.code === "precondition_failed") {
+          if (lastFailedMutation?.mutationId === mutationId) {
+            lastFailedMutation = null;
+          }
+        } else {
+          lastFailedMutation = tagged;
+        }
         if (typeof tagged.onError === "function") {
           tagged.onError(error);
         }
@@ -431,47 +583,94 @@ export function createApi(model, options) {
       return true;
     },
 
-    patchEpic(epicId, updates, optimistic) {
+    patchEpic(epicId, updates, optimistic, options) {
+      // Per-call override wins; otherwise read the live store at fire-time so
+      // queued back-to-back edits on the same entity carry the post-success
+      // version rather than a stale enqueue-time snapshot.
+      const explicitVersion = options?.ifMatchVersion;
+      const resolveIfMatch = explicitVersion !== undefined
+        ? () => explicitVersion
+        : () => getCurrentVersion(model.store, "epic", epicId);
       enqueueMutation({
         optimistic,
         successMessage: "Epic saved.",
-        request: () => request(`/api/epics/${encodeURIComponent(epicId)}`, {
-          method: "PATCH",
-          body: JSON.stringify(updates),
-        }),
+        entityKind: "epic",
+        entityId: epicId,
+        resolveIfMatch,
+        request: ({ ifMatchVersion } = {}) => {
+          const ifMatch = normalizeIfMatchVersion(ifMatchVersion);
+          return request(`/api/epics/${encodeURIComponent(epicId)}`, {
+            method: "PATCH",
+            headers: ifMatch !== null ? { "if-match": ifMatch } : undefined,
+            body: JSON.stringify(updates),
+          });
+        },
       });
     },
 
-    patchTask(taskId, updates, optimistic) {
+    patchTask(taskId, updates, optimistic, options) {
+      const explicitVersion = options?.ifMatchVersion;
+      const resolveIfMatch = explicitVersion !== undefined
+        ? () => explicitVersion
+        : () => getCurrentVersion(model.store, "task", taskId);
       enqueueMutation({
         optimistic,
         successMessage: "Task saved.",
-        request: () => request(`/api/tasks/${encodeURIComponent(taskId)}`, {
-          method: "PATCH",
-          body: JSON.stringify(updates),
-        }),
+        entityKind: "task",
+        entityId: taskId,
+        resolveIfMatch,
+        request: ({ ifMatchVersion } = {}) => {
+          const ifMatch = normalizeIfMatchVersion(ifMatchVersion);
+          return request(`/api/tasks/${encodeURIComponent(taskId)}`, {
+            method: "PATCH",
+            headers: ifMatch !== null ? { "if-match": ifMatch } : undefined,
+            body: JSON.stringify(updates),
+          });
+        },
       });
     },
 
-    patchSubtask(subtaskId, updates, optimistic) {
+    patchSubtask(subtaskId, updates, optimistic, options) {
+      const explicitVersion = options?.ifMatchVersion;
+      const resolveIfMatch = explicitVersion !== undefined
+        ? () => explicitVersion
+        : () => getCurrentVersion(model.store, "subtask", subtaskId);
       enqueueMutation({
         optimistic,
         successMessage: "Subtask saved.",
-        request: () => request(`/api/subtasks/${encodeURIComponent(subtaskId)}`, {
-          method: "PATCH",
-          body: JSON.stringify(updates),
-        }),
+        entityKind: "subtask",
+        entityId: subtaskId,
+        resolveIfMatch,
+        request: ({ ifMatchVersion } = {}) => {
+          const ifMatch = normalizeIfMatchVersion(ifMatchVersion);
+          return request(`/api/subtasks/${encodeURIComponent(subtaskId)}`, {
+            method: "PATCH",
+            headers: ifMatch !== null ? { "if-match": ifMatch } : undefined,
+            body: JSON.stringify(updates),
+          });
+        },
       });
     },
 
-    cascadeEpicStatus(epicId, status, optimistic) {
+    cascadeEpicStatus(epicId, status, optimistic, options) {
+      const explicitVersion = options?.ifMatchVersion;
+      const resolveIfMatch = explicitVersion !== undefined
+        ? () => explicitVersion
+        : () => getCurrentVersion(model.store, "epic", epicId);
       enqueueMutation({
         optimistic,
         successMessage: "Epic cascade status updated.",
-        request: () => request(`/api/epics/${encodeURIComponent(epicId)}/cascade`, {
-          method: "PATCH",
-          body: JSON.stringify({ status }),
-        }),
+        entityKind: "epic",
+        entityId: epicId,
+        resolveIfMatch,
+        request: ({ ifMatchVersion } = {}) => {
+          const ifMatch = normalizeIfMatchVersion(ifMatchVersion);
+          return request(`/api/epics/${encodeURIComponent(epicId)}/cascade`, {
+            method: "PATCH",
+            headers: ifMatch !== null ? { "if-match": ifMatch } : undefined,
+            body: JSON.stringify({ status }),
+          });
+        },
       });
     },
 

package/src/board/assets/state/utils.js

@@ -46,6 +46,21 @@ function normalizeOwner(value) {
   return typeof value === "string" ? value : null;
 }
 
+/**
+ * Normalize a server-provided version into a non-negative integer, or null if
+ * the value is missing/invalid. The board uses this to populate If-Match
+ * headers; non-integers and negative numbers are silently dropped here so the
+ * mutation queue treats the entity as version-less (back-compat path).
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+function normalizeVersion(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    return null;
+  }
+  return value;
+}
+
 /**
  * @param {any[]} tasks
  * @returns {Record<string, number>}
@@ -89,6 +104,7 @@ export function normalizeSnapshot(rawSnapshot) {
       owner: normalizeOwner(task.owner),
       createdAt,
       updatedAt: normalizeTimestamp(task.updatedAt, createdAt),
+      version: normalizeVersion(task.version),
       blockedBy: [],
       blocks: [],
       dependencyIds: [],
@@ -118,6 +134,7 @@ export function normalizeSnapshot(rawSnapshot) {
       owner: normalizeOwner(subtask.owner),
       createdAt,
       updatedAt: normalizeTimestamp(subtask.updatedAt, createdAt),
+      version: normalizeVersion(subtask.version),
       blockedBy: [],
       blocks: [],
       dependencyIds: [],
@@ -188,6 +205,7 @@ export function normalizeSnapshot(rawSnapshot) {
       status: normalizeStatus(String(epic.status ?? "todo")),
       createdAt,
       updatedAt: normalizeTimestamp(epic.updatedAt, createdAt),
+      version: normalizeVersion(epic.version),
       taskIds: epicTasks.map((task) => task.id),
       counts: deriveCounts(epicTasks),
       searchText: "",

package/src/board/routes.ts

@@ -612,6 +612,16 @@ function preconditionFailedResponse(details: PreconditionFailedDetails): Respons
   });
 }
 
+function preconditionRequiredResponse(): Response {
+  return jsonResponse(428, {
+    ok: false,
+    error: {
+      code: "precondition_required",
+      message: "If-Match header is required for PATCH requests",
+    },
+  });
+}
+
 function readIdempotencyKey(request: Request, body: Record<string, unknown>): string | null {
   const headerKey = request.headers.get("x-trekoon-idempotency-key");
   if (typeof headerKey === "string" && headerKey.trim().length > 0) {
@@ -705,12 +715,12 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
           const body = await parseJsonBody(request);
           const status = readRequiredString(body, "status");
           const ifMatch = parseIfMatchHeader(request);
+          if (ifMatch === null) {
+            return preconditionRequiredResponse();
+          }
           // CAS path: precondition is enforced inside the write transaction
-          // (see PreconditionFailedError catch below). Missing-header path
-          // preserves back-compat with clients that don't send If-Match.
-          const plan = ifMatch !== null
-            ? mutations.updateEpicStatusCascadeWithIfMatch(epicId, ifMatch, status)
-            : mutations.updateEpicStatusCascade(epicId, status);
+          // (see PreconditionFailedError catch below).
+          const plan = mutations.updateEpicStatusCascadeWithIfMatch(epicId, ifMatch, status);
           return respondWithMutationDelta(domain, {
             plan,
           }, {
@@ -725,14 +735,15 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         const epicId = epicMatch[1] ?? "";
         const body = await parseJsonBody(request);
         const ifMatch = parseIfMatchHeader(request);
+        if (ifMatch === null) {
+          return preconditionRequiredResponse();
+        }
         const epicInput = {
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
         };
-        const epic = ifMatch !== null
-          ? mutations.updateEpicWithIfMatch(epicId, ifMatch, epicInput)
-          : mutations.updateEpic(epicId, epicInput);
+        const epic = mutations.updateEpicWithIfMatch(epicId, ifMatch, epicInput);
           return respondWithMutationDelta(domain, { epic }, { epicIds: [epic.id] });
         }
 
@@ -741,15 +752,16 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         const taskId = taskMatch[1] ?? "";
         const body = await parseJsonBody(request);
         const ifMatch = parseIfMatchHeader(request);
+        if (ifMatch === null) {
+          return preconditionRequiredResponse();
+        }
         const taskInput = {
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
           owner: readOptionalNullableString(body, "owner"),
         };
-        const task = ifMatch !== null
-          ? mutations.updateTaskWithIfMatch(taskId, ifMatch, taskInput)
-          : mutations.updateTask(taskId, taskInput);
+        const task = mutations.updateTaskWithIfMatch(taskId, ifMatch, taskInput);
           return respondWithMutationDelta(domain, { task }, { epicIds: [task.epicId], taskIds: [task.id] });
         }
 
@@ -758,15 +770,16 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         const subtaskId = subtaskMatch[1] ?? "";
         const body = await parseJsonBody(request);
         const ifMatch = parseIfMatchHeader(request);
+        if (ifMatch === null) {
+          return preconditionRequiredResponse();
+        }
         const subtaskInput = {
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
           owner: readOptionalNullableString(body, "owner"),
         };
-        const subtask = ifMatch !== null
-          ? mutations.updateSubtaskWithIfMatch(subtaskId, ifMatch, subtaskInput)
-          : mutations.updateSubtask(subtaskId, subtaskInput);
+        const subtask = mutations.updateSubtaskWithIfMatch(subtaskId, ifMatch, subtaskInput);
           const task = domain.getTaskOrThrow(subtask.taskId);
           return respondWithMutationDelta(domain, { subtask }, { epicIds: [task.epicId], taskIds: [task.id], subtaskIds: [subtask.id] });
         }