projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/organize/schedule.ts

@@ -0,0 +1,137 @@
+/**
+ * The schedule of daily organizing (Spec §3.8, §6.10; D105; CKC-07 AC-18, AC-28～AC-30).
+ *
+ * The owner sets how often a round starts by itself and at what time of day, on the `Daily` page: `Off`, `Every day`,
+ * `On selected days`, `Every N days` — each of the last three with a time — or `Continuous`. Times are this machine's
+ * local time. A project whose schedule was never saved runs `Every day` at the time of day its takeover finished.
+ *
+ * Everything here is computed: which scheduled time comes next, which one was the last to pass, and whether one is due.
+ * The planner (clerk.ts) asks `scheduledDue` and stamps what it did with the time on the project (`scheduleHandled`), so
+ * a time that passed while ProjectKeeper was not running, or the machine slept, is made up for with one round however
+ * many were missed, and no time is dealt with twice.
+ */
+import type { OrganizeSchedule, Project, ScheduleFrequency } from '../../model/types.ts';
+
+export const SCHEDULE_FREQUENCIES: readonly ScheduleFrequency[] = ['Off', 'Every day', 'On selected days', 'Every N days', 'Continuous'];
+/** The frequencies that start a round at a time of day. */
+export const TIMED_FREQUENCIES: readonly ScheduleFrequency[] = ['Every day', 'On selected days', 'Every N days'];
+export const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] as const;
+const DAY_MS = 24 * 60 * 60_000;
+/** How far a search for a scheduled time looks: more than the longest `Every N days` allowed. */
+const MAX_EVERY_DAYS = 365;
+
+const pad = (n: number) => String(n).padStart(2, '0');
+/** The local time of day of an instant, `HH:MM`. */
+export const localTime = (at: Date): string => `${pad(at.getHours())}:${pad(at.getMinutes())}`;
+/** The local date of an instant, `YYYY-MM-DD`. */
+export const localDate = (at: Date): string => `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`;
+
+const parseTime = (time: string): { h: number; m: number } | null => {
+  const x = /^([01]?\d|2[0-3]):([0-5]\d)$/.exec(time.trim());
+  return x ? { h: Number(x[1]), m: Number(x[2]) } : null;
+};
+
+/** What the owner sent from the `Daily` page, checked: the schedule to save, or why it cannot be saved. */
+export function parseSchedule(input: unknown, now = new Date()): { schedule: OrganizeSchedule } | { error: string } {
+  const b = (input ?? {}) as Record<string, unknown>;
+  const frequency = b.frequency;
+  if (typeof frequency !== 'string' || !(SCHEDULE_FREQUENCIES as readonly string[]).includes(frequency)) return { error: `frequency must be one of ${SCHEDULE_FREQUENCIES.join(', ')}` };
+  const f = frequency as ScheduleFrequency;
+  const timed = TIMED_FREQUENCIES.includes(f);
+  const time = typeof b.time === 'string' ? b.time.trim() : '';
+  const t = parseTime(time);
+  if (timed && !t) return { error: 'time must be a time of day, HH:MM' };
+  const base = { frequency: f, time: t ? `${pad(t.h)}:${pad(t.m)}` : '00:00', savedAt: now.toISOString() };
+  if (f === 'On selected days') {
+    const days = Array.isArray(b.days) ? [...new Set(b.days.map(Number).filter((d) => Number.isInteger(d) && d >= 0 && d <= 6))].sort((x, y) => x - y) : [];
+    if (!days.length) return { error: 'Choose at least one day of the week' };
+    return { schedule: { ...base, days } };
+  }
+  if (f === 'Every N days') {
+    const n = Number(b.everyDays);
+    if (!Number.isInteger(n) || n < 1 || n > MAX_EVERY_DAYS) return { error: `everyDays must be a whole number from 1 to ${MAX_EVERY_DAYS}` };
+    return { schedule: { ...base, everyDays: n, anchor: localDate(now) } };
+  }
+  return { schedule: base };
+}
+
+/**
+ * The schedule in force for a project. One the owner saved stands as saved. Otherwise the default (§3.8): `Every day` at
+ * the time of day the takeover finished — which is also what a home from before D105 gets from its `Daily` rhythm (its
+ * last round's end, when there is one: a day after the last round is what `Daily` meant); its `Continuous` stays.
+ * `takeoverDoneAt` is when the takeover finished, `lastRoundEnd` when the project's latest round ended.
+ */
+export function scheduleOf(project: Pick<Project, 'schedule' | 'organizeRhythm'>, when: { readonly takeoverDoneAt?: string | null; readonly lastRoundEnd?: string | null } = {}): OrganizeSchedule {
+  if (project.schedule) return project.schedule;
+  if (project.organizeRhythm === 'Continuous') return { frequency: 'Continuous', time: '00:00', savedAt: null };
+  const from = when.lastRoundEnd ?? when.takeoverDoneAt ?? null;
+  return { frequency: 'Every day', time: from ? localTime(new Date(from)) : '09:00', savedAt: null };
+}
+
+/** Whether a local calendar day is one the schedule starts a round on. */
+function onDay(s: OrganizeSchedule, day: Date): boolean {
+  if (s.frequency === 'Every day') return true;
+  if (s.frequency === 'On selected days') return (s.days ?? []).includes(day.getDay());
+  if (s.frequency === 'Every N days') {
+    const n = Math.max(1, s.everyDays ?? 1);
+    const a = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s.anchor ?? '');
+    const anchor = a ? new Date(Number(a[1]), Number(a[2]) - 1, Number(a[3])) : new Date(day.getFullYear(), day.getMonth(), day.getDate());
+    // Whole local days between the two dates; rounding absorbs the hour a daylight-saving change adds or removes.
+    const days = Math.round((new Date(day.getFullYear(), day.getMonth(), day.getDate()).getTime() - anchor.getTime()) / DAY_MS);
+    return days >= 0 && days % n === 0;
+  }
+  return false;
+}
+
+/** The scheduled time on a local calendar day. */
+function slotOn(s: OrganizeSchedule, day: Date): Date {
+  const t = parseTime(s.time) ?? { h: 0, m: 0 };
+  return new Date(day.getFullYear(), day.getMonth(), day.getDate(), t.h, t.m, 0, 0);
+}
+
+/** The first scheduled time strictly after `after`; null when the schedule starts nothing by the clock. */
+export function nextSlot(s: OrganizeSchedule, after: Date): Date | null {
+  if (!TIMED_FREQUENCIES.includes(s.frequency)) return null;
+  for (let i = 0; i <= MAX_EVERY_DAYS + 7; i++) {
+    const day = new Date(after.getFullYear(), after.getMonth(), after.getDate() + i);
+    if (!onDay(s, day)) continue;
+    const slot = slotOn(s, day);
+    if (slot.getTime() > after.getTime()) return slot;
+  }
+  return null;
+}
+
+/** The latest scheduled time at or before `now`, no earlier than `notBefore`; null when none has passed since then. */
+export function lastSlot(s: OrganizeSchedule, now: Date, notBefore: Date): Date | null {
+  if (!TIMED_FREQUENCIES.includes(s.frequency)) return null;
+  for (let i = 0; i <= MAX_EVERY_DAYS + 7; i++) {
+    const day = new Date(now.getFullYear(), now.getMonth(), now.getDate() - i);
+    const slot = slotOn(s, day);
+    if (slot.getTime() <= notBefore.getTime()) return null;
+    if (onDay(s, day) && slot.getTime() <= now.getTime()) return slot;
+  }
+  return null;
+}
+
+/**
+ * Whether a scheduled time has come that was not dealt with yet (§3.8 到了时间). `since` is the later of: when the
+ * schedule was saved, when the takeover finished, and the last scheduled time already dealt with — times before it are
+ * not made up for. `missed` counts the scheduled times that passed since then; however many, one round makes up for them.
+ */
+export function scheduledDue(s: OrganizeSchedule, now: Date, since: Date): { readonly slot: Date; readonly missed: number } | null {
+  const slot = lastSlot(s, now, since);
+  if (!slot) return null;
+  let missed = 0;
+  for (let at = nextSlot(s, since); at && at.getTime() <= now.getTime() && missed < 1000; at = nextSlot(s, at)) missed += 1;
+  return { slot, missed: Math.max(1, missed) };
+}
+
+/** The schedule in one line, as the `Daily` page and the context say it. */
+export function scheduleText(s: OrganizeSchedule): string {
+  if (s.frequency === 'Off') return 'Off — a round runs only when you press Follow up';
+  if (s.frequency === 'Continuous') return 'Continuous — a round after each stretch of work';
+  if (s.frequency === 'Every day') return `Every day at ${s.time}`;
+  if (s.frequency === 'On selected days') return `On ${(s.days ?? []).map((d) => DAY_NAMES[d]).join(', ')} at ${s.time}`;
+  const n = s.everyDays ?? 1;
+  return `Every ${n === 1 ? 'day' : `${n} days`} at ${s.time}`;
+}

package/src/keeper/organize/service.ts

@@ -0,0 +1,409 @@
+/**
+ * Organizing service (CKC-05, CKC-06, CKC-07, CKC-13): plans and queues the Keeper's automatic work from the state of
+ * the assets, keeps the coverage record honest, marks entries whose material changed (`Update pending`), and derives
+ * the graph after every job.
+ *
+ * Since increment K every round is a round of the clerk method (Spec v3.0 §3.3; clerk.ts). Planning is a pull: after
+ * each job (and after intake, settled changes, resume) the service lets the clerk planner advance the round under way or
+ * start the one that is due, and brings coverage and the takeover's progress up to date from the rounds, so the Keeper
+ * activity list shows what is happening now.
+ */
+import type { Coverage, CoverageScope, DeepeningPlan, KeeperJob, TakeoverStatus } from '../../model/types.ts';
+import { organizingHeld } from '../held.ts';
+import type { ProjectStore } from '../../store/project-store.ts';
+import type { PendingChange } from '../../sources/watch.ts';
+import type { IntakeResult } from '../../intake/intake.ts';
+import { excludedLocations, splitTooLarge } from '../../intake/skipped.ts';
+import type { App } from '../../server/app.ts';
+import type { KeeperEvent } from '../runtime.ts';
+import { gitHead } from '../../util/git.ts';
+import { listMaterials } from './materials.ts';
+import { areaOf, deriveGraph } from './graph.ts';
+import { positioningBlock } from './positioning.ts';
+import { composeRelook, scopeLabel, type RelookScope } from '../relook/compose.ts';
+import { relookPrompt } from '../relook/prompts.ts';
+import { takeoverState } from './takeover-state.ts';
+import { scheduleDueFor } from './schedule-state.ts';
+import { clerkDepthOptions, deepeningAsRun, deepeningPlanned, deepeningReads, firstUsableFigures, focusedCovers } from './takeover-clerk.ts';
+import { readingBasisText } from './reading.ts';
+import { isRoundMain } from '../roles.ts';
+import { ACTIVE_STATUSES, ClerkPlanner, stepFailureText, type LedgerRunner, type ProcessRunner } from './clerk.ts';
+import { clerkLevels, clerkPending } from './clerk-coverage.ts';
+import { refreshUpdatePending } from './update-pending.ts';
+import { isTableJob, tableJobs, tablePending, TableFollowUp } from './table-follow-up.ts';
+
+/** What the service reads from a job's task, and writes into a re-look's: its kind, judgement record and scope. */
+interface TaskExtra { readonly kind: string; readonly judgementId?: string; readonly scopeKey?: string }
+
+const ACTIVE: readonly string[] = ['Queued', 'Running', 'Waiting for quota', 'Paused'];
+const extraOf = (job: KeeperJob): TaskExtra | null => ((job.task as { extra?: TaskExtra } | null)?.extra ?? null);
+
+/** What an owner's request left to re-look at, kept on the request's job until the re-looks open (§3.3, §5.6). */
+interface DeferredExtra { readonly deferredRelooks?: readonly RelookScope[]; readonly relooksOpenedAt?: string | null }
+const deferredOf = (job: KeeperJob): DeferredExtra | null => ((job.task as { extra?: DeferredExtra } | null)?.extra ?? null);
+
+/** A round under way: a round of the clerk method running, or — left by a build before it — a round's main job still active. */
+function roundUnderWay(store: ProjectStore): boolean {
+  return store.clerkRounds.find((r) => r.status === 'Running') !== undefined || store.jobs.find((j) => ACTIVE.includes(j.status) && isRoundMain(j)) !== undefined;
+}
+
+export class OrganizingService {
+  private readonly app: App;
+  private readonly enabled: boolean;
+  private readonly replanning = new Map<string, { running: boolean; again: boolean }>();
+
+  /** The clerk method (Spec v3.0 §3.3): plans every round since increment K. */
+  private clerk: ClerkPlanner;
+  /** D107: a project taken over by the ProjectKeeper table is followed up by carrying the table on, not by rounds. */
+  private table: TableFollowUp;
+
+  constructor(app: App, enabled = true) { this.app = app; this.enabled = enabled; this.clerk = new ClerkPlanner(app, null); this.table = new TableFollowUp(app); }
+
+  /** The program step of every round: bring the ledger up to date (src/ledger). Set once the build carries it. */
+  setLedgerRunner(runner: LedgerRunner | null): void { this.clerk.setLedgerRunner(runner); }
+  /** The program step that computes each work item's process and breakpoints (§2.12). Set once the build carries it. */
+  setProcessRunner(runner: ProcessRunner | null): void { this.clerk.setProcessRunner(runner); }
+
+  start(): void {
+    this.app.keeper.on('event', (event: KeeperEvent) => { if (event.kind === 'done') void this.afterJob(event.projectId, event.jobId); });
+  }
+
+  /** The clock the schedule is read against (§3.8); a test sets it. */
+  setClock(clock: () => number): void { this.clerk.clock = clock; this.table.clock = clock; }
+
+  private ticker: NodeJS.Timeout | null = null;
+  /**
+   * Watch the clock for the scheduled times (§3.8; CKC-07 AC-29, AC-30): twice a minute, a project whose scheduled time
+   * has come is planned again, and the planner starts a round when something changed. After the machine slept, or
+   * ProjectKeeper was not running, the first pass finds the time that was missed and makes up for it with one round.
+   */
+  watchSchedule(everyMs = 30_000): void {
+    if (!this.enabled || this.ticker) return;
+    this.ticker = setInterval(() => { void this.tick(); }, everyMs);
+    this.ticker.unref?.();
+  }
+  stopWatchingSchedule(): void { if (this.ticker) { clearInterval(this.ticker); this.ticker = null; } }
+  /** One pass over the projects: one whose scheduled time has come is planned again. A paused project waits for its resume. */
+  async tick(): Promise<void> {
+    for (const p of this.app.workspace.list()) {
+      try {
+        if (organizingHeld(p)) continue;
+        const store = this.app.store(p.id);
+        const state = takeoverState(store, p);
+        if (state.phase === 'Done' && scheduleDueFor(store, p, state.completedAt, this.clerk.clock())) await this.replan(p.id);
+      } catch (e) { console.warn(`[schedule ${p.id}] ${(e as Error).message}`); }
+    }
+  }
+
+  /**
+   * When ProjectKeeper starts, each project's organizing goes on from its saved progress (Spec §3.10 接着做): the round
+   * under way advances — what the restart cut short runs again (clerk.ts `stepEnding`) — and a step of a round that was
+   * waiting for quota is queued again, because what would have queued it (the runtime's quota and rate-limit timers) did
+   * not outlive the last run. If the quota is still out, it waits again.
+   */
+  resumeAll(): void {
+    for (const p of this.app.workspace.list()) {
+      if (this.enabled) {
+        try {
+          const store = this.app.store(p.id);
+          for (const j of store.jobs.filter((x) => x.status === 'Waiting for quota' && store.clerkRounds.get(x.step?.roundId ?? '')?.status === 'Running')) this.app.keeper.restartJob(p.id, j.id);
+        } catch (e) { console.warn(`[organize ${p.id}] ${(e as Error).message}`); }
+      }
+      void this.replan(p.id);
+    }
+  }
+  onIntake(projectId: string): void { void this.replan(projectId); }
+
+  /**
+   * The owner's Retry or Continue on a job (Spec §3.10, §6.9). A job of a round's step is the planner's to run again — a
+   * job the program did itself as well (the ledger, the process, the program's part of a step), which the runtime does
+   * not run; any other job goes back on the runtime's queue.
+   */
+  runAgain(projectId: string, jobId: string): boolean {
+    const store = this.app.store(projectId);
+    const job = store.jobs.get(jobId);
+    if (!job) return false;
+    return job.step ? this.clerk.ownerRunAgain(store, this.app.project(projectId), job) : this.app.keeper.restartJob(projectId, jobId);
+  }
+
+  onSettled(projectId: string, changes: readonly PendingChange[], _result: IntakeResult): void {
+    this.markPending(projectId, changes);
+    void this.replan(projectId);
+  }
+
+  /**
+   * Settled changes were just read (§3.2): the entries they affect show `Update pending` (§1.11), each naming the changes it
+   * waits for and how they reach it (update-pending.ts). The marks follow the coverage's list of what waits for the next
+   * round, so only material that will be organized again marks anything: what is History only or Reference only, what the
+   * scope does not read, what the project's rules settle and the Keeper's own commits of its project folder never do.
+   *
+   * A changed material does not modify the work items built on it, so their propagation judgements stand (§2.10,
+   * §5.5): a work item is modified when organizing brings it up to date, and then the next round judges what it still
+   * lacks, while what already has a conclusion keeps it. Its own time is left alone as well: when an object last
+   * changed is evidence a judgement weighs, and the change of a material is not a change of the object. Resetting the
+   * entries to `Not yet checked` here left objects in the change's detail that no round would judge — a concluded
+   * item is not judged again, and the refreshed time made the entry read as answered (batch D2, AK P4).
+   */
+  markPending(projectId: string, changes: readonly PendingChange[]): void {
+    if (changes.length === 0) return;
+    try { refreshUpdatePending(this.app, projectId); } catch (e) { console.warn(`[update pending ${projectId}] ${(e as Error).message}`); }
+  }
+
+  private async afterJob(projectId: string, jobId: string): Promise<void> {
+    const store = this.app.store(projectId);
+    const job = store.jobs.get(jobId);
+    if (job && extraOf(job)?.kind === 'relook') this.finalizeRelook(store, job);
+    try { deriveGraph(store, this.app.project(projectId)); } catch (e) { console.warn(`[graph ${projectId}] ${(e as Error).message}`); }
+    if (job && job.kind === 'Your request' && job.status === 'Done') this.relookAfterRequest(store, job);
+    await this.replan(projectId);
+  }
+
+  /** §5.6: after a delegated or authorized adjustment, the affected scope is re-looked at; changing files alone resolves nothing. */
+  private relookAfterRequest(store: ProjectStore, job: KeeperJob): void {
+    const areaIds = new Set<string>();
+    const consider = (id: string) => { const a = store.reference.has(id) ? areaOf(store, id) : store.threads.has(id) ? this.threadArea(store, id) : null; if (a) areaIds.add(a); };
+    for (const r of job.savedResults) consider(r.id);
+    const ctx = (job.task as { extra?: { context?: { kind: string; id: string } } } | null)?.extra?.context;
+    if (ctx?.kind === 'note') { const n = store.notes.get(ctx.id); for (const id of n?.mount.ids ?? []) consider(id); }
+    else if (ctx) consider(ctx.id);
+    const scopes: RelookScope[] = areaIds.size === 0 ? [{ kind: 'project', id: null, label: 'Whole project' }] : [...areaIds].slice(0, 3).map((id) => ({ kind: 'area', id, label: store.reference.get(id)?.name ?? id }));
+    // Like every automatic re-look, it opens after the round under way has ended, not alongside it (§3.3): the round's
+    // synthesis writes the notes then. What waits is kept on the request's own job, not in memory, so a restart in between
+    // does not lose it (C1's hand-back item 2), and `openDeferredRelooks` opens it once no round is under way.
+    if (roundUnderWay(store)) {
+      const current = store.jobs.get(job.id) ?? job;
+      const task = (current.task ?? {}) as { extra?: Record<string, unknown> | null };
+      const extra = task.extra ?? {};
+      const waiting = [...((extra.deferredRelooks as RelookScope[] | undefined) ?? []), ...scopes];
+      store.jobs.put({ ...current, task: { ...task, extra: { ...extra, deferredRelooks: waiting, relooksOpenedAt: null } } }, { jobId: job.id, summary: `Re-look after the request waits for the round under way: ${scopes.map((sc) => sc.label).join(', ')}` });
+      return;
+    }
+    for (const scope of scopes) this.enqueueRelook(job.projectId, scope, false);
+  }
+
+  /**
+   * The re-looks an owner's request left for after the round under way (`relookAfterRequest`), opened once no round is
+   * under way — each scope once — and marked opened on the request's job, so they open once and a restart before then
+   * does not lose them. The reader of what waits went with the material rounds' planner (06bccd4), which left the owner's
+   * request stored and never opened (explore of test-C-1, §5.6 item 5).
+   */
+  openDeferredRelooks(projectId: string): number {
+    const store = this.app.store(projectId);
+    if (roundUnderWay(store)) return 0;
+    const waiting = store.jobs.filter((j) => (deferredOf(j)?.deferredRelooks?.length ?? 0) > 0 && !deferredOf(j)?.relooksOpenedAt).sort((a, b) => a.queuedAt.localeCompare(b.queuedAt));
+    if (!waiting.length) return 0;
+    const now = new Date().toISOString();
+    const seen = new Set<string>();
+    for (const j of waiting) {
+      const task = (j.task ?? {}) as { extra?: Record<string, unknown> | null };
+      store.jobs.put({ ...j, task: { ...task, extra: { ...(task.extra ?? {}), relooksOpenedAt: now } } }, { jobId: j.id, summary: 'The re-looks the request left for after the round are opened now' });
+      for (const scope of deferredOf(j)!.deferredRelooks!) {
+        const key = `${scope.kind}:${scope.id ?? ''}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        this.enqueueRelook(projectId, scope, false);
+      }
+    }
+    return seen.size;
+  }
+
+  private threadArea(store: ProjectStore, threadId: string): string | null {
+    const t = store.threads.get(threadId);
+    if (!t) return null;
+    for (const s of t.serves) { const a = areaOf(store, s.referenceId); if (a) return a; }
+    return null;
+  }
+
+  /** After a re-look: a `Questioned` without a note is not allowed (§2.5); record whether anything was found. */
+  private finalizeRelook(store: ProjectStore, job: KeeperJob): void {
+    const judgementId = extraOf(job)?.judgementId;
+    const j = judgementId ? store.judgements.get(judgementId) : undefined;
+    if (!j) return;
+    const now = new Date().toISOString();
+    const assessments = j.outcome.assessments.filter((a) => {
+      if (a.assessment !== 'Questioned') return true;
+      const r = store.relations.get(a.relationId);
+      if (!r) return false;
+      const hasNote = store.notes.find((n) => n.status === 'Current' && (n.mount.ids.includes(r.id) || n.mount.ids.includes(r.from) || n.mount.ids.includes(r.to) || n.versions.some((v) => v.judgementRecordId === j.id && (v.preview.includes(r.id) || JSON.stringify(v.body).includes(r.id)))));
+      if (hasNote) return true;
+      store.relations.put({ ...r, assessment: 'Not assessed', assessedAt: now, assessedInJobId: job.id, updatedAt: now }, { jobId: job.id, summary: 'Questioned without a note; assessment reverted to Not assessed' });
+      return false;
+    });
+    const reconsideredOnly = job.status === 'Done' && j.outcome.noteIds.length === 0 && assessments.length === 0;
+    store.judgements.put({ ...j, outcome: { ...j.outcome, assessments, reconsideredOnly } });
+    // The notes this re-look touched keep the course of events (§4.5, CKC-11 AC-16).
+    for (const noteId of j.outcome.noteIds) {
+      const n = store.notes.get(noteId);
+      if (!n || n.followUps.some((f) => f.jobId === job.id)) continue;
+      store.notes.put({ ...n, followUps: [...n.followUps, { kind: 'relook', jobId: job.id, at: now, summary: `Product re-look: ${j.scope.label}${n.status !== 'Current' ? ` → ${n.status}` : ''}` }] });
+    }
+    if (job.status === 'Done') {
+      const scopes = store.coverage.scopes.map((s) => (s.id === 'project' ? { ...s, lastRelookAt: now } : s));
+      store.setCoverage({ ...store.coverage, scopes }, { jobId: job.id, summary: `Product re-look done: ${j.scope.label}${reconsideredOnly ? ' (reconsidered; no new finding)' : ''}` });
+    }
+  }
+
+  /** Owner-requested re-look (§3.4 "owner 要求"): runs in the owner lane ahead of backlog. */
+  requestRelook(projectId: string, scope: RelookScope): KeeperJob {
+    return this.enqueueRelook(projectId, scope, true);
+  }
+
+  private enqueueRelook(projectId: string, scope: RelookScope, byOwner: boolean): KeeperJob {
+    const store = this.app.store(projectId);
+    const project = this.app.project(projectId);
+    const composed = composeRelook(store, project, scope, '');
+    store.judgements.put(composed.judgement, { jobId: null, summary: `Re-look inputs composed: ${composed.judgement.scope.label}` });
+    const first = !store.judgements.find((j) => j.scope.kind === 'project' && j.id !== composed.judgement.id);
+    const job = this.app.keeper.enqueue(projectId, {
+      kind: 'Product re-look', initiator: byOwner ? 'owner' : 'auto', priority: byOwner ? 0 : 2, timeoutMs: 45 * 60_000,
+      scope: { kind: scope.kind, ids: scope.id ? [scope.id] : [], label: scopeLabel(store, scope) },
+      prompt: relookPrompt(positioningBlock(store, project), composed.judgement.scope.label, composed.judgement.id, composed.text, first, byOwner),
+      judgementId: composed.judgement.id,
+      task: { kind: 'relook', judgementId: composed.judgement.id, scopeKey: `${scope.kind}:${scope.id ?? ''}` } satisfies TaskExtra,
+    });
+    store.judgements.put({ ...composed.judgement, jobId: job.id });
+    return job;
+  }
+
+  /** Re-evaluate what to queue next; serialized per project. */
+  async replan(projectId: string): Promise<Coverage> {
+    if (!this.enabled || this.app.isClearing(projectId)) return this.app.store(projectId).coverage;
+    let st = this.replanning.get(projectId);
+    if (!st) { st = { running: false, again: false }; this.replanning.set(projectId, st); }
+    if (st.running) { st.again = true; return this.app.store(projectId).coverage; }
+    st.running = true;
+    try {
+      do { st.again = false; await this.plan(projectId); } while (st.again);
+    } catch (e) {
+      console.warn(`[organize ${projectId}] ${(e as Error).message}`);
+    } finally {
+      st.running = false;
+    }
+    return this.app.store(projectId).coverage;
+  }
+
+  /**
+   * Since increment K every round is a round of the clerk method (Spec v3.0 §3.3; CKC-23): the planner below advances the
+   * round under way or starts the one that is due, and the coverage and the depth question follow from its rounds. The
+   * material rounds it replaced (D59; CKC-06) are gone.
+   */
+  private async plan(projectId: string): Promise<void> {
+    // D107: a project taken over by the table never starts the clerk method's rounds; its Follow up is a table follow-up.
+    if (this.app.project(projectId).takenOverByTable) await this.table.plan(projectId);
+    else await this.clerk.plan(projectId);
+    this.openDeferredRelooks(projectId);
+    this.clerkCoverage(projectId);
+  }
+
+  /** The coverage and the takeover's progress for the clerk method's rounds (`writeClerkCoverage`). */
+  private clerkCoverage(projectId: string): void {
+    writeClerkCoverage(this.app, projectId);
+  }
+}
+
+/**
+ * Coverage and takeover progress for the clerk method's rounds (Spec §3.7, §1.11; CKC-13 AC-1, AC-10, AC-19, AC-20):
+ * the first usable round's time as evidence (D37), where the takeover stands (not started, under way, done), what waits and what is
+ * running or failed, every material's organizing level, and the last Follow up. The depth options are sized from the
+ * project's own material. Exported so a fixture that plants rounds gets the coverage the product computes from them.
+ */
+export function writeClerkCoverage(app: App, projectId: string): void {
+  const store = app.store(projectId);
+  const project = app.project(projectId);
+  const rounds = store.clerkRounds.all().sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+  const first = rounds.find((r) => r.kind === 'First usable');
+  const firstDone = first?.status === 'Done';
+  // Where the takeover stands is read from the rounds (takeover-state.ts): the depth is the one the takeover runs to, and
+  // once it is done, the one that ran — never the last button pressed (D105).
+  const takeover = takeoverState(store, project);
+  const notStarted = takeover.phase === 'Not started';
+  const depth = takeover.phase === 'Done' ? takeover.ran : takeover.chosen;
+  const complete = takeover.phase === 'Done';
+  const stage: TakeoverStatus['stage'] = notStarted ? 'Not started' : !firstDone ? 'First usable' : complete ? 'Daily' : 'Deepening';
+  // §3.7 by the clerk method: the first usable round's own figures, what a deepening reads path by path (counted from
+  // the ledger), the three options on a stated basis, and the deepening's progress path by path — with what each path
+  // actually read against its plan, and the round against the whole plan, beside the estimate (CKC-13 AC-8).
+  const ledger = app.ledger.ledger(projectId);
+  const figures = firstUsableFigures(store, first, ledger, project);
+  // The plan is counted once for the options, the paths and the deepening as it ran: counting it reads the ledger's totals.
+  const planned = deepeningPlanned(ledger, store);
+  const { options, basis, perMaterial } = clerkDepthOptions(figures, ledger, store, app.keeper.autoLaneCountFor(projectId), planned, project);
+  const asRun = deepeningAsRun(ledger, store, project, planned);
+  // A deepening read by reading assignments (reading.ts): how its reading is counted and its assignments sized.
+  const reading = rounds.filter((r) => r.kind === 'Deepen' && r.reading).pop()?.reading ?? null;
+  const deepening: DeepeningPlan = { paths: deepeningReads(ledger, store, planned), focused: focusedCovers(store), basis, progress: asRun.progress, actual: asRun.actual, ...(reading ? { readingBasis: readingBasisText(reading) } : {}) };
+  const chosen = options.find((o) => o.depth === depth);
+  // Under way, what remains of a deepening read by assignments is what its paths have not accounted for yet.
+  const open = reading ? asRun.progress.reduce((n, p) => n + (p.reading?.open ?? 0), 0) : null;
+  // What waits for the next round, and every material's organizing level (§1.11; CKC-07 AC-1, AC-10; CKC-13 AC-8): from
+  // the rounds, the jobs' recorded calls, the drafts and the rules. Both used to be written empty on every pass, which
+  // wiped what the watcher and intake had listed and left the level table blank (QC AY B1, B8).
+  const materials = listMaterials(store, project);
+  // Before `Start` nothing is taken in and nothing counts as waiting (D105; CKC-13 AC-20).
+  // D107: what waits for a table project is what its table is behind: the commits since its asOf and the owner's messages
+  // since it was filled in (table-follow-up.ts `tablePending`); no material level is pending, so no entry shows `Update pending`.
+  const found = project.takenOverByTable ? { pending: tablePending(app, project), keys: new Set<string>(), fresh: new Map() } : clerkPending(store, project, app.pendingChanges(projectId), materials);
+  const waiting = notStarted ? { ...found, pending: [], keys: new Set<string>() } : found;
+  const { pending, keys: pendingKeys } = waiting;
+  const { levels, sampled, readInPart, historyNotOrganized } = clerkLevels(store, project, pendingKeys, materials);
+  // The entries what waits affects show `Update pending` from the same list (§1.11; CKC-07 AC-10), so the marks and the
+  // coverage agree: what a round took in leaves both at once. A failure here never keeps the coverage from being written.
+  try { refreshUpdatePending(app, projectId, waiting); } catch (e) { console.warn(`[update pending ${projectId}] ${(e as Error).message}`); }
+  const status: TakeoverStatus = {
+    depth: depth ?? 'Depth not chosen', stage,
+    firstUsable: { startedAt: first?.startedAt ?? project.createdAt, completedAt: firstDone ? first!.endedAt : null, minutes: figures.minutes, byKind: figures.byKind, ownerWords: figures.ownerWords },
+    levels, readInPart, sampled,
+    remaining: stage === 'Deepening' && chosen && chosen.depth !== 'First picture only'
+      ? open !== null && perMaterial
+        ? { materials: open, minutes: Math.round((open * perMaterial.minutes) / Math.max(1, app.keeper.autoLaneCountFor(projectId))), cost: perMaterial.cost == null ? null : Math.round(open * perMaterial.cost * 100) / 100 }
+        : { materials: chosen.toOrganize, minutes: chosen.minutes, cost: chosen.cost }
+      : null,
+    options, rates: { basis, msPerChar: 0, costPerChar: null, perMaterial },
+    // What history is still not read for meaning, counted from the levels of the history-tier materials whatever the
+    // depth (§3.7 stage 5 lists the rest). It used to be 0 by definition once a Full deepening was done.
+    historyNotOrganized,
+    noteId: null, deepening,
+  };
+  // A table follow-up's session (D107) is organizing too, though it is no step of a round.
+  const running = store.jobs.filter((j) => (Boolean(j.step) || isTableJob(j)) && ACTIVE_STATUSES.includes(j.status));
+  // Every job of a round's step that did not finish, whether the program runs it again, it waits for the owner, or it is
+  // listed and the round went on — or closed — without it (Spec §3.10: 列入覆盖情况的失败清单并写明原因，不静默跳过). It
+  // leaves the list when a run again finishes it.
+  const failed = store.jobs.filter((j) => Boolean(j.step) && (j.status === 'Failed' || j.status === 'Stopped') && store.clerkRounds.has(j.step!.roundId)).sort((a, b) => a.queuedAt.localeCompare(b.queuedAt));
+  // The last table follow-up, when it did not finish (D107): listed until a later one does.
+  const lastTable = tableJobs(store).pop();
+  const tableFailed = lastTable && (lastTable.status === 'Failed' || lastTable.status === 'Stopped') ? [{ ref: lastTable.id, reason: `${lastTable.scope.label}: ${lastTable.status === 'Failed' ? 'failed' : 'was stopped'} — ${lastTable.error ?? 'no reason recorded'}. Retry or Follow up runs it again`, at: lastTable.endedAt ?? lastTable.queuedAt }] : [];
+  const previous = store.coverage.scopes.find((s) => s.id === 'project');
+  const mainRepo = project.scope.find((i) => i.category === 'Repository' && i.relation !== 'Excluded' && !i.missing);
+  // §1.11's four labels: paused holds the rest; what runs is organizing; what waits with nothing running is pending.
+  const label: CoverageScope['coverage'] = organizingHeld(project) ? 'Organizing paused' : running.length ? 'Organizing' : pending.length ? 'Changes pending' : 'Up to date';
+  // What intake could not take in is carried over; a file too large to read is skipped, not failed (D105) — also one a
+  // home written before that still holds among its failures, which moves over here with no step by the owner.
+  const intake = splitTooLarge((previous?.failed ?? []).filter((f) => !store.jobs.has(f.ref)), previous?.skipped ?? [], excludedLocations(project));
+  const projectScope: CoverageScope = {
+    id: 'project', kind: 'project', label: project.name, coverage: label, asOf: latest(rounds.filter((r) => r.endedAt).pop()?.endedAt, project.takenOverByTable?.at) ?? previous?.asOf ?? null,
+    commit: mainRepo ? gitHead(mainRepo.path) : null, pending, organizing: running.map((j) => ({ kind: 'other', ref: j.id, label: j.scope.label, since: j.startedAt ?? j.queuedAt })),
+    // A round's step that did not finish, and what intake could not take in with its reason (CKC-07 AC-10): intake
+    // writes its own failures, so they are carried over, not wiped by the next pass.
+    failed: notStarted ? [] : [...failed.map((j) => ({ ref: j.id, reason: stepFailureText(store, j, organizingHeld(project)), at: j.endedAt ?? j.queuedAt })), ...tableFailed, ...intake.failed], skipped: notStarted ? [] : intake.skipped, lastRelookAt: previous?.lastRelookAt ?? null,
+  };
+  const pendingByKind: Record<string, number> = {};
+  for (const p of pending) pendingByKind[p.kind] = (pendingByKind[p.kind] ?? 0) + 1;
+  store.setCoverage({ ...store.coverage, scopes: [projectScope, ...store.coverage.scopes.filter((s) => s.id !== 'project')], pendingByKind, takeover: status, lastFollowUp: lastFollowUp(store), state: notStarted ? 'Not organized yet' : complete ? 'Takeover complete' : 'Initial model', updatedAt: new Date().toISOString() }, { jobId: null, summary: 'Coverage updated' });
+}
+
+/** The later of two times, either of which may be absent: a table's filling-in counts as the picture's time (D107). */
+const latest = (a: string | null | undefined, b: string | null | undefined): string | null => (a && b ? (a > b ? a : b) : a ?? b ?? null);
+
+/**
+ * The last Follow up round that closed, for the top bar (§6.2): whether it found anything new, in one line. When it did
+ * not, this is where "the last round found nothing new" is said (CKC-07 AC-27, CKC-24 AC-15); when it did, its item is
+ * in `Notes (attention)`. A result closed before rounds counted their news says nothing here.
+ */
+function lastFollowUp(store: ProjectStore): NonNullable<Coverage['lastFollowUp']> | null {
+  const record = store.rounds.filter((r) => r.endedAt !== null && r.result !== null).sort((a, b) => (b.endedAt ?? '').localeCompare(a.endedAt ?? ''))[0];
+  if (!record?.result?.news) return null;
+  const news = record.result!.news!;
+  const clerk = store.clerkRounds.find((c) => c.followUpRoundId === record.id);
+  return { recordId: record.id, round: clerk?.number ?? record.number, endedAt: record.endedAt!, nothingNew: news.nothingNew, statement: news.nothingNew ? 'The last Follow up round found nothing new' : `The last Follow up round: ${news.statement}` };
+}