projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/merge.ts

@@ -0,0 +1,260 @@
+/**
+ * Merging duplicate work items (Spec §1.4; CKC-06 AC-28; subagent/DECISIONS.md E64, E65). Deterministic; no model.
+ *
+ * The main job merges, at the end of its round, work items that turned out to be one unit of work. The merged one
+ * leaves the work items: its sources, facts and relations move to the one kept, everything that named it names the
+ * kept one, and a merge record keeps what it was and points to the one kept. So the list, the graph and every pack —
+ * all read from the work items — show it once, and its id still resolves to the one kept.
+ *
+ * It is not written as `Replaced`. `Replaced` is the history of something superseded, struck through and pointing to
+ * its successor; a duplicate is the same work written twice, and marking it `Replaced` would blur the one signal the
+ * owner reads for what was given up.
+ */
+import type { ItemRef, MergeRecord, ObjectJudgement, PropagationEntry, WorkThread } from '../model/types.ts';
+import { stableId } from '../model/ids.ts';
+import type { ProjectStore, TraceInfo } from '../store/project-store.ts';
+import { sameItem } from './adjustment.ts';
+import { isNumberShaped } from './numbers-check.ts';
+
+const now = () => new Date().toISOString();
+const unique = <T>(list: readonly T[]): T[] => [...new Set(list)];
+/** `first` wins on a shared key; what only `more` has is added after it. */
+const byKey = <T>(first: readonly T[], more: readonly T[], key: (x: T) => string): T[] => {
+  const out = new Map(first.map((x) => [key(x), x]));
+  for (const x of more) if (!out.has(key(x))) out.set(key(x), x);
+  return [...out.values()];
+};
+const unionRefs = <T extends ItemRef>(a: readonly T[], b: readonly T[]): T[] => [...a, ...b.filter((x) => !a.some((y) => sameItem(x, y)))];
+
+/** The merge record that took this id out of the work items, or null. */
+export function mergeOf(store: ProjectStore, id: string): MergeRecord | null {
+  return store.merges.find((m) => m.mergedId === id) ?? null;
+}
+
+/**
+ * The id that stands for this one now: itself, or the work item it was merged into — following a later merge of that
+ * one too. Every tool that takes a work item id reads it through this, so an id a job still remembers reaches the
+ * kept work item instead of bringing the duplicate back.
+ */
+export function resolveMergedId(store: ProjectStore, id: string): string {
+  let current = id;
+  const seen = new Set<string>();
+  for (;;) {
+    if (seen.has(current)) return current;
+    seen.add(current);
+    const m = mergeOf(store, current);
+    if (!m) {
+      // CJ: a project number (`CKC-07`, `AP`) names the one work item that carries it, where no asset has it as its id —
+      // a work item's number lives in its ids, and its id is the program's.
+      const up = current.trim().toUpperCase();
+      if (!store.threads.has(current) && !store.reference.has(current) && isNumberShaped(up)) {
+        const carriers = store.threads.filter((t) => t.ids.some((x) => x.trim().toUpperCase() === up));
+        if (carriers.length === 1 && !seen.has(carriers[0]!.id)) { current = carriers[0]!.id; continue; }
+      }
+      return current;
+    }
+    current = m.keptId;
+  }
+}
+
+/** Why this merge cannot be done, or null. Every id is checked before anything is written. */
+export function mergeRefusal(store: ProjectStore, keepId: string, mergeIds: readonly string[], reason: string): string | null {
+  if (!reason.trim()) return 'Say why these are one unit of work (reason): the same number in the project’s index, the same task named in a receipt or a hand-over. The merge record keeps it, so the merge can be checked and undone by hand if it was wrong.';
+  const kept = resolveMergedId(store, keepId);
+  if (!store.threads.has(kept)) return `${keepId} is not a work item in the assets, so there is nothing to keep. Give the id of the work item that stays (pk_read_assets kind thread lists them).`;
+  if (mergeIds.length === 0) return 'Name the duplicate work item(s) to merge into the one kept (mergeIds).';
+  for (const id of mergeIds) {
+    // The kept id was itself merged into this one earlier: merging this one into it would go round in a circle.
+    if (kept !== keepId && id === kept) return `${keepId} was merged into ${id} earlier, so merging ${id} into ${keepId} would make a circle. ${id} is the work item that stays; merge into it instead.`;
+    if (id === keepId || id === kept) return `A work item is not merged into itself: ${id} is the one being kept. Name the duplicate(s) in mergeIds.`;
+    const target = resolveMergedId(store, id);
+    if (target !== id) {
+      return target === kept
+        ? `${id} is already merged into ${kept}; its id already reaches ${kept}, and a second merge would add nothing.`
+        : `${id} was merged into ${target} earlier. If ${target} is the same unit of work as ${kept}, merge ${target} into ${kept}.`;
+    }
+    if (!store.threads.has(id)) return `${id} is not a work item in the assets. Merging is for work items that turned out to be one unit of work.`;
+  }
+  return null;
+}
+
+export interface MergeInput {
+  readonly projectId: string;
+  readonly keepId: string;
+  readonly mergeIds: readonly string[];
+  readonly reason: string;
+  readonly sourceIds: readonly string[];
+  readonly jobId: string | null;
+  readonly roundId: string | null;
+}
+export interface MergeOutcome {
+  readonly keptId: string;
+  readonly merged: readonly string[];
+  /** How many records of each kind now name the kept work item instead of a merged one. */
+  readonly moved: Readonly<Record<string, number>>;
+}
+
+/** The kept work item with what the merged one brings: its numbers, facts, fact records, what it serves and needs. */
+function combine(kept: WorkThread, merged: WorkThread, at: string): WorkThread {
+  return {
+    ...kept,
+    ids: unique([...kept.ids, ...merged.ids]),
+    doing: kept.doing || merged.doing,
+    changed: kept.changed || merged.changed,
+    results: kept.results || merged.results,
+    unresolved: kept.unresolved || merged.unresolved,
+    doneMeans: kept.doneMeans || merged.doneMeans || '',
+    acceptanceMeans: kept.acceptanceMeans || merged.acceptanceMeans || '',
+    acceptance: kept.acceptance || merged.acceptance || '',
+    executionFacts: byKey(kept.executionFacts, merged.executionFacts, (s) => s.text),
+    qcFacts: byKey(kept.qcFacts, merged.qcFacts, (s) => s.text),
+    factRecordIds: unique([...kept.factRecordIds, ...merged.factRecordIds]),
+    serves: byKey(kept.serves, merged.serves, (s) => s.referenceId),
+    dependsOn: byKey(kept.dependsOn, merged.dependsOn, (d) => d.threadId).filter((d) => d.threadId !== kept.id && d.threadId !== merged.id),
+    pendingSourceIds: unique([...kept.pendingSourceIds, ...merged.pendingSourceIds]),
+    validityByRuleId: kept.validityByRuleId ?? merged.validityByRuleId ?? null,
+    progressByRuleId: kept.progressByRuleId ?? merged.progressByRuleId ?? null,
+    updatedAt: at,
+  };
+}
+
+/** One object's entry in a change record, with the merged one's folded in: behind if either was behind. */
+function foldEntry(mine: PropagationEntry, theirs: PropagationEntry): PropagationEntry {
+  const behind = [mine, theirs].find((p) => p.state === 'Still on old understanding');
+  return {
+    ...mine,
+    state: behind ? behind.state : mine.state,
+    sourceOrReason: unique([mine.sourceOrReason, theirs.sourceOrReason].filter((x) => x.trim())).join(' · '),
+    // No `itemIds` means the whole record reached the object, so the fold is the whole record too.
+    ...(mine.itemIds && theirs.itemIds ? { itemIds: unique([...mine.itemIds, ...theirs.itemIds]) } : { itemIds: undefined }),
+  };
+}
+
+/** Every record that names `from` names `to` instead. Records of what happened (jobs, contexts, round results) stay. */
+function repoint(store: ProjectStore, from: string, to: string, moved: Record<string, number>, trace: TraceInfo): void {
+  const swap = (id: string) => (id === from ? to : id);
+  const count = (kind: string) => { moved[kind] = (moved[kind] ?? 0) + 1; };
+
+  for (const t of store.threads.all()) {
+    if (t.id === from || !t.dependsOn.some((d) => d.threadId === from)) continue;
+    const dependsOn = byKey(t.dependsOn.map((d) => ({ ...d, threadId: swap(d.threadId) })), [], (d) => d.threadId).filter((d) => d.threadId !== t.id);
+    store.threads.put({ ...t, dependsOn }, trace);
+    count('workItems');
+  }
+  for (const a of store.areas.all()) {
+    if (!a.contributions.some((c) => c.threadId === from)) continue;
+    store.areas.put({ ...a, contributions: byKey(a.contributions.map((c) => ({ ...c, threadId: swap(c.threadId) })), [], (c) => c.threadId) }, trace);
+    count('areas');
+  }
+  for (const r of store.relations.all()) {
+    if (r.from !== from && r.to !== from) continue;
+    const f = swap(r.from);
+    const t = swap(r.to);
+    store.relations.remove(r.id, trace);
+    count('relations');
+    // The two duplicates were related to each other; one work item is not related to itself.
+    if (f === t) continue;
+    const id = stableId('rel', r.type, f, t);
+    const existing = store.relations.get(id);
+    if (existing) {
+      store.relations.put({ ...existing, evidence: {
+        sourceIds: unique([...existing.evidence.sourceIds, ...r.evidence.sourceIds]),
+        factRecordIds: unique([...existing.evidence.factRecordIds, ...r.evidence.factRecordIds]),
+        factsSoFar: existing.evidence.factsSoFar || r.evidence.factsSoFar,
+      } }, trace);
+    } else {
+      store.relations.put({ ...r, id, from: f, to: t }, trace);
+    }
+  }
+  store.nodes.remove(from, trace);
+  for (const n of store.nodes.all()) if (n.parentWorkId === from) store.nodes.put({ ...n, parentWorkId: to });
+  for (const m of store.marks.all()) {
+    if (m.targetId !== from) continue;
+    store.marks.remove(m.id, trace);
+    count('marks');
+    // One mark per kind and object (as pk_write_mark keeps them): the same doubt on both becomes one, with both clues.
+    const id = stableId('mark', m.kind, to);
+    const existing = store.marks.get(id);
+    if (!existing || (existing.closed && !m.closed)) store.marks.put({ ...m, id, targetId: to }, trace);
+    else if (!existing.closed && !m.closed) {
+      store.marks.put({ ...existing, clue: existing.clue === m.clue ? existing.clue : `${existing.clue} · ${m.clue}`, clueSourceIds: unique([...existing.clueSourceIds, ...m.clueSourceIds]) }, trace);
+    }
+  }
+  for (const n of store.notes.all()) {
+    if (!n.mount.ids.includes(from)) continue;
+    store.notes.put({ ...n, mount: { ...n.mount, ids: unique(n.mount.ids.map(swap)) } }, trace);
+    count('notes');
+  }
+  for (const c of store.changes.all()) {
+    const touches = c.affects.includes(from) || (c.items ?? []).some((i) => i.affects.includes(from))
+      || c.propagation.some((p) => p.nodeId === from) || (c.notJudged ?? []).some((e) => e.nodeId === from);
+    if (!touches) continue;
+    const items = c.items?.map((i) => ({ ...i, affects: unique(i.affects.map(swap)) }));
+    const affects = unique(c.affects.map(swap));
+    const mine = c.propagation.find((p) => p.nodeId === to);
+    const theirs = c.propagation.find((p) => p.nodeId === from);
+    let propagation = c.propagation.filter((p) => p.nodeId !== from && p.nodeId !== to);
+    const folded = theirs ? (mine ? foldEntry(mine, theirs) : { ...theirs, nodeId: to }) : mine;
+    // A subject is never downstream of its own item (§1.8): what reached the kept one through an item that now changes
+    // it directly is dropped.
+    if (folded) {
+      const subjectOf = new Set((items ?? []).filter((i) => i.affects.includes(to)).map((i) => i.id));
+      const still = folded.itemIds ? folded.itemIds.filter((id) => !subjectOf.has(id)) : folded.itemIds;
+      const whole = !folded.itemIds && affects.includes(to);
+      if (!whole && (!still || still.length > 0)) propagation = [...propagation, still ? { ...folded, itemIds: still } : folded];
+    }
+    const notJudged = c.notJudged ? byKey(c.notJudged.map((e) => ({ ...e, nodeId: swap(e.nodeId) })), [], (e) => e.nodeId) : undefined;
+    store.changes.put({ ...c, affects, propagation, ...(items ? { items } : {}), ...(notJudged ? { notJudged } : {}) }, trace);
+    count('changes');
+  }
+  for (const j of store.propagation.all()) {
+    if (j.nodeId !== from) continue;
+    store.propagation.remove(j.id, trace);
+    count('judgements');
+    const id = `${j.roundId}:${to}`;
+    const k = store.propagation.get(id);
+    if (!k) { store.propagation.put({ ...j, id, nodeId: to }, trace); continue; }
+    // The kept one's judgement of that round takes in what the merged one still lacked, and lacking wins.
+    const lacks = unionRefs(k.lacks, j.lacks);
+    const closed = unionRefs(k.closed, j.closed).filter((c) => !lacks.some((l) => sameItem(l, c)));
+    const followed = unionRefs(k.followed, j.followed).filter((f) => ![...lacks, ...closed].some((x) => sameItem(x, f)));
+    const judgement: ObjectJudgement = {
+      ...k, covers: unionRefs(k.covers, j.covers), lacks, closed, followed,
+      state: lacks.length ? 'Still on old understanding' : k.state,
+      sourceOrReason: unique([k.sourceOrReason, j.sourceOrReason].filter((x) => x.trim())).join(' · '),
+    };
+    store.propagation.put(judgement, trace);
+  }
+  for (const r of store.requests.all()) {
+    if (!r.impact.includes(from) && !(r.lines ?? []).some((l) => l.nodeId === from)) continue;
+    store.requests.put({ ...r, impact: unique(r.impact.map(swap)), ...(r.lines ? { lines: r.lines.map((l) => ({ ...l, nodeId: swap(l.nodeId) })) } : {}) }, trace);
+    count('requests');
+  }
+  for (const ref of store.reference.all()) {
+    if (!ref.carryOut || !ref.carryOut.workIds.includes(from)) continue;
+    store.reference.put({ ...ref, carryOut: { ...ref.carryOut, workIds: unique(ref.carryOut.workIds.map(swap)) } }, trace);
+    count('decisions');
+  }
+}
+
+/** Merge the named duplicates into the work item kept. Call `mergeRefusal` first; this assumes the ids are valid. */
+export function mergeWorkItems(store: ProjectStore, input: MergeInput): MergeOutcome {
+  const keptId = resolveMergedId(store, input.keepId);
+  const moved: Record<string, number> = {};
+  const merged: string[] = [];
+  for (const mergedId of unique(input.mergeIds)) {
+    const at = now();
+    const kept = store.threads.get(keptId)!;
+    const duplicate = store.threads.get(mergedId)!;
+    const trace: TraceInfo = { jobId: input.jobId, basisSourceIds: input.sourceIds, summary: `Merged ${mergedId} (${duplicate.title}) into ${keptId} (${kept.title}): ${input.reason}` };
+    store.threads.put(combine(kept, duplicate, at), trace);
+    repoint(store, mergedId, keptId, moved, trace);
+    store.threads.remove(mergedId, trace);
+    store.merges.put({
+      id: stableId('merge', input.projectId, mergedId), projectId: input.projectId, kind: 'thread', mergedId, keptId,
+      reason: input.reason, sourceIds: [...input.sourceIds], merged: duplicate, at, jobId: input.jobId, roundId: input.roundId,
+    }, trace);
+    merged.push(mergedId);
+  }
+  return { keptId, merged, moved };
+}

package/src/keeper/note-origin.ts

@@ -0,0 +1,56 @@
+/**
+ * How a note came about (Spec §4.1, §4.2; D47 supplement, D56 item 5): `Product re-look`, `Change follow-up`,
+ * `Investigation`, `Owner question`, `Organizing` (written while material was being organized) or `Takeover` (written
+ * while the project was being taken over), named from the work that wrote it. A note from a change follow-up also names
+ * the changes it is about, so the owner can tell at a glance which reminders it brought (§6.2).
+ *
+ * By the clerk method (Spec v3.0 §3.3) a note is written by a step of a round — the synthesis, which is the round's product
+ * re-look, or the spot-check — and the round says how it came about: a note of a Follow up round came from following the
+ * changes up; one of the first usable round or a deepening, from taking the project over. The D59 scopes this used to
+ * read (`follow-up`, `change-follow-up`, `round`, `frame`, `takeover`) belong to jobs nothing creates any more.
+ */
+import type { KeeperJob, NoteCameFrom } from '../model/types.ts';
+import type { NoteOrigin } from '../model/vocab.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { clerkRoundOfJob } from './roles.ts';
+
+/** How a note came about from the kind of work outside a round: a re-look, an investigation, the owner's conversation. */
+export function originOfJob(job: Pick<KeeperJob, 'kind' | 'scope'> | undefined | null): NoteOrigin | null {
+  if (!job) return null;
+  if (job.kind === 'Product re-look') return 'Product re-look';
+  if (job.kind === 'Investigation') return 'Investigation';
+  if (job.kind === 'Answering' || job.kind === 'Your request') return 'Owner question';
+  if (job.kind === 'Organizing') return 'Organizing';
+  return null;
+}
+
+/**
+ * The changes a follow-up note is about: of the changes the round took up (every change when that is not known), those
+ * whose downstream includes the object the note is mounted on.
+ */
+export function followUpChangesFor(store: ProjectStore, mountIds: readonly string[], candidates: readonly string[] | null): string[] {
+  const pool = candidates ? candidates.flatMap((id) => store.changes.get(id) ?? []) : store.changes.all();
+  return pool.filter((c) => c.propagation.some((p) => mountIds.includes(p.nodeId)) || c.affects.some((id) => mountIds.includes(id))).map((c) => c.id);
+}
+
+/** The changes a Follow up round took up: those its cross-check judged objects against, in the round's record (§5.5). */
+function changesOfFollowUp(store: ProjectStore, recordId: string | null): string[] | null {
+  if (!recordId) return null;
+  const ids = store.propagation.filter((j) => j.roundId === recordId).flatMap((j) => [...j.covers, ...j.followed, ...j.lacks].map((i) => i.changeId));
+  return ids.length ? [...new Set(ids)] : null;
+}
+
+export function cameFromFor(
+  store: ProjectStore, job: KeeperJob | undefined | null, mountIds: readonly string[],
+  opts: { readonly given?: readonly string[]; readonly candidates?: readonly string[] | null } = {},
+): NoteCameFrom {
+  const round = job ? clerkRoundOfJob(store, job) : null;
+  const kind: NoteOrigin | null = round ? (round.kind === 'Follow up' ? 'Change follow-up' : 'Takeover') : originOfJob(job);
+  let changeIds: string[] = [];
+  if (kind === 'Change follow-up') {
+    const given = (opts.given ?? []).filter((id) => store.changes.has(id));
+    const known = opts.candidates ?? changesOfFollowUp(store, round?.followUpRoundId ?? null);
+    changeIds = given.length ? given : followUpChangesFor(store, mountIds, known);
+  }
+  return { kind, jobKind: job?.kind ?? null, jobId: job?.id ?? null, changeIds };
+}

package/src/keeper/numbers-check.ts

@@ -0,0 +1,102 @@
+/**
+ * What the writers check against the ledger's numbering (CJ; Spec §1.16 row 4; CKC-23 AC-21, CKC-24): a work item's ids
+ * are numbers the project defines, and not another object's number; an item named by its number alone is named as its
+ * document names it. Without a ledger (it is built by the round's first step), or a ledger that recognised no numbering,
+ * nothing is checked.
+ */
+import { Ledger } from '../ledger/index.ts';
+import { familyOf } from '../ledger/numbering.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { pathKey } from '../util/paths.ts';
+import { entryTitle, isNumberOnly } from './organize/entries.ts';
+
+/** A project number as written (`CKC-22`, `D99`, `AP`, `CK-M2`, `SOL-PI-0871`): the shapes the ledger and the writers read. */
+const NUMBER_SHAPE = /^(?:[A-Z]{1,6}(?:-[A-Z]{1,4})?-?\d{1,4}(?:\.\d{1,3})*|[A-Z]{2})$/;
+export const isNumberShaped = (s: string): boolean => NUMBER_SHAPE.test(s.trim()) && !/^V\d/.test(s.trim());
+
+/** Reference categories whose numbers are never a work item's own: a decision's, a boundary's, a goal's, a module's. */
+const NOT_A_TICKET: ReadonlySet<string> = new Set(['Decision', 'Boundary', "Owner's words", 'Product', 'Goal', 'Area', 'Design']);
+
+/** Run with the project's ledger when it has one that recognised a numbering; the ledger is closed after. */
+export function withNumbering<T>(store: ProjectStore, fn: (ledger: Ledger) => T, otherwise: T): T {
+  let ledger: Ledger | null = null;
+  try { ledger = Ledger.openDir(store.dir); } catch { ledger = null; }
+  if (!ledger) return otherwise;
+  try {
+    const rules = ledger.db.prepare('SELECT count(*) c FROM num_rules').get() as { c: number } | undefined;
+    if (!rules || rules.c === 0) return otherwise;
+    return fn(ledger);
+  } catch {
+    return otherwise;
+  } finally {
+    ledger.close();
+  }
+}
+
+/** The documents the layer map marks as current decision records, as `repo\0path` keys. */
+function decisionRecordKeys(store: ProjectStore): Set<string> {
+  return new Set(store.layers.filter((l) => l.layer === 'Decision record').map((l) => `${pathKey(l.repo ?? '')}\u0000${l.path.replace(/\\/g, '/').replace(/\/+$/, '')}`));
+}
+
+/**
+ * Whose number this is when it is not a work item's: a decision, boundary, goal or module that carries it, or the decision
+ * record that alone defines it (`D99`, `E145`). Null when it may be a work item's own number.
+ */
+export function otherObjectOf(store: ProjectStore, ledger: Ledger | null, num: string): string | null {
+  const n = num.trim().toUpperCase();
+  const item = store.reference.find((r) => NOT_A_TICKET.has(r.category) && r.ids.some((x) => x.trim().toUpperCase() === n));
+  if (item) return `the ${item.category} ${item.ids[0] ?? ''} “${item.name.slice(0, 60)}”`;
+  if (!ledger) return null;
+  const records = decisionRecordKeys(store);
+  if (!records.size) return null;
+  const places = ledger.definitionPlaces(n);
+  if (!places.length) return null;
+  const repos = new Map(ledger.repos().map((r) => [r.id, r.path]));
+  const inRecord = (d: { repo: string | null; path: string }) => [...records].some((k) => {
+    const [repo, path] = k.split('\u0000') as [string, string];
+    return pathKey(repos.get(d.repo ?? '') ?? '') === repo && (d.path === path || d.path.startsWith(`${path}/`));
+  });
+  if (places.every(inRecord)) return `a decision the decision record ${places[0]!.path} defines`;
+  return null;
+}
+
+/**
+ * The ids the project does not have as its numbers: of a numbering the ledger recognised (or two capitals), one it never
+ * defines; of any other shape, one no document, commit or session the ledger read writes at all (`KIMI-P1`,
+ * `SOL-PI-0871`: a label of the writer's own).
+ */
+export function undefinedNumbers(ledger: Ledger, ids: readonly string[]): string[] {
+  const shaped = ids.map((i) => i.trim()).filter((i) => isNumberShaped(i.toUpperCase()));
+  if (!shaped.length) return [];
+  const defined = ledger.definedNumbers(shaped.map((s) => s.toUpperCase()));
+  const rules = new Set((ledger.db.prepare('SELECT rule FROM num_rules').all() as { rule: string }[]).map((r) => r.rule));
+  return shaped.filter((s) => {
+    const up = s.toUpperCase();
+    if (defined.has(up)) return false;
+    const family = familyOf(up);
+    if (family && (family.shape === 'two-letters' || rules.has(family.family))) return true;
+    return !ledger.hasToken(up);
+  });
+}
+
+/**
+ * Why a name that is the number alone is refused, or null (CKC-23 AC-21: named as the document names it): the line that
+ * defines the number — in a document the item cites, else anywhere current — gives a title besides the number.
+ */
+export function numberOnlyRefusal(store: ProjectStore, ledger: Ledger, name: string, sourceIds: readonly string[], what: string): string | null {
+  if (!isNumberOnly(name)) return null;
+  const num = name.replace(/[^A-Za-z0-9-]/g, '').toUpperCase();
+  if (!familyOf(num) && !isNumberShaped(num)) return null;
+  const defs = ledger.definitionsOf(num).filter((d) => d.position === 'heading' || d.position === 'bold entry' || d.position === 'table first column');
+  if (!defs.length) return null;
+  const cited = new Set(sourceIds.map((id) => store.sources.get(id)).flatMap((s) => (s && s.anchor.kind === 'file' ? [pathKey(s.anchor.path)] : [])));
+  const repos = new Map(ledger.repos().map((r) => [r.id, r.path]));
+  const absKey = (d: { repo: string | null; path: string }) => pathKey(`${repos.get(d.repo ?? '') ?? ''}/${d.path}`);
+  const ordered = [...defs.filter((d) => cited.has(absKey(d))), ...defs.filter((d) => !cited.has(absKey(d)))];
+  for (const d of ordered) {
+    const t = entryTitle(d.context, num, d.position as 'heading');
+    if (!t.title) continue;
+    return `${what} “${name}” is its number alone, and the line that defines ${num} (${d.path}:${d.line}) gives its title: “${d.context.slice(0, 160)}”. Name it by its number and its title as written, e.g. “${t.name.slice(0, 120)}” (named as the document names it). Nothing was written.`;
+  }
+  return null;
+}

package/src/keeper/open-in-pi.ts

@@ -0,0 +1,57 @@
+/**
+ * Opening pi's own interface in a terminal, for `Open in pi` on a system that is not Windows (runtime.ts keeps the
+ * Windows way: a console window started with `start`).
+ *
+ * macOS: a small script is written to the temporary directory and handed to Terminal (`open -a Terminal <script>`),
+ * which runs a `.command` file in a new window. That needs no permission from the owner; telling Terminal what to do
+ * through AppleScript would need macOS's leave for one program to control another, which can be refused without a
+ * word. What is reported is what happened: Terminal was asked and `open` said yes, or it was not and why.
+ *
+ * Anywhere else there is no one terminal to open, so nothing is started and the answer is the command to run. (Started
+ * with no terminal at all, as it used to be, pi showed nothing and the workbench said it had been opened.)
+ */
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** A word for `sh`, whatever it holds: a space, a quote, a `$`. */
+export const shellWord = (text: string): string => `'${text.replaceAll("'", "'\\''")}'`;
+
+/** The line that opens pi in a project's directory, resuming a session when one is given: what the script runs, and what the owner is shown to run. */
+export function piCommandLine(cwd: string, sessionFile: string | null, pi = 'pi'): string {
+  return `cd ${shellWord(cwd)} && ${pi === 'pi' ? 'pi' : shellWord(pi)}${sessionFile ? ` --session ${shellWord(sessionFile)}` : ''}`;
+}
+
+/** The script Terminal runs: go to the project, then become pi (so closing pi ends the window's process). */
+export function openInPiScript(cwd: string, sessionFile: string | null, pi = 'pi'): string {
+  return `#!/bin/sh\ncd ${shellWord(cwd)} || exit 1\nexec ${pi === 'pi' ? 'pi' : shellWord(pi)}${sessionFile ? ` --session ${shellWord(sessionFile)}` : ''}\n`;
+}
+
+const runnable = (path: string): boolean => { try { accessSync(path, constants.X_OK); return true; } catch { return false; } };
+
+/** pi's command: the one on the PATH, else the one installed with ProjectKeeper; null when there is neither. */
+export function findPi(pathVariable: string = process.env.PATH ?? '', installed: string = fileURLToPath(new URL('../../node_modules/.bin/pi', import.meta.url))): string | null {
+  for (const dir of pathVariable.split(delimiter)) if (dir && runnable(join(dir, 'pi'))) return 'pi';
+  return runnable(installed) ? installed : null;
+}
+
+export function openInPiOffWindows(cwd: string, sessionFile: string | null, platform: NodeJS.Platform = process.platform): { message: string } {
+  const yourself = (pi: string) => `run it yourself in a terminal: ${piCommandLine(cwd, sessionFile, pi)}`;
+  if (platform !== 'darwin') return { message: `Opening a terminal is not available on this system; ${yourself('pi')}` };
+  const pi = findPi();
+  if (!pi) return { message: `pi’s command was not found, neither on the PATH nor installed with ProjectKeeper, so nothing was opened; once it is installed, ${yourself('pi')}` };
+  try {
+    const script = join(mkdtempSync(join(tmpdir(), 'pk-open-in-pi-')), 'open-in-pi.command');
+    writeFileSync(script, openInPiScript(cwd, sessionFile, pi), { mode: 0o700 });
+    const asked = spawnSync('open', ['-a', 'Terminal', script], { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] });
+    if (asked.error || asked.status !== 0) {
+      const why = asked.error?.message ?? ((asked.stderr || asked.stdout || '').trim().split('\n')[0] || `open ended with ${asked.status ?? asked.signal}`);
+      return { message: `Terminal could not be opened (${why}), so pi was not started; ${yourself(pi)}` };
+    }
+    return { message: `Asked Terminal to open pi in ${cwd}${sessionFile ? ' with the Keeper session' : ''}` };
+  } catch (e) {
+    return { message: `Could not open pi: ${(e as Error).message}; ${yourself(pi)}` };
+  }
+}