makersclaw 0.8.0 → 0.8.1

package/registry/blocks/schedule-engine/index.js

@@ -0,0 +1,9 @@
+// The schedule-engine block — `makersclaw add schedule-engine`. Fixed:
+// compose it through its functions (README.md beside this file). Pure
+// JavaScript, no React: the browser, a script and an agent run the same
+// rules.
+export * from "./engine";
+export { taskTree, descendantsOf, positionBetween, siblingOrder } from "./tree";
+export { KIND_WORDS, lagWords, shortForm, waitsWords, parseWaits } from "./waits";
+export { nextWorkday, summaryChanges, placeNew, familyLinkProblem, outlineChange, lengthChange, overlapsOf, snapshotOf } from "./place";
+export { operate, plain, OPERATIONS } from "./ops";

package/registry/blocks/schedule-engine/ops.js

@@ -0,0 +1,71 @@
+// One entry for the questions an agent (or a script) asks of the rules:
+// the same functions a screen runs, over JSON. A package's
+// `references/plan.mjs` reads `{ operation, tasks, links, … }` on stdin and
+// prints `operate(input)` as JSON, so the dates an agent states or writes
+// are the dates the chart shows.
+//
+//   schedule  the plan: rows, links, finish, critical path, stuck, violations
+//   move      { moves: [{ id, start, due }] }       what a move shifts
+//   replan    { today }                              late work off the past
+//   mend      {}                                     broken links aligned
+//   place     { add, today, project }                where a new task goes
+//   outline   { id, kind, parent_id }                an outline change
+//   length    { id, days, project }                  a length, dependents follow
+//   link      { task_id, depends_on_id, kind, lag }  can it be made; what it shifts
+//   snapshot  {}                                     the rows a baseline keeps
+//   load      { owner_key }                          who is on two things at once
+//
+// Maps become arrays of [id, value] pairs' objects (`rows` an object keyed
+// by id); Sets become arrays. Throws nothing: a bad input answers { ok: false, error }.
+
+import { alignConflicts, linkKind, linkProblem, longPole, replanFromToday, schedule, shiftDependents } from "./engine";
+import { lengthChange, outlineChange, overlapsOf, placeNew, snapshotOf, summaryChanges } from "./place";
+
+/** Maps and Sets as plain JSON values. */
+export function plain(value) {
+  return JSON.parse(JSON.stringify(value, (_k, v) => (v instanceof Map ? Object.fromEntries(v) : v instanceof Set ? [...v] : v)));
+}
+
+/** The operations an agent may ask for. */
+export const OPERATIONS = ["schedule", "move", "replan", "mend", "place", "outline", "length", "link", "snapshot", "load"];
+
+export function operate(input = {}) {
+  try {
+    const { tasks = [], links = [], operation = "schedule" } = input;
+    switch (operation) {
+      case "schedule": {
+        const plan = schedule(tasks, links);
+        return plain({ ok: true, ...plan, longPole: longPole(plan) });
+      }
+      case "move":
+        return plain({ ok: true, ...shiftDependents(tasks, links, input.moves ?? []) });
+      case "replan":
+        return plain({ ok: true, ...replanFromToday(tasks, links, input.today) });
+      case "mend":
+        return plain({ ok: true, ...alignConflicts(tasks, links) });
+      case "place": {
+        const placed = placeNew(tasks, { add: input.add ?? {}, today: input.today, project: input.project ?? null });
+        const next = [...tasks, { id: "__new", parent_id: placed.parent_id, start_date: placed.start_date, due_date: placed.due_date, is_milestone: placed.is_milestone, progress: 0, status: "todo" }];
+        return plain({ ...placed, summaries: placed.resum ? summaryChanges(next, links, ["__new"]) : [] });
+      }
+      case "outline":
+        return plain(outlineChange(tasks, links, { id: input.id, kind: input.kind, parent_id: input.parent_id ?? null }));
+      case "length":
+        return plain(lengthChange(tasks, links, { id: input.id, days: input.days, project: input.project ?? null }));
+      case "link": {
+        const problem = linkProblem(tasks, links, input.task_id, input.depends_on_id);
+        if (problem) return { ok: false, error: problem };
+        const next = [...links, { id: "__new", task_id: input.task_id, depends_on_id: input.depends_on_id, kind: input.kind ?? "finish_to_start", lag_days: Number(input.lag ?? 0) || 0 }];
+        return plain({ ok: true, kind: linkKind(input.kind), ...shiftDependents(tasks, links, [], { nextLinks: next }) });
+      }
+      case "snapshot":
+        return plain({ ok: true, ...snapshotOf(tasks, links) });
+      case "load":
+        return plain({ ok: true, overlaps: overlapsOf(tasks, schedule(tasks, links), { ownerOf: (t) => t[input.owner_key ?? "assignee_id"] }) });
+      default:
+        return { ok: false, error: `Unknown operation "${operation}". Use one of: ${OPERATIONS.join(", ")}.` };
+    }
+  } catch (error) {
+    return { ok: false, error: error?.message ?? String(error) };
+  }
+}

package/registry/blocks/schedule-engine/place.js

@@ -0,0 +1,294 @@
+// Planning a write: where a new task goes, what an outline change moves, which
+// summaries must re-span. Pure functions over the same rows the engine takes,
+// so a screen and an agent that ask the same question get the same answer.
+//
+// None of these writes anything. Each returns exactly the values a write
+// needs ({ parent_id, sort_order, start_date, due_date, summaries, changes … }),
+// and the caller hands them to its own save.
+//
+// Rows in (as the engine's):
+//   task  { id, parent_id, title, start_date, due_date, is_milestone, progress, status, position }
+//   link  { id, task_id, depends_on_id, kind, lag_days }
+
+import { addWorkdays, datesOf, dayOf, isoOf, makeCalendar, schedule, shiftDependents, spanOf } from "./engine";
+import { descendantsOf, positionBetween, siblingOrder, taskTree } from "./tree";
+
+const ISO = /^\d{4}-\d{2}-\d{2}$/;
+const same = (a, b) => String(a ?? "") === String(b ?? "");
+const quote = (s) => `“${String(s ?? "").slice(0, 90)}”`;
+
+/** The working day on or after `iso`, as a date. */
+export function nextWorkday(iso, calendar = "weekdays") {
+  const cal = makeCalendar(calendar);
+  const d = dayOf(iso);
+  return d == null ? null : isoOf(cal.dayAt(cal.startIndex(d)));
+}
+
+/**
+ * Summaries whose stored dates differ from the span of the work under them:
+ * the ancestors of each id (and each id itself when it is a summary).
+ * → [{ id, start_date, due_date }]
+ */
+export function summaryChanges(tasks, links, ids) {
+  const plan = schedule(tasks, links);
+  const byId = new Map((tasks ?? []).map((t) => [String(t.id), t]));
+  const want = new Set();
+  for (const id of ids ?? []) {
+    for (let p = byId.get(String(id))?.parent_id; p; p = byId.get(String(p))?.parent_id) {
+      if (want.has(String(p))) break;
+      want.add(String(p));
+    }
+    if (id) want.add(String(id));
+  }
+  const out = [];
+  for (const id of want) {
+    const row = plan.rows.get(id);
+    const t = byId.get(id);
+    if (!row?.summary || !t) continue;
+    if (!same(t.start_date, row.start) || !same(t.due_date, row.due)) out.push({ id, start_date: row.start, due_date: row.due });
+  }
+  return out;
+}
+
+/**
+ * Where a new task goes and the dates it starts with.
+ *
+ *   add: { title, parent_id, after_id, start, due, days, milestone }
+ *   today: 'YYYY-MM-DD' in the team's zone
+ *   project: { start_date }
+ *
+ * It lands after `after_id` at the same level, or as the last sub-task of
+ * `parent_id`, or last in the project. Undated input gets dates: a first
+ * sub-task takes its parent's dates; a task added after another starts the
+ * next working day; otherwise the later of today and the project's start.
+ * Three working days long unless `days` says.
+ *
+ * → { ok, parent_id, sort_order, start_date, due_date, is_milestone,
+ *     resum: boolean (the parent already had sub-tasks: re-span it after) }
+ */
+export function placeNew(tasks, { add = {}, today, project = null } = {}) {
+  const list = tasks ?? [];
+  const byId = new Map(list.map((t) => [String(t.id), t]));
+  const after = add.after_id && byId.has(String(add.after_id)) ? byId.get(String(add.after_id)) : null;
+  const parent = add.parent_id && byId.has(String(add.parent_id)) ? byId.get(String(add.parent_id)) : after?.parent_id ? byId.get(String(after.parent_id)) ?? null : null;
+  const siblings = list.filter((t) => same(t.parent_id, parent?.id)).sort(siblingOrder);
+  let sort_order;
+  if (after && same(after.parent_id, parent?.id)) {
+    const i = siblings.findIndex((t) => same(t.id, after.id));
+    sort_order = positionBetween(after, siblings[i + 1] ?? null);
+  } else sort_order = positionBetween(siblings[siblings.length - 1] ?? null, null);
+
+  let s = ISO.test(String(add.start ?? "")) ? add.start : null;
+  let d = ISO.test(String(add.due ?? "")) ? add.due : null;
+  if (!s) {
+    const parentLeaf = parent && !list.some((t) => same(t.parent_id, parent.id)) && parent.start_date;
+    if (parentLeaf) {
+      s = String(parent.start_date);
+      d = d ?? String(parent.due_date ?? parent.start_date);
+    } else if (after?.due_date) s = addWorkdays(String(after.due_date), 1);
+    else {
+      const now = ISO.test(String(today ?? "")) ? today : isoOf(Math.floor(Date.now() / 86400000));
+      const begins = project?.start_date ? String(project.start_date) : null;
+      s = nextWorkday(begins && begins > now ? begins : now);
+    }
+  }
+  const length = Math.max(1, Math.min(500, Math.trunc(Number(add.days) || 0)));
+  const milestone = Boolean(add.milestone);
+  if (milestone) d = s = d ?? s;
+  else if (Number(add.days) >= 1) d = addWorkdays(nextWorkday(s), length - 1);
+  else if (!d || d < s) d = addWorkdays(nextWorkday(s), 2);
+  return {
+    ok: true,
+    parent_id: parent ? String(parent.id) : null,
+    sort_order,
+    start_date: s,
+    due_date: d,
+    is_milestone: milestone,
+    resum: Boolean(parent && list.some((t) => same(t.parent_id, parent.id))),
+  };
+}
+
+/** A link between a task (or anything under it) and a would-be parent can't stay. */
+export function familyLinkProblem(tasks, links, id, parentId) {
+  const under = descendantsOf(tasks, id);
+  under.add(String(id));
+  const bad = (links ?? []).find((l) => (under.has(String(l.task_id)) && same(l.depends_on_id, parentId)) || (under.has(String(l.depends_on_id)) && same(l.task_id, parentId)));
+  if (!bad) return null;
+  const title = (x) => (tasks ?? []).find((t) => same(t.id, x))?.title ?? "a task";
+  return `Remove the link between ${quote(title(bad.task_id))} and ${quote(title(bad.depends_on_id))} first: a task can't wait on its own summary.`;
+}
+
+/**
+ * A change of outline. `kind`: "in" (a sub-task of the row above), "out"
+ * (up a level, just after its old parent), "up" / "down" (one place among
+ * its siblings), "under" (last child of `parent_id`, or the top level for
+ * null).
+ *
+ * → { ok: false, error } or { ok: true, id, parent_id, old_parent_id,
+ *     sort_order, order_only, changes (date changes the outline binds, as
+ *     shiftDependents), summaries (re-spans: the old parent, the new one),
+ *     finishBefore, finishAfter, words }
+ */
+export function outlineChange(tasks, links, { id, kind, parent_id = null }) {
+  const list = tasks ?? [];
+  const task = list.find((t) => same(t.id, id));
+  if (!task) return { ok: false, error: "That task is gone." };
+  const level = (pid) => list.filter((t) => same(t.parent_id, pid)).sort(siblingOrder);
+  const siblings = level(task.parent_id);
+  const i = siblings.findIndex((t) => same(t.id, id));
+  let newParent = task.parent_id ?? null;
+  let position;
+  let words;
+  if (kind === "up" || kind === "down") {
+    const j = kind === "up" ? i - 1 : i + 1;
+    if (j < 0 || j >= siblings.length) return { ok: false, error: kind === "up" ? "It's already first in its phase." : "It's already last in its phase." };
+    position = kind === "up" ? positionBetween(siblings[j - 1] ?? null, siblings[j]) : positionBetween(siblings[j], siblings[j + 1] ?? null);
+    words = `${quote(task.title)} ${kind} one place`;
+  } else if (kind === "in") {
+    if (i <= 0) return { ok: false, error: "There's nothing above it at this level to put it under." };
+    const parent = siblings[i - 1];
+    const problem = familyLinkProblem(list, links, id, parent.id);
+    if (problem) return { ok: false, error: problem };
+    const kids = level(parent.id);
+    newParent = String(parent.id);
+    position = positionBetween(kids[kids.length - 1] ?? null, null);
+    words = `${quote(task.title)} under ${quote(parent.title)}`;
+  } else if (kind === "out") {
+    const parent = task.parent_id ? list.find((t) => same(t.id, task.parent_id)) : null;
+    if (!parent) return { ok: false, error: "It's already at the top level." };
+    const grand = parent.parent_id ?? null;
+    if (grand) {
+      const problem = familyLinkProblem(list, links, id, grand);
+      if (problem) return { ok: false, error: problem };
+    }
+    const above = level(grand);
+    const j = above.findIndex((t) => same(t.id, parent.id));
+    newParent = grand == null ? null : String(grand);
+    position = positionBetween(parent, above[j + 1] ?? null);
+    words = `${quote(task.title)} out of ${quote(parent.title)}`;
+  } else if (kind === "under") {
+    const parent = parent_id ? list.find((t) => same(t.id, parent_id)) : null;
+    if (parent_id && !parent) return { ok: false, error: "That phase is gone." };
+    if (parent && (same(parent.id, id) || descendantsOf(list, id).has(String(parent.id)))) return { ok: false, error: "A task can't go under itself or one of its own sub-tasks." };
+    if (same(task.parent_id, parent?.id)) return { ok: false, error: "It's there already." };
+    if (parent) {
+      const problem = familyLinkProblem(list, links, id, parent.id);
+      if (problem) return { ok: false, error: problem };
+    }
+    const kids = level(parent?.id ?? null);
+    newParent = parent ? String(parent.id) : null;
+    position = positionBetween(kids[kids.length - 1] ?? null, null);
+    words = `${quote(task.title)} under ${parent ? quote(parent.title) : "the top level"}`;
+  } else return { ok: false, error: "Unknown outline change." };
+
+  const moved = !same(newParent, task.parent_id);
+  let result = { changes: [], finishBefore: schedule(list, links).finish, finishAfter: schedule(list, links).finish };
+  const summaries = [];
+  if (moved) {
+    const nextTasks = list.map((t) => (same(t.id, id) ? { ...t, parent_id: newParent } : t));
+    result = shiftDependents(list, links, [], { nextTasks });
+    const afterTasks = nextTasks.map((t) => {
+      const c = result.changes.find((x) => same(x.id, t.id));
+      return c ? { ...t, start_date: c.start_date, due_date: c.due_date } : t;
+    });
+    // The summary it left is re-spanned. The one it joined keeps its own
+    // dates, unless the task was put there by name ("under"): putting a task
+    // under another with a key and taking it out again loses nothing.
+    if (task.parent_id) summaries.push(...summaryChanges(afterTasks, links, [task.parent_id]));
+    if (newParent && kind === "under") summaries.push(...summaryChanges(afterTasks, links, [newParent]).filter((s) => !summaries.some((x) => same(x.id, s.id))));
+  }
+  return {
+    ok: true,
+    id: String(id),
+    parent_id: newParent,
+    old_parent_id: task.parent_id == null ? null : String(task.parent_id),
+    sort_order: position,
+    order_only: !moved,
+    changes: result.changes.filter((c) => !c.summary),
+    summaries,
+    finishBefore: result.finishBefore,
+    finishAfter: result.finishAfter,
+    words,
+  };
+}
+
+/**
+ * Give a task a length: it keeps its start (or takes the project's) and
+ * the dependents follow. → shiftDependents' result, or { ok: false, error }.
+ */
+export function lengthChange(tasks, links, { id, days, project = null }) {
+  const len = Math.trunc(Number(days));
+  if (!(len >= 1 && len <= 500)) return { ok: false, error: "A length is a whole number of working days, 1 or more." };
+  const task = (tasks ?? []).find((t) => same(t.id, id));
+  if (!task) return { ok: false, error: "That task is gone." };
+  if (task.is_milestone) return { ok: false, error: "A milestone has no length." };
+  const start = task.start_date ? String(task.start_date).slice(0, 10) : project?.start_date ? nextWorkday(String(project.start_date)) : null;
+  if (!start) return { ok: false, error: "Set the project's start date first: a length needs a day to count from." };
+  const s = spanOf({ start_date: start, due_date: start });
+  const m = datesOf(s.s, len, false);
+  return { ok: true, ...shiftDependents(tasks, links, [{ id: String(id), start: m.start, due: m.due }]), moves: [{ id: String(id), start: m.start, due: m.due }] };
+}
+
+/**
+ * Who is on two things at once: for each owner, the stretches of working
+ * days where two or more of their unfinished, dated tasks overlap.
+ * `ownerOf(task)` → a key (default `assignee_id`).
+ * → [{ owner, from, to, count, ids }] sorted by owner then date.
+ */
+export function overlapsOf(tasks, plan, { ownerOf = (t) => t.assignee_id } = {}) {
+  const cal = makeCalendar();
+  const by = new Map();
+  for (const t of tasks ?? []) {
+    const r = plan?.rows?.get(String(t.id));
+    const owner = ownerOf(t);
+    if (!r || !r.dated || r.summary || r.milestone || r.pinned || owner == null || owner === "") continue;
+    const a = dayOf(r.planStart);
+    const b = dayOf(r.planDue);
+    if (a == null || b == null) continue;
+    const k = String(owner);
+    if (!by.has(k)) by.set(k, []);
+    by.get(k).push({ id: String(t.id), s: cal.startIndex(a), e: cal.lastIndex(b) });
+  }
+  const out = [];
+  for (const [owner, spans] of by) {
+    const points = new Map();
+    for (const sp of spans) for (let x = sp.s; x <= sp.e; x += 1) points.set(x, (points.get(x) ?? 0) + 1);
+    let run = null;
+    const flush = () => {
+      if (!run) return;
+      const ids = spans.filter((sp) => sp.s <= run.e && sp.e >= run.s).map((sp) => sp.id);
+      out.push({ owner, from: isoOf(cal.dayAt(run.s)), to: isoOf(cal.dayAt(run.e)), count: run.n, ids });
+      run = null;
+    };
+    const days = [...points.keys()].sort((x, y) => x - y);
+    for (const x of days) {
+      const n = points.get(x);
+      if (n >= 2) {
+        if (run && run.e === x - 1) {
+          run.e = x;
+          run.n = Math.max(run.n, n);
+        } else {
+          flush();
+          run = { s: x, e: x, n };
+        }
+      } else flush();
+    }
+    flush();
+  }
+  return out.sort((a, b) => String(a.owner).localeCompare(String(b.owner)) || a.from.localeCompare(b.from));
+}
+
+/** The rows a baseline keeps: every dated, live task as it is planned. → { finish_date, data } */
+export function snapshotOf(tasks, links) {
+  const plan = schedule(tasks, links);
+  const data = [];
+  for (const t of tasks ?? []) {
+    if (!t || String(t.status ?? "") === "cancelled") continue;
+    const r = plan.rows.get(String(t.id));
+    if (!r?.dated) continue;
+    data.push({ task_id: String(t.id), title: String(t.title ?? ""), start_date: r.start, due_date: r.due, is_milestone: Boolean(t.is_milestone) });
+  }
+  return { finish_date: plan.finish, data };
+}
+
+export { taskTree };

package/registry/blocks/schedule-engine/tree.js

@@ -0,0 +1,79 @@
+// The task tree: outline order and outline numbers (1, 1.1, 1.2, 2 …).
+// Pure, like engine.js: the chart, the server's writes and the tests use it.
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
+
+/** Sibling order: position, then when it was made, then id. */
+export function siblingOrder(a, b) {
+  return num(a.position) - num(b.position) || String(a.created_at ?? "").localeCompare(String(b.created_at ?? "")) || String(a.id).localeCompare(String(b.id));
+}
+
+/**
+ * → { order: [{ id, parentId, depth, outline, childCount, index }], byId: Map(id → entry) }
+ * `order` walks the tree depth first. A parent outside `tasks` makes a
+ * root; a parent chain that loops is cut.
+ */
+export function taskTree(tasks) {
+  const list = (tasks ?? []).filter((t) => t && t.id != null);
+  const ids = new Set(list.map((t) => String(t.id)));
+  const kids = new Map();
+  for (const t of list) {
+    const pid = t.parent_id != null && ids.has(String(t.parent_id)) && String(t.parent_id) !== String(t.id) ? String(t.parent_id) : "";
+    if (!kids.has(pid)) kids.set(pid, []);
+    kids.get(pid).push(t);
+  }
+  for (const arr of kids.values()) arr.sort(siblingOrder);
+  const order = [];
+  const byId = new Map();
+  const seen = new Set();
+  const walk = (pid, depth, prefix) => {
+    (kids.get(pid) ?? []).forEach((t, i) => {
+      const id = String(t.id);
+      if (seen.has(id)) return;
+      seen.add(id);
+      const outline = prefix ? `${prefix}.${i + 1}` : String(i + 1);
+      const entry = { id, parentId: pid || null, depth, outline, childCount: (kids.get(id) ?? []).length, index: order.length };
+      order.push(entry);
+      byId.set(id, entry);
+      walk(id, depth + 1, outline);
+    });
+  };
+  walk("", 0, "");
+  // Anything a loop hid becomes a root at the end.
+  for (const t of list) {
+    const id = String(t.id);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const entry = { id, parentId: null, depth: 0, outline: String(order.filter((e) => e.depth === 0).length + 1), childCount: 0, index: order.length };
+    order.push(entry);
+    byId.set(id, entry);
+  }
+  return { order, byId };
+}
+
+/** Every id below `id` (not including it). */
+export function descendantsOf(tasks, id) {
+  const out = new Set();
+  const want = [String(id)];
+  while (want.length) {
+    const p = want.pop();
+    for (const t of tasks ?? []) {
+      const tid = String(t.id);
+      if (String(t.parent_id ?? "") === p && !out.has(tid)) {
+        out.add(tid);
+        want.push(tid);
+      }
+    }
+  }
+  return out;
+}
+
+/** A position between two siblings (or after the last one). */
+export function positionBetween(before, after) {
+  const a = before == null ? null : num(before.position);
+  const b = after == null ? null : num(after.position);
+  if (a == null && b == null) return 1;
+  if (a == null) return b - 1;
+  if (b == null) return a + 1;
+  return (a + b) / 2;
+}

package/registry/blocks/schedule-engine/waits.js

@@ -0,0 +1,80 @@
+// The short form schedulers write for "what a task waits on": `2.5FS`,
+// `6.3SS+5d`, `3.4SF-2d`, several joined with a semicolon. An outline
+// number (the tree's 1, 1.1, 1.2.3) names the task, FS / SS / FF / SF the
+// kind (finish-to-start when left out), and a signed number of working
+// days the lag. Pure, like the engine.
+
+import { LINK_KINDS, linkKind } from "./engine";
+
+/** The four kinds, named in full and in a clause ("B starts after A finishes"). */
+export const KIND_WORDS = {
+  FS: { name: "Finish to start", clause: (b, a) => `${b} starts after ${a} finishes` },
+  SS: { name: "Start to start", clause: (b, a) => `${b} can start once ${a} has started` },
+  FF: { name: "Finish to finish", clause: (b, a) => `${b} can finish once ${a} has finished` },
+  SF: { name: "Start to finish", clause: (b, a) => `${b} can finish once ${a} has started` },
+};
+
+/** `+2d`, `-1d` or "" for no lag. */
+export function lagWords(lag) {
+  const n = Math.trunc(Number(lag) || 0);
+  return n ? `${n > 0 ? "+" : "-"}${Math.abs(n)}d` : "";
+}
+
+/** One link as the short form: `2.4FS+2d`. */
+export function shortForm(outline, kind, lag) {
+  return `${outline}${linkKind(kind)}${lagWords(lag)}`;
+}
+
+/**
+ * What a task waits on, in the short form.
+ * `links`: [{ task_id, depends_on_id, kind, lag_days }]; `outlineOf(id)` → "2.4".
+ * Only links of `taskId`; ordered by the predecessor's outline.
+ */
+export function waitsWords(links, taskId, outlineOf) {
+  return (links ?? [])
+    .filter((l) => String(l.task_id) === String(taskId))
+    .map((l) => ({ outline: outlineOf(String(l.depends_on_id)) ?? "", kind: l.kind, lag: l.lag_days }))
+    .filter((l) => l.outline)
+    .sort((a, b) => a.outline.localeCompare(b.outline, undefined, { numeric: true }))
+    .map((l) => shortForm(l.outline, l.kind, l.lag))
+    .join("; ");
+}
+
+const PART = /^\s*([0-9]+(?:\.[0-9]+)*)\s*(FS|SS|FF|SF)?\s*(?:([+-])\s*([0-9]+)\s*d?)?\s*$/i;
+
+/**
+ * Read the short form back. `idOf(outline)` → the task's id, or null when
+ * the file / the screen has no such task.
+ * → { links: [{ depends_on_id, outline, kind ("finish_to_start" …), lag_days }],
+ *     problems: [{ part, why }] }
+ */
+export function parseWaits(text, idOf) {
+  const links = [];
+  const problems = [];
+  for (const raw of String(text ?? "").split(/[;,]/)) {
+    const part = raw.trim();
+    if (!part) continue;
+    const m = PART.exec(part);
+    if (!m) {
+      problems.push({ part, why: `"${part}" isn't a task number with a kind and a lag, like 2.4FS+2d.` });
+      continue;
+    }
+    const outline = m[1];
+    const id = idOf(outline);
+    if (id == null) {
+      problems.push({ part, why: `There is no task ${outline}.` });
+      continue;
+    }
+    if (links.some((l) => l.depends_on_id === String(id))) {
+      problems.push({ part, why: `Task ${outline} is listed twice.` });
+      continue;
+    }
+    const lag = m[3] ? Number(m[4]) * (m[3] === "-" ? -1 : 1) : 0;
+    if (lag < -250 || lag > 250) {
+      problems.push({ part, why: "A lag is between -250 and 250 working days." });
+      continue;
+    }
+    links.push({ depends_on_id: String(id), outline, kind: LINK_KINDS[linkKind(m[2] || "FS")], lag_days: lag });
+  }
+  return { links, problems };
+}