projectkeeper 0.0.0-stage → 1.0.0

package/src/process/plan.ts

@@ -0,0 +1,276 @@
+/**
+ * A plan's execution shape (Spec v3.0 §6.3 执行形状, D72; CKC-24 AC-2): its batches as the plan wrote them, the order they
+ * actually ran in — by when their work was dispatched and delivered — which ran in parallel, the merge commit of each,
+ * and where the actual order differs from the planned one, in one sentence. As the orchestrator wrote it and as git shows
+ * it; ProjectKeeper schedules nothing.
+ *
+ * The plan's own batches are read from its section: numbered items (`1. **地基**：…`), or lines and headings naming a batch
+ * (`批次 3`, `Batch 3`), with the parallel it states (`和 3、4 并行`, `in parallel with 3`). Which batch a piece of work is
+ * comes from its own arrangement (`批次 5b`, `batch 6 of 7`; placement.ts).
+ */
+import type { Occurred } from '../model/k-types.ts';
+import type { PlanShapeView } from '../model/views-k.ts';
+import type { WorkThread } from '../model/types.ts';
+import { splitMarkdown } from '../sources/files.ts';
+import type { Analysis } from './analysis.ts';
+import { batchOf, planDocument, workOfPlan } from './placement.ts';
+import type { Unit } from './units.ts';
+import type { WorkProcess } from './work.ts';
+
+export interface PlannedBatch {
+  readonly label: string;
+  readonly name: string;
+  readonly text: string;
+  /** Other batches the plan says this one runs in parallel with. */
+  readonly parallelWith: readonly string[];
+}
+
+/** The batches a plan section names, in its order. */
+export function plannedBatches(text: string): PlannedBatch[] {
+  const out: PlannedBatch[] = [];
+  let inFence = false;
+  for (const raw of text.split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(raw)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const item = /^\s{0,3}(\d{1,2})[.)、]\s+(.+)$/.exec(raw);
+    const named = /^\s{0,3}(?:#{1,6}\s+|[-*+]\s+)?(?:\*\*)?(?:批次|第)\s*(\d{1,2})\s*批?\s*[:：·—-]?\s*(.*)$/.exec(raw) ?? /^\s{0,3}(?:#{1,6}\s+|[-*+]\s+)?(?:\*\*)?batch\s*(\d{1,2})\b\s*[:：·—-]?\s*(.*)$/i.exec(raw);
+    const m = item ?? named;
+    if (!m) continue;
+    const label = m[1]!;
+    if (out.some((b) => b.label === label)) continue;
+    const body = m[2]!.trim();
+    const bold = /\*\*([^*]+)\*\*/.exec(body)?.[1];
+    const name = (bold ?? body).replace(/[：:（(。].*$/, '').replace(/[*_`]/g, '').trim() || body.slice(0, 30);
+    const hint = /(?:和|与|跟|同)\s*((?:\d{1,2}\s*[、,，和与及]\s*)*\d{1,2})\s*(?:同时|一起)?\s*并行|(?:in )?parallel with\s+(?:batch(?:es)?\s*)?((?:\d{1,2}\s*(?:,|and|&)\s*)*\d{1,2})/i.exec(body);
+    const parallelWith = hint ? [...(hint[1] ?? hint[2] ?? '').matchAll(/\d{1,2}/g)].map((x) => x[0]) : [];
+    out.push({ label, name, text: body, parallelWith });
+  }
+  return out;
+}
+
+/** The text of a document's section (the heading path) in a version's text; the whole text when no section is given. */
+export function sectionText(text: string, headingPath: readonly string[]): string {
+  if (headingPath.length === 0) return text;
+  const want = headingPath.join(' › ');
+  const sections = splitMarkdown(text);
+  const own = sections.filter((s) => s.headingPath.join(' › ') === want || s.headingPath.join(' › ').startsWith(`${want} › `));
+  return own.length ? own.map((s) => s.text).join('\n') : text;
+}
+
+interface WorkRun {
+  readonly thread: WorkThread;
+  readonly process: WorkProcess;
+  readonly units: readonly Unit[];
+  readonly batch: string | null;
+  readonly part: string | null;
+  readonly start: { readonly ms: number; readonly occurred: Occurred } | null;
+  readonly end: number | null;
+}
+
+/** One time a plan's batch ran: all of it, or — when its work ran at different times — one part of it. */
+interface ActualBatch {
+  readonly label: string;
+  readonly runs: readonly WorkRun[];
+  /** Work of the batch not started yet (shown with its first part). */
+  readonly waiting: readonly WorkRun[];
+  readonly start: number;
+  readonly end: number;
+  readonly startOccurred: Occurred | null;
+  /** Which part of the batch this is (1-based), and of how many. */
+  readonly part: number;
+  readonly parts: number;
+}
+
+const joinList = (xs: readonly string[]): string => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`);
+const byLabelOrder = (x: string, y: string): number => x.localeCompare(y, 'en', { numeric: true });
+
+export function planShapeOf(a: Analysis, planId: string): PlanShapeView | null {
+  const { store, facts, index } = a;
+  const plan = store.reference.get(planId);
+  if (!plan || plan.category !== 'Plan') return null;
+  const doc = planDocument(store, facts, plan);
+  const version = doc?.current ?? doc?.first ?? null;
+  const text = version ? facts.textOf(version.id) : null;
+  const planned = text ? plannedBatches(sectionText(text, doc?.headingPath ?? [])) : [];
+  // The work of the plan, each with its batch and when it ran (dispatch or first commit, to its last merge, fix or check).
+  const runs: WorkRun[] = workOfPlan(store, planId).map((thread) => {
+    const process = a.process(thread.id)!;
+    const units = process.own.map((n) => index.units.get(n)!).filter(Boolean);
+    const b = units.map(batchOf).find((x) => x !== null) ?? null;
+    const d = process.delivery;
+    const start = d.dispatched ? { ms: d.dispatched.ms, occurred: d.dispatched.occurred } : d.codeCommits[0] ? { ms: d.codeCommits[0].ms, occurred: d.codeCommits[0].occurred } : null;
+    const endCandidates = [...d.merges.map((m) => m.ms), d.deliveredAt?.ms ?? 0, ...process.checks.map((c) => c.ms), ...process.fixes.flatMap((f) => [f.ms, ...f.merges.map((m) => m.ms)])].filter((x) => x > 0);
+    const end = endCandidates.length ? Math.max(...endCandidates) : null;
+    return { thread, process, units, batch: b?.batch ?? null, part: b?.part ?? null, start, end };
+  });
+  // Batches as they ran: by the plan's batch number (work with no batch of its own is a batch of its own); a batch whose
+  // work ran at different times is split into the parts that ran together.
+  const byLabel = new Map<string, WorkRun[]>();
+  for (const r of runs) {
+    const label = r.batch ?? r.thread.ids[0] ?? r.thread.id;
+    byLabel.set(label, [...(byLabel.get(label) ?? []), r]);
+  }
+  const actual: ActualBatch[] = [];
+  for (const [label, rs] of byLabel) {
+    const ran = rs.filter((r) => r.start).sort((x, y) => x.start!.ms - y.start!.ms);
+    const waiting = rs.filter((r) => !r.start);
+    const clusters: WorkRun[][] = [];
+    let until = -Infinity;
+    for (const r of ran) {
+      const e = r.end ?? r.start!.ms;
+      const c = clusters[clusters.length - 1];
+      if (c && r.start!.ms < until) { c.push(r); until = Math.max(until, e); }
+      else { clusters.push([r]); until = e; }
+    }
+    if (clusters.length === 0) { actual.push({ label, runs: [], waiting, start: Number.MAX_SAFE_INTEGER, end: 0, startOccurred: null, part: 1, parts: 1 }); continue; }
+    clusters.forEach((c, i) => actual.push({
+      label, runs: c, waiting: i === 0 ? waiting : [], start: c[0]!.start!.ms, end: Math.max(...c.map((r) => r.end ?? r.start!.ms)),
+      startOccurred: c[0]!.start!.occurred, part: i + 1, parts: clusters.length,
+    }));
+  }
+  const started = actual.filter((b) => b.runs.length).sort((x, y) => x.start - y.start || byLabelOrder(x.label, y.label));
+  const notStarted = actual.filter((b) => b.runs.length === 0).sort((x, y) => byLabelOrder(x.label, y.label));
+  // Batches that ran at the same time: one that starts before the ones before it ended joins them.
+  const groups: ActualBatch[][] = [];
+  for (const b of started) {
+    const g = groups[groups.length - 1];
+    if (g && b.start < Math.max(...g.map((x) => x.end))) g.push(b);
+    else groups.push([b]);
+  }
+  const nameOfRun = (b: ActualBatch, r: WorkRun) => (r.part ? `${b.label}${r.part}` : r.thread.ids[0] ?? r.thread.id);
+  const partsOf = (b: ActualBatch): string => {
+    const names = b.runs.map((r) => nameOfRun(b, r));
+    const pieces = b.parts > 1 || b.runs.length > 1 ? [names.join(runsOverlap(b.runs) ? ' ∥ ' : ' → ')] : [];
+    const waiting = b.waiting.map((r) => `${nameOfRun(b, r)} not started`);
+    return pieces.length || waiting.length ? ` (${[...pieces, ...waiting].join('; ')})` : '';
+  };
+  const actualOrder = groups.length
+    ? [...groups.map((g) => (g.length > 1 ? `(${g.map((b) => `${b.label}${partsOf(b)}`).join(' ∥ ')})` : `${g[0]!.label}${partsOf(g[0]!)}`)), ...notStarted.map((b) => `${b.label} (not started)`)].join(' → ')
+    : null;
+  // The planned order, with the parallel the plan states.
+  const plannedGroups: string[][] = [];
+  for (const p of planned) {
+    if (plannedGroups.some((g) => g.includes(p.label))) continue;
+    const mates = new Set([p.label, ...p.parallelWith.filter((x) => planned.some((q) => q.label === x))]);
+    for (const q of planned) if (q.parallelWith.includes(p.label)) mates.add(q.label);
+    plannedGroups.push([...mates].sort(byLabelOrder));
+  }
+  const plannedOrder = plannedGroups.length ? plannedGroups.map((g) => (g.length > 1 ? `(${g.join(' ∥ ')})` : g[0]!)).join(' → ') : null;
+  const differs = differences(plannedGroups, groups, actual, planned, nameOfRun);
+  const nameOf = (label: string) => planned.find((p) => p.label === label)?.name ?? null;
+  const batches: PlanShapeView['batches'] = [...groups.flat(), ...notStarted].map((b) => {
+    const group = groups.find((g) => g.includes(b));
+    const members = [...b.runs, ...b.waiting];
+    // The merge commits that brought the batch in; work committed straight to the trunk has none, and its last commit stands in.
+    const merged = [...new Map(b.runs.flatMap((r) => [...r.process.delivery.merges, ...r.process.fixes.flatMap((f) => f.merges)]).map((m) => [m.hash, m])).values()];
+    const direct = b.runs.flatMap((r) => (r.process.delivery.merges.length ? [] : r.process.delivery.codeCommits.filter((c) => c.fpTrunk).slice(-1)));
+    const merges = [...merged, ...direct].sort((x, y) => x.ms - y.ms);
+    const agents = [...new Set(members.flatMap((r) => r.units.map((u) => u.executor).filter((x): x is string => Boolean(x))))];
+    const worktrees = [...new Set(b.runs.flatMap((r) => r.units.map((u) => (u.fields.worktree ?? u.branches[0] ?? '').split(/[\\/ ]/).filter(Boolean).pop() ?? '').filter(Boolean)))];
+    const name = nameOf(b.label);
+    return {
+      label: `Batch ${b.label}${name ? ` · ${name}` : ''}${b.parts > 1 ? ` (part ${b.part} of ${b.parts})` : ''}`,
+      workIds: members.map((r) => r.thread.id),
+      parallel: (group?.length ?? 1) > 1 || (b.runs.length > 1 && runsOverlap(b.runs)),
+      running: b.runs.some((r) => r.process.execution === 'In progress' && r.process.delivery.dispatched !== null),
+      agent: agents.length ? agents.join(', ') : null,
+      worktree: worktrees.length ? worktrees.join(', ') : null,
+      mergeCommit: merges.length ? merges.map((m) => m.short).join(', ') : null,
+      occurred: b.startOccurred,
+    };
+  });
+  return { planId, actualOrder, plannedOrder, differs, batches, dependsOn: dependenciesOf(a, runs) };
+}
+
+function runsOverlap(runs: readonly WorkRun[]): boolean {
+  const spans = runs.filter((r) => r.start).map((r) => ({ s: r.start!.ms, e: r.end ?? r.start!.ms })).sort((x, y) => x.s - y.s);
+  for (let i = 1; i < spans.length; i++) if (spans[i]!.s < Math.max(...spans.slice(0, i).map((x) => x.e))) return true;
+  return false;
+}
+
+/** Where the actual order differs from the plan, in one sentence; null when it does not (or the plan names no batches). */
+function differences(
+  plannedGroups: readonly string[][], groups: readonly ActualBatch[][], actual: readonly ActualBatch[], planned: readonly PlannedBatch[],
+  nameOfRun: (b: ActualBatch, r: WorkRun) => string,
+): string | null {
+  if (plannedGroups.length === 0 || groups.length === 0) return null;
+  const rank = new Map<string, number>();
+  plannedGroups.forEach((g, i) => { for (const l of g) rank.set(l, i); });
+  const sequence = groups.flat().filter((b) => rank.has(b.label));
+  const said = (b: ActualBatch) => (b.parts > 1 ? `${b.runs.map((r) => nameOfRun(b, r)).join(', ')} of batch ${b.label}` : `batch ${b.label}`);
+  // The batches that keep the planned order are the longest run of non-decreasing planned ranks; the others moved.
+  const n = sequence.length;
+  const len = new Array<number>(n).fill(1);
+  const prev = new Array<number>(n).fill(-1);
+  for (let i = 0; i < n; i++) for (let j = 0; j < i; j++) if (rank.get(sequence[j]!.label)! <= rank.get(sequence[i]!.label)! && len[j]! + 1 > len[i]!) { len[i] = len[j]! + 1; prev[i] = j; }
+  let best = 0;
+  for (let i = 1; i < n; i++) if (len[i]! > len[best]!) best = i;
+  const kept = new Set<number>();
+  for (let i = n ? best : -1; i >= 0; i = prev[i]!) kept.add(i);
+  const parts: string[] = [];
+  const unique = (xs: string[]) => [...new Set(xs)];
+  sequence.forEach((b, i) => {
+    if (kept.has(i)) return;
+    const r = rank.get(b.label)!;
+    // Said against the batches that kept their order.
+    const jumped = unique(sequence.flatMap((x, j) => (j > i && kept.has(j) && rank.get(x.label)! < r ? [x.label] : [])));
+    const after = unique(sequence.flatMap((x, j) => (j < i && kept.has(j) && rank.get(x.label)! > r ? [x.label] : [])));
+    if (jumped.length) parts.push(`${said(b)} ran before batch${jumped.length > 1 ? 'es' : ''} ${joinList(jumped)}`);
+    else if (after.length) parts.push(`${said(b)} ran after batch${after.length > 1 ? 'es' : ''} ${joinList(after)}`);
+  });
+  // A batch the plan wrote as one, run as several pieces of work together, or in parts at different times.
+  for (const b of actual) {
+    if (b.runs.length < 2 || !rank.has(b.label)) continue;
+    const pieces = b.runs.map((r) => nameOfRun(b, r));
+    parts.push(`batch ${b.label} ran as ${b.runs.length === 2 ? 'two halves' : `${b.runs.length} parts`} ${runsOverlap(b.runs) ? 'in parallel' : 'one after the other'} (${pieces.join(', ')})`);
+  }
+  for (const label of unique(actual.filter((b) => b.parts > 1 && b.part === 1).map((b) => b.label))) {
+    const pieces = actual.filter((b) => b.label === label).sort((x, y) => x.part - y.part).map((b) => b.runs.map((r) => nameOfRun(b, r)).join(', '));
+    parts.push(`batch ${label} ran in ${pieces.length} parts at different times (${pieces.join('; then ')})`);
+  }
+  // Parallel the plan stated and the run did not keep, or the other way round.
+  const groupOf = (label: string) => groups.findIndex((g) => g.some((b) => b.label === label && b.part === 1));
+  for (const g of plannedGroups) {
+    if (g.length < 2) continue;
+    const ran = g.map(groupOf).filter((i) => i >= 0);
+    if (ran.length === g.length && new Set(ran).size > 1) parts.push(`batches ${joinList(g)}, planned in parallel, ran one after another`);
+  }
+  for (const grp of groups) {
+    const labels = unique(grp.map((b) => b.label).filter((l) => rank.has(l)));
+    if (labels.length < 2) continue;
+    if (new Set(labels.map((l) => rank.get(l))).size > 1) parts.push(`batches ${joinList(labels)} ran in parallel, planned one after another`);
+  }
+  const missing = planned.filter((p) => !actual.some((b) => b.label === p.label)).map((p) => p.label);
+  if (missing.length) parts.push(`no work item is recorded for batch${missing.length > 1 ? 'es' : ''} ${joinList(missing)}`);
+  return parts.length ? `Execution differs from the plan: ${parts.join('; ')}.` : null;
+}
+
+/** Dependencies between the plan's work: the round's `dependsOn`, and the arrangement's own fields (`upstream`, `blocks`). */
+function dependenciesOf(a: Analysis, runs: readonly WorkRun[]): PlanShapeView['dependsOn'] {
+  const { index } = a;
+  const byNum = new Map<string, string>();
+  for (const t of a.store.threads.all()) for (const n of t.ids) if (!byNum.has(n)) byNum.set(n, t.id);
+  for (const r of runs) for (const n of r.thread.ids) byNum.set(n, r.thread.id);
+  const byBatch = new Map<string, string[]>();
+  for (const r of runs) if (r.batch) byBatch.set(r.batch, [...(byBatch.get(r.batch) ?? []), r.thread.id]);
+  const edges = new Map<string, { from: string; to: string }>();
+  const add = (from: string | undefined, to: string | undefined) => { if (from && to && from !== to) edges.set(`${from}\x1f${to}`, { from, to }); };
+  const unitNames = [...index.units.keys()];
+  const named = (v: string) => unitNames.filter((n) => new RegExp(`(?<![A-Za-z0-9_])${n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_]|-\\d)`).test(v));
+  for (const r of runs) {
+    for (const d of r.thread.dependsOn) if (runs.some((x) => x.thread.id === d.threadId)) add(r.thread.id, d.threadId);
+    for (const u of r.units) {
+      for (const [k, v] of Object.entries(u.fields)) {
+        if (/^(upstream|depends_on|depends|after|blocked_by|requires|prerequisites?)$/i.test(k)) for (const n of named(v)) add(r.thread.id, byNum.get(n));
+        if (/^blocks$/i.test(k)) {
+          for (const n of named(v)) add(byNum.get(n), r.thread.id);
+          // `batches 2 (B runner), 3 (A assembly), 4 (memory rooms)`: every batch number after the word.
+          const after = /(?:batch(?:es)?|批次)([\s\S]*)$/i.exec(v)?.[1] ?? '';
+          for (const b of after.replace(/\([^)]*\)|（[^）]*）/g, ' ').match(/(?<![\d.])\d{1,2}(?![\d.])/g) ?? []) for (const t of byBatch.get(b) ?? []) add(t, r.thread.id);
+        }
+      }
+    }
+  }
+  return [...edges.values()];
+}
+

package/src/process/sendbacks.ts

@@ -0,0 +1,244 @@
+/**
+ * Send-backs (Spec v3.0 §1.18 送回): a relation, not a ticket. `Suggested → Returned → Closed`, recognised from the
+ * ledger at each round; nobody changes a state by hand, and the owner's `No action needed` stays.
+ *
+ * - **Where they come from.** A check that failed (QC, review or walkthrough judged `fail`, `needs repair` …; a check
+ *   still in progress, `incomplete（审核进行中）`, has judged nothing and starts none) and a
+ *   host's review that sent a delivery back (`status: needs-repair`) are send-backs to Work the project itself wrote
+ *   (§1.18 "QC 与走查的判定"); the program records each once, keyed by the ledger entry it started from. The round's
+ *   synthesis suggests the others — from breakpoints, the six things, code anomalies (clerk-tools `pk_suggest_sendback`).
+ * - **`Returned`**: a later task, commit or document version picks it up — a fix whose task names the work or the check
+ *   (by number), a commit or document that cites the send-back's own id (the `Copy for agent` text carries it), a later
+ *   version of the document a send-back to Plan hangs on, or a confirmed link (then `Inferred`).
+ * - **`Closed`**: later evidence shows it fixed — a check after the fix that passed; the fix merged (for a host's review,
+ *   or where the project does not ask for a re-check); the breakpoint it came from put out by evidence; the note or mark
+ *   it came from resolved — always with that evidence.
+ */
+import { linkHolds } from '../model/k-types.ts';
+import type { Basis } from '../model/vocab.ts';
+import type { EvidenceRef, Occurred, SendBack } from '../model/k-types.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import type { Analysis } from './analysis.ts';
+import { msOfOccurred } from './facts.ts';
+import { FIX_WORDS } from './units.ts';
+import { clip, standsAlone } from './text.ts';
+import { earlierWork } from '../keeper/organize/carried-on.ts';
+import { ownFindings, sendBackIdFor, startsSendBack, type CheckRecord, type FixRecord, type ReviewRecord, type WorkProcess } from './work.ts';
+
+export interface SendBackResult {
+  readonly created: number;
+  readonly returned: number;
+  readonly closed: number;
+  readonly open: number;
+  readonly written: number;
+}
+
+interface Origin {
+  readonly id: string;
+  readonly kind: 'check' | 'review';
+  readonly targetId: string;
+  readonly occurred: Occurred;
+  readonly ms: number;
+  readonly what: string;
+  readonly suggestion: string;
+  readonly evidence: readonly EvidenceRef[];
+  readonly process: WorkProcess;
+  readonly check: CheckRecord | null;
+  readonly review: ReviewRecord | null;
+}
+
+type Stage = { readonly stage: SendBack['stage']; readonly returned: SendBack['returned']; readonly closed: SendBack['closed'] };
+
+const RANK: Record<SendBack['stage'], number> = { Suggested: 0, Returned: 1, Closed: 2 };
+
+/** The failed checks and the host's send-back reviews of every current piece of work, once each (a chain is seen from several works). */
+function originsOf(a: Analysis): Origin[] {
+  const { store, facts, index } = a;
+  const gen = earlierWork(store);   // CZ: an item carried on under the same number is current work
+  const out = new Map<string, Origin>();
+  for (const t of store.threads.filter((x) => x.validity === 'Current' && !gen.has(x.id))) {
+    const p = a.process(t.id)!;
+    for (const c of p.checks) {
+      // A check unit's failing verdict; a "fail" in a delivery's own receipt is its account, not a check (CKC-27 AC-11), and
+      // a check still in progress (`incomplete（审核进行中）`) has judged nothing yet.
+      if (!startsSendBack(c) || !c.verdict || out.has(c.verdict.id)) continue;
+      const checked = index.units.get(c.unit)?.relations.map((r) => r.num) ?? [];
+      const targetNum = checked.find((n) => index.threadOf.has(n)) ?? null;
+      const targetId = targetNum ? index.threadOf.get(targetNum)! : t.id;
+      const findings = ownFindings(c);
+      out.set(c.verdict.id, {
+        id: c.verdict.id, kind: 'check', targetId, occurred: c.occurred, ms: c.ms, process: targetId === t.id ? p : a.process(targetId) ?? p, check: c, review: null,
+        what: `${c.unit}'s ${c.by === 'Independent QC' ? 'independent ' : ''}${c.kind === 'QC' ? 'QC' : c.kind.toLowerCase()} judged ${checked.filter((n) => index.units.has(n)).join(', ') || (t.ids[0] ?? t.title)} ${c.verdictWord ?? c.normalized}${findings.length ? `: ${findings.length} finding${findings.length === 1 ? '' : 's'}, ${clip(findings[0]!.text.replace(/^#+\s*/, ''), 80)}` : ''}`,
+        suggestion: `Fix what ${c.unit} found${findings.length ? ` (${findings.map((f) => f.verdict).join(', ')})` : ''} in new or reopened work, then have it checked again`,
+        evidence: [facts.ref(c.verdict.id, c.verdict.text), ...findings.slice(0, 8).map((f) => facts.ref(f.id, f.text))],
+      });
+    }
+    for (const r of p.reviews) {
+      if (out.has(r.entry.id)) continue;
+      const targetId = index.threadOf.get(r.unit) ?? t.id;
+      out.set(r.entry.id, {
+        id: r.entry.id, kind: 'review', targetId, occurred: r.occurred, ms: r.ms, process: targetId === t.id ? p : a.process(targetId) ?? p, check: null, review: r,
+        what: `${r.who ?? 'The host'} reviewed ${r.unit}'s delivery: ${r.status}`,
+        suggestion: `Repair ${r.unit}'s delivery in new or reopened work`,
+        evidence: [facts.ref(r.entry.id, `status: ${r.status}`), ...r.receipts.map((x) => facts.ref(x.id))],
+      });
+    }
+  }
+  return [...out.values()];
+}
+
+/** The stage of a send-back that a failed check or a host's review started, from its work's process. */
+function stageOfOrigin(a: Analysis, o: Origin): Stage {
+  const p = o.process;
+  // The fix that caught it: the first fix whose task was written at or after the failure and that fixes the checked
+  // unit or the check itself.
+  const failedUnit = o.check ? o.check.unit : o.review!.unit;
+  const checked = o.check ? a.index.units.get(o.check.unit)?.relations.map((r) => r.num) ?? [] : [o.review!.unit];
+  const fix: FixRecord | undefined = p.fixes
+    .filter((f) => (f.taskWritten?.ms ?? f.dispatched?.ms ?? f.ms) >= o.ms && f.targets.some((n) => n === failedUnit || checked.includes(n)))
+    .sort((x, y) => (x.taskWritten?.ms ?? x.ms) - (y.taskWritten?.ms ?? y.ms))[0];
+  if (!fix) return { stage: 'Suggested', returned: null, closed: null };
+  const by = fix.taskWritten?.evidence ?? fix.dispatched?.evidence ?? fix.evidence[0]!;
+  const returned = { by, at: by.occurred?.at ?? new Date().toISOString(), basis: 'Explicit' as Basis };
+  // Fixed: the earliest of a check after the fix that passed, and the fix landing on the trunk — the latter counts
+  // for a host's review, and for a failed check only where the project does not ask for a re-check after a fix.
+  const recheck = p.checks.filter((c) => c.ms > fix.ms && c.normalized === 'pass' && c.verdict).sort((x, y) => x.ms - y.ms)[0];
+  const needsRecheck = o.kind === 'check' && a.expecting(p.thread, 'Re-check after fix') !== null;
+  const closings = [
+    ...(recheck ? [{ ms: recheck.ms, by: a.facts.ref(recheck.verdict!.id, recheck.verdict!.text), at: recheck.occurred.at }] : []),
+    ...(!needsRecheck && fix.landed ? [{ ms: fix.landed.ms, by: fix.landed.evidence, at: fix.landed.occurred.at }] : []),
+  ].sort((x, y) => x.ms - y.ms);
+  const c = closings[0];
+  return c ? { stage: 'Closed', returned, closed: { by: c.by, at: c.at } } : { stage: 'Returned', returned, closed: null };
+}
+
+/** The numbers of a send-back's target (the work item, or what the reference item or territory names). */
+function targetNumbers(store: ProjectStore, sb: SendBack): string[] {
+  return store.threads.get(sb.targetId)?.ids.slice() ?? store.reference.get(sb.targetId)?.ids.slice() ?? [];
+}
+
+/** The stage a suggested send-back has reached by what came later (§1.18), whoever suggested it. */
+function stageOfSuggested(a: Analysis, sb: SendBack): Stage {
+  const { store, facts, index } = a;
+  const since = msOfOccurred(sb.occurred);
+  let returned: SendBack['returned'] = sb.returned;
+  const candidates: { ms: number; by: EvidenceRef; basis: Basis }[] = [];
+  // 1. A later commit or document that cites the send-back's own id (the text `Copy for agent` hands over carries it).
+  const cited = facts.ledger.word(sb.id, { limit: 20, oldestFirst: true });
+  if (typeof cited !== 'string') for (const h of cited.rows) if (h.kind === 'doc' || h.kind === 'commit' || h.kind === 'loose') candidates.push({ ms: msOfOccurred(h.occurred), by: facts.ref(h.id, h.snippet), basis: 'Explicit' });
+  const nums = targetNumbers(store, sb);
+  if (sb.to === 'Work') {
+    // 2. A later fix task that names the work, or a later commit that says it fixes it.
+    for (const u of index.units.values()) {
+      if (u.nature !== 'fix' || !u.relations.some((r) => nums.includes(r.num))) continue;
+      const task = u.prompts[0];
+      if (task && task.ms > since) candidates.push({ ms: task.ms, by: facts.ref(task.id, task.data.title ?? null), basis: 'Explicit' });
+    }
+    for (const c of facts.commits.values()) {
+      if (c.ms <= since || c.merge || !FIX_WORDS.test(c.subject) || !nums.some((n) => standsAlone(c.subject, n))) continue;
+      candidates.push({ ms: c.ms, by: facts.ref(c.id), basis: 'Explicit' });
+    }
+  } else {
+    // 2'. A later version of the document the send-back to Plan hangs on.
+    for (const path of documentPaths(a, sb.targetId)) {
+      const v = (facts.docsByPath.get(path) ?? []).find((d) => d.ms > since);
+      if (v) candidates.push({ ms: v.ms, by: facts.ref(v.id), basis: 'Explicit' });
+    }
+  }
+  // 3. A confirmed link on the target, later than the problem.
+  for (const l of store.links.filter((x) => x.workId === sb.targetId && linkHolds(x) && (x.stepKind === 'Fix' || x.stepKind === 'Delivered' || x.stepKind === 'Dispatched'))) {
+    const ms = msOfOccurred(l.evidence?.occurred);
+    if (ms > since) candidates.push({ ms, by: l.evidence ?? facts.ref(l.ledgerRef), basis: 'Inferred' });
+  }
+  const first = candidates.filter((c) => c.ms > 0).sort((x, y) => x.ms - y.ms)[0];
+  if (!returned && first) returned = { by: first.by, at: first.by.occurred?.at ?? new Date(first.ms).toISOString(), basis: first.basis };
+  // Closed: the breakpoint it came from went out on evidence; the note or mark it came from was resolved; for Work, a
+  // passing check or a merge of the work after it was returned.
+  let closed: SendBack['closed'] = null;
+  if (sb.from.kind === 'breakpoint') {
+    // Put out by evidence of the step — not by this send-back itself, which only says the problem went back.
+    const bp = store.breakpoints.get(sb.from.id);
+    const ev = bp && !bp.lit && bp.out?.by === 'evidence' ? bp.out.evidence.find((e) => e.id !== sb.id && !(e.kind === 'object' && store.sendbacks.has(e.id))) : undefined;
+    if (ev) closed = { by: ev, at: bp!.out!.at };
+  } else if (sb.from.kind === 'owner-judgement') {
+    const mark = store.marks.get(sb.from.id);
+    const note = store.notes.get(sb.from.id);
+    if (mark?.closed) closed = { by: { kind: 'object', id: mark.id, label: `${mark.kind} closed: ${mark.closed.result}`, line: mark.closed.reason, occurred: null }, at: mark.closed.at };
+    else if (note?.status === 'Resolved') closed = { by: { kind: 'object', id: note.id, label: `Note resolved: ${note.versions[note.versions.length - 1]?.title ?? note.id}`, line: note.resolvedReason, occurred: null }, at: note.updatedAt };
+  }
+  if (!closed && returned && sb.to === 'Work') {
+    const thread = store.threads.get(sb.targetId);
+    const p = thread ? a.process(thread.id) : null;
+    const after = msOfOccurred(returned.by.occurred) || Date.parse(returned.at) || since;
+    const pass = p?.checks.filter((c) => c.ms > after && c.normalized === 'pass').sort((x, y) => x.ms - y.ms)[0];
+    const merge = p ? [...p.delivery.merges, ...p.fixes.flatMap((f) => f.merges)].filter((m) => m.ms > after).sort((x, y) => x.ms - y.ms)[0] : undefined;
+    if (pass?.verdict) closed = { by: facts.ref(pass.verdict.id, pass.verdict.text), at: pass.occurred.at };
+    else if (merge && !(thread && a.expecting(thread, 'Re-check after fix'))) closed = { by: facts.ref(merge.id), at: merge.occurred.at };
+  }
+  if (closed && !returned) returned = { by: closed.by, at: closed.at, basis: 'Explicit' };
+  return { stage: closed ? 'Closed' : returned ? 'Returned' : 'Suggested', returned, closed };
+}
+
+function documentPaths(a: Analysis, id: string): string[] {
+  const { store, facts } = a;
+  const ref = store.reference.get(id);
+  const out = new Set<string>();
+  for (const sid of ref?.sourceIds ?? []) {
+    const an = store.sources.get(sid)?.anchor;
+    if (an?.kind !== 'file') continue;
+    for (const path of facts.docsByPath.keys()) if (an.path.replace(/\\/g, '/').endsWith(`/${path}`)) out.add(path);
+  }
+  return [...out];
+}
+
+/**
+ * Record the send-backs the project's own failed checks and reviews started, and move every send-back on by what the
+ * ledger shows (never back, never by hand). Returns what moved.
+ */
+export function advance(a: Analysis, roundId: string | null, jobId: string | null): SendBackResult {
+  const { store, project } = a;
+  const now = new Date().toISOString();
+  const trace = (summary: string, sourceIds: readonly string[] = []) => ({ jobId, summary, basisSourceIds: sourceIds });
+  let created = 0; let returned = 0; let closed = 0; let written = 0;
+  const handled = new Set<string>();
+  for (const o of originsOf(a)) {
+    const existing = store.sendbacks.get(sendBackIdFor(project.id, o.id)) ?? store.sendbacks.find((s) => s.from.id === o.id);
+    const st = stageOfOrigin(a, o);
+    if (existing) {
+      handled.add(existing.id);
+      const next = moveOn(existing, st, now);
+      if (next) { store.sendbacks.put(next, trace(`Send-back ${existing.id}: ${existing.stage} → ${next.stage} (program)`)); written += 1; if (next.stage !== existing.stage) (next.stage === 'Closed' ? closed++ : returned++); }
+      continue;
+    }
+    const record: SendBack = {
+      id: sendBackIdFor(project.id, o.id), projectId: project.id, to: 'Work', stage: st.stage, targetId: o.targetId, what: o.what, suggestion: o.suggestion,
+      evidence: o.evidence, from: { kind: 'verdict', id: o.id }, returned: st.returned, closed: st.closed, ownerResponse: null, sixThing: null,
+      occurred: o.occurred, roundId, updatedAt: now,
+    };
+    store.sendbacks.put(record, trace(`Send-back to Work (program, from ${o.kind === 'check' ? 'a failed check' : "the host's review"}): ${clip(o.what, 120)} — ${st.stage}`));
+    handled.add(record.id);
+    created += 1; written += 1;
+    if (st.stage === 'Returned') returned += 1;
+    if (st.stage === 'Closed') closed += 1;
+  }
+  for (const sb of store.sendbacks.filter((s) => s.projectId === project.id && !handled.has(s.id) && s.stage !== 'Closed')) {
+    const next = moveOn(sb, stageOfSuggested(a, sb), now);
+    if (!next) continue;
+    store.sendbacks.put(next, trace(`Send-back ${sb.id}: ${sb.stage} → ${next.stage} (program): ${next.stage === 'Closed' ? next.closed!.by.label : next.returned!.by.label}`));
+    written += 1;
+    if (next.stage !== sb.stage) (next.stage === 'Closed' ? closed++ : returned++);
+  }
+  const open = store.sendbacks.filter((s) => s.projectId === project.id && s.stage !== 'Closed' && !s.ownerResponse).length;
+  return { created, returned, closed, open, written };
+}
+
+/** The send-back moved on to a computed stage, never back; null when nothing changes. The owner's answer stays. */
+function moveOn(sb: SendBack, st: Stage, now: string): SendBack | null {
+  if (RANK[st.stage] < RANK[sb.stage]) return null;
+  const returned = sb.returned ?? st.returned;
+  const closed = sb.closed ?? st.closed;
+  const stage = closed ? 'Closed' : returned ? 'Returned' : 'Suggested';
+  if (stage === sb.stage && returned === sb.returned && closed === sb.closed) return null;
+  return { ...sb, stage, returned, closed, updatedAt: now };
+}
+