agent-horde 0.1.5 → 0.2.0

package/src/dashboard.ts

@@ -1,7 +1,6 @@
 import * as http from "node:http";
 import {
   DashboardError,
-  latestRunId,
   listRunSessions,
   listRuns,
   loadBoard,
@@ -18,10 +17,22 @@ import {
   loadResources,
   loadSessionEntry,
   loadSessionTranscript,
+  loadSwarm,
+  loadSwarmBoard,
+  loadSwarmClaims,
+  loadSwarmCollaboration,
+  loadSwarmFacts,
+  loadSwarmFile,
+  loadSwarmFindings,
+  loadSwarmGraph,
+  loadSwarmIdeas,
+  loadSwarmResources,
   loadTranscript,
   loadTranscriptEntry,
   MEMBER_RE,
-  RUN_ID_RE,
+  requireRun,
+  swarmHordes,
+  swarmOfRun,
 } from "./dashboard-data.js";
 import type { DashboardSource, GraphView } from "./dashboard-data.js";
 import {
@@ -42,10 +53,19 @@ import {
   renderRunOverview,
   renderResources,
   renderSessions,
+  renderSwarm,
+  renderSwarmBoard,
+  renderSwarmClaims,
+  renderSwarmCollaboration,
+  renderSwarmFacts,
+  renderSwarmFindings,
+  renderSwarmGraph,
+  renderSwarmIdeas,
+  renderSwarmResources,
   renderTranscript,
   renderTranscriptEntry,
 } from "./dashboard-html.js";
-import type { RenderContext } from "./dashboard-html.js";
+import type { PageKind, RenderContext, Scope } from "./dashboard-html.js";
 import { collect, exportDashboard } from "./dashboard-export.js";
 import type { ExportPage } from "./dashboard-export.js";
 
@@ -72,6 +92,10 @@ interface Route {
   live: (vm: unknown, src: DashboardSource, params: string[], query: URLSearchParams) => boolean;
   load: (src: DashboardSource, params: string[], query: URLSearchParams) => unknown;
   render: (vm: never, ctx: RenderContext) => string;
+  /** What the page is about; params[0] is the run or swarm id for those scopes. */
+  scope: "project" | "run" | "swarm";
+  /** Which page-row item the page is, so the nav can mark it and horde tabs can keep it. */
+  page: PageKind;
   /** Serve the renderer's output as text/plain instead of a page. */
   text?: boolean;
 }
@@ -103,12 +127,6 @@ function queryFrom(query: URLSearchParams): number | "last" {
   return query.get("from") === "last" ? "last" : queryInt(query, "from", 0, 999_999_999, 0);
 }
 
-function queryRun(query: URLSearchParams): string {
-  const value = query.get("run") ?? "all";
-  if (value !== "all" && !RUN_ID_RE.test(value)) throw new DashboardError(400, `invalid run: ${value}`);
-  return value;
-}
-
 function queryOwner(query: URLSearchParams): string | undefined {
   const value = query.get("owner");
   if (value === null || value === "") return undefined;
@@ -116,17 +134,39 @@ function queryOwner(query: URLSearchParams): string | undefined {
   return value;
 }
 
+function queryOrder(query: URLSearchParams): "newest" | "oldest" {
+  return queryEnum(query, "order", ["newest", "oldest"] as const, "newest");
+}
+
+function queryView(query: URLSearchParams): "list" | "clusters" {
+  return queryEnum(query, "view", ["list", "clusters"] as const, "list");
+}
+
 function isActive(src: DashboardSource, runId: string | undefined): boolean {
-  return runId !== undefined && src.getActive()?.id === runId;
+  return runId !== undefined && src.getActive().some((run) => run.id === runId);
 }
 
 function isFinalizing(src: DashboardSource, runId: string | undefined): boolean {
-  return runId !== undefined && src.getFinalizing?.()?.id === runId;
+  return runId !== undefined && (src.getFinalizing?.() ?? []).some((run) => run.id === runId);
+}
+
+function isRunLive(src: DashboardSource, runId: string): boolean {
+  return isActive(src, runId) || isFinalizing(src, runId);
+}
+
+/** A swarm page is live while the swarm is in memory: members running or the merge step pending. */
+function isSwarmLive(src: DashboardSource, swarmId: string | undefined): boolean {
+  return swarmId !== undefined && src.getSwarm?.()?.id === swarmId;
+}
+
+/** The project ledgers change while a single run (one writing to the project `.horde`) is live. */
+function isProjectLive(src: DashboardSource): boolean {
+  return src.getActive().some((run) => run.hordeDir === src.hordeDir);
 }
 
 function memberRunning(src: DashboardSource, runId: string, member: string): boolean {
-  const state = src.getActive()?.members.find((m) => m.name === member);
-  return isActive(src, runId) && state !== undefined && (state.status === "running" || state.status === "starting");
+  const state = src.getActive().find((run) => run.id === runId)?.members.find((m) => m.name === member);
+  return state !== undefined && (state.status === "running" || state.status === "starting");
 }
 
 const p = (params: string[], i: number): string => params[i] ?? "";
@@ -142,84 +182,112 @@ function graphView(query: URLSearchParams): GraphView {
   };
 }
 
-const ROUTES: Route[] = [
-  {
-    pattern: /^\/$/,
-    live: () => true,
-    load: (src) => listRuns(src),
-    render: renderRunIndex,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)$/,
-    live: (_vm, src, params) => isActive(src, p(params, 0)) || isFinalizing(src, p(params, 0)),
-    load: (src, params) => loadRunOverview(src, p(params, 0)),
-    render: renderRunOverview,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)\/collaboration$/,
-    live: (_vm, src, params) => isActive(src, p(params, 0)),
-    load: (src, params, query) => loadCollaboration(src, p(params, 0), queryInt(query, "from", 0, 999_999_999, 0)),
-    render: renderCollaboration,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)\/graph$/,
-    live: (_vm, src, params) => isActive(src, p(params, 0)) || isFinalizing(src, p(params, 0)),
-    load: (src, params, query) => loadRunGraph(src, p(params, 0), graphView(query)),
-    render: renderGraph,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)\/graph\.mmd$/,
-    live: () => false,
-    load: (src, params) => loadRunGraph(src, p(params, 0), { width: GRAPH_WIDTH_DEFAULT, from: 0, to: 0 }),
-    render: renderGraphMermaid,
-    text: true,
-  },
+const LEDGERS = ["ideas", "board", "findings", "claims", "facts", "resources"] as const;
+type Ledger = (typeof LEDGERS)[number];
+
+/** A ledger page for the project (`run` undefined) or for one run, which may be a swarm horde. */
+const LEDGER_LOAD: Record<Ledger, (src: DashboardSource, run: string | undefined, query: URLSearchParams) => unknown> = {
+  ideas: (src, run, query) => loadIdeas(src, queryOwner(query), run),
+  board: (src, run, query) => loadBoard(src, run ?? "all", queryOrder(query)),
+  findings: (src, run, query) => loadFindings(src, run ?? "all", queryView(query), queryIds(query, "open")),
+  claims: (src, run) => loadClaims(src, run),
+  facts: (src, run) => loadFacts(src, run),
+  resources: (src, run) => loadResources(src, run),
+};
+
+const SWARM_LEDGER_LOAD: Record<Ledger, (src: DashboardSource, swarmId: string, query: URLSearchParams) => unknown> = {
+  ideas: (src, swarmId, query) => loadSwarmIdeas(src, swarmId, queryOwner(query)),
+  board: (src, swarmId, query) => loadSwarmBoard(src, swarmId, queryOrder(query)),
+  findings: (src, swarmId, query) => loadSwarmFindings(src, swarmId, queryView(query), queryIds(query, "open")),
+  claims: (src, swarmId) => loadSwarmClaims(src, swarmId),
+  facts: (src, swarmId) => loadSwarmFacts(src, swarmId),
+  resources: (src, swarmId) => loadSwarmResources(src, swarmId),
+};
+
+const LEDGER_RENDER: Record<Ledger, Route["render"]> = {
+  ideas: renderIdeas, board: renderBoard, findings: renderFindings, claims: renderClaims, facts: renderFacts, resources: renderResources,
+};
+
+const SWARM_LEDGER_RENDER: Record<Ledger, Route["render"]> = {
+  ideas: renderSwarmIdeas, board: renderSwarmBoard, findings: renderSwarmFindings,
+  claims: renderSwarmClaims, facts: renderSwarmFacts, resources: renderSwarmResources,
+};
+
+/** Every ledger page in its three scopes: `/<ledger>`, `/runs/<id>/<ledger>`, `/swarms/<id>/<ledger>`. */
+function ledgerRoutes(): Route[] {
+  return LEDGERS.flatMap((kind): Route[] => [
+    {
+      pattern: new RegExp(`^/${kind}$`), scope: "project", page: kind,
+      live: (_vm, src) => isProjectLive(src),
+      load: (src, _params, query) => LEDGER_LOAD[kind](src, undefined, query),
+      render: LEDGER_RENDER[kind],
+    },
+    {
+      pattern: new RegExp(`^/runs/([^/]+)/${kind}$`), scope: "run", page: kind,
+      live: (_vm, src, params) => isRunLive(src, p(params, 0)),
+      load: (src, params, query) => {
+        requireRun(src, p(params, 0));
+        return LEDGER_LOAD[kind](src, p(params, 0), query);
+      },
+      render: LEDGER_RENDER[kind],
+    },
+    {
+      pattern: new RegExp(`^/swarms/([^/]+)/${kind}$`), scope: "swarm", page: kind,
+      live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+      load: (src, params, query) => SWARM_LEDGER_LOAD[kind](src, p(params, 0), query),
+      render: SWARM_LEDGER_RENDER[kind],
+    },
+  ]);
+}
+
+/** Pages that exist for one run only: members, logs, transcripts, sessions, run files. */
+const RUN_DETAIL_ROUTES: Route[] = [
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)$/, scope: "run", page: "other",
     live: (_vm, src, params) => memberRunning(src, p(params, 0), p(params, 1)),
     load: (src, params, query) => loadMemberDetail(src, p(params, 0), p(params, 1), queryInt(query, "tail", 1, 2000, 60)),
     render: renderMemberDetail,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/log$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/log$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params, query) => loadMemberLog(src, p(params, 0), p(params, 1), queryInt(query, "tail", 0, 2000, 500)),
     render: renderMemberLog,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript$/, scope: "run", page: "other",
     live: (_vm, src, params, query) => query.get("from") === "last" && memberRunning(src, p(params, 0), p(params, 1)),
     load: (src, params, query) =>
       loadTranscript(src, p(params, 0), p(params, 1), queryFrom(query), queryInt(query, "n", 1, 200, 50)),
     render: renderTranscript,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript\/(\d{1,9})$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript\/(\d{1,9})$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params) => loadTranscriptEntry(src, p(params, 0), p(params, 1), Number(p(params, 2))),
     render: renderTranscriptEntry,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/sessions$/,
+    pattern: /^\/runs\/([^/]+)\/sessions$/, scope: "run", page: "other",
     live: (_vm, src, params) => isActive(src, p(params, 0)),
     load: (src, params) => listRunSessions(src, p(params, 0)),
     render: renderSessions,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)$/,
+    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params, query) =>
       loadSessionTranscript(src, p(params, 0), p(params, 1), queryFrom(query), queryInt(query, "n", 1, 200, 50)),
     render: renderTranscript,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)\/(\d{1,9})$/,
+    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)\/(\d{1,9})$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params) => loadSessionEntry(src, p(params, 0), p(params, 1), Number(p(params, 2))),
     render: renderTranscriptEntry,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/files\/([^/]+)$/,
+    pattern: /^\/runs\/([^/]+)\/files\/([^/]+)$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params) => {
       const vm = loadRunFile(src, p(params, 0), p(params, 1));
@@ -228,52 +296,70 @@ const ROUTES: Route[] = [
     },
     render: renderFile,
   },
+];
+
+const ROUTES: Route[] = [
   {
-    pattern: /^\/ideas$/,
+    pattern: /^\/$/, scope: "project", page: "overview",
     live: () => true,
-    load: (src, _params, query) => loadIdeas(src, queryOwner(query)),
-    render: renderIdeas,
+    load: (src) => listRuns(src),
+    render: renderRunIndex,
   },
   {
-    pattern: /^\/board$/,
-    live: () => true,
-    load: (src, _params, query) =>
-      loadBoard(src, queryRun(query), queryEnum(query, "order", ["newest", "oldest"] as const, "newest")),
-    render: renderBoard,
+    pattern: /^\/runs\/([^/]+)$/, scope: "run", page: "overview",
+    live: (_vm, src, params) => isRunLive(src, p(params, 0)),
+    load: (src, params) => loadRunOverview(src, p(params, 0)),
+    render: renderRunOverview,
   },
   {
-    pattern: /^\/findings$/,
-    live: () => true,
-    load: (src, _params, query) =>
-      loadFindings(
-        src,
-        queryRun(query),
-        queryEnum(query, "view", ["list", "clusters"] as const, "list"),
-        queryIds(query, "open"),
-      ),
-    render: renderFindings,
+    pattern: /^\/runs\/([^/]+)\/collaboration$/, scope: "run", page: "collaboration",
+    live: (_vm, src, params) => isActive(src, p(params, 0)),
+    load: (src, params, query) => loadCollaboration(src, p(params, 0), queryInt(query, "from", 0, 999_999_999, 0)),
+    render: renderCollaboration,
   },
   {
-    pattern: /^\/claims$/,
-    live: () => true,
-    load: (src) => loadClaims(src),
-    render: renderClaims,
+    pattern: /^\/runs\/([^/]+)\/graph$/, scope: "run", page: "graph",
+    live: (_vm, src, params) => isRunLive(src, p(params, 0)),
+    load: (src, params, query) => loadRunGraph(src, p(params, 0), graphView(query)),
+    render: renderGraph,
   },
   {
-    pattern: /^\/facts$/,
-    live: () => true,
-    load: (src, _params, query) => {
-      const run = queryRun(query);
-      return loadFacts(src, run === "all" ? undefined : run);
-    },
-    render: renderFacts,
+    pattern: /^\/runs\/([^/]+)\/graph\.mmd$/, scope: "run", page: "graph",
+    live: () => false,
+    load: (src, params) => loadRunGraph(src, p(params, 0), { width: GRAPH_WIDTH_DEFAULT, from: 0, to: 0 }),
+    render: renderGraphMermaid,
+    text: true,
   },
+  ...RUN_DETAIL_ROUTES,
   {
-    pattern: /^\/resources$/,
-    live: () => true,
-    load: (src) => loadResources(src),
-    render: renderResources,
+    pattern: /^\/swarms\/([^/]+)$/, scope: "swarm", page: "overview",
+    live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+    load: (src, params) => loadSwarm(src, p(params, 0)),
+    render: renderSwarm,
+  },
+  {
+    pattern: /^\/swarms\/([^/]+)\/collaboration$/, scope: "swarm", page: "collaboration",
+    live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+    load: (src, params) => loadSwarmCollaboration(src, p(params, 0)),
+    render: renderSwarmCollaboration,
+  },
+  {
+    pattern: /^\/swarms\/([^/]+)\/graph$/, scope: "swarm", page: "graph",
+    live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+    load: (src, params, query) => loadSwarmGraph(src, p(params, 0), graphView(query)),
+    render: renderSwarmGraph,
   },
+  {
+    pattern: /^\/swarms\/([^/]+)\/files\/([^/]+)$/, scope: "swarm", page: "other",
+    live: () => false,
+    load: (src, params) => {
+      const vm = loadSwarmFile(src, p(params, 0), p(params, 1));
+      if (!vm.present) throw new DashboardError(404, `${vm.name}.md has not been written yet`);
+      return vm;
+    },
+    render: renderFile,
+  },
+  ...ledgerRoutes(),
 ];
 
 function baseHeaders(): Record<string, string> {
@@ -329,12 +415,36 @@ function routeMatch(pathname: string): { route: Route; params: string[] } | unde
   return undefined;
 }
 
-/** The run this page belongs to, and the run the nav's collaboration and graph links target. */
-function runContext(src: DashboardSource, url: URL, params: string[]): Pick<RenderContext, "runId" | "navRun"> {
-  const runId = RUN_ID_RE.test(params[0] ?? "") ? params[0] : undefined;
-  const filterRun = url.searchParams.get("run");
-  const navRun = runId ?? (filterRun && RUN_ID_RE.test(filterRun) ? filterRun : undefined) ?? latestRunId(src);
-  return { runId, navRun };
+/**
+ * The scope the route declares, filled in from its id. A horde run also carries its swarm's hordes
+ * for the tabs; a swarm that cannot be read leaves the run without tabs rather than failing the page.
+ */
+function scopeOf(src: DashboardSource, route: Route, params: string[]): Scope {
+  if (route.scope === "project") return { kind: "project" };
+  const id = p(params, 0);
+  if (route.scope === "swarm") return { kind: "swarm", swarmId: id, hordes: swarmHordes(src, id) };
+  const swarm = swarmOfRun(id);
+  if (!swarm) return { kind: "run", runId: id };
+  try {
+    return { kind: "run", runId: id, swarm: { id: swarm.swarmId, hordes: swarmHordes(src, swarm.swarmId) } };
+  } catch {
+    return { kind: "run", runId: id };
+  }
+}
+
+/** The page's place in the nav: its scope and which page-row item it is. */
+/** A swarm (not a swarm of one, which writes the project ledgers) the parent still holds in memory. */
+function liveSwarmOf(src: DashboardSource): RenderContext["liveSwarm"] {
+  const swarm = src.getSwarm?.();
+  if (!swarm || swarm.dir === undefined) return undefined;
+  const running = src.getActive().some((run) => swarmOfRun(run.id)?.swarmId === swarm.id);
+  return { id: swarm.id, finishing: !running };
+}
+
+/** The page's place in the nav: its scope, which page-row item it is, and a live swarm for project pages. */
+function pageContext(src: DashboardSource, route: Route, params: string[]): Pick<RenderContext, "scope" | "pageKind" | "liveSwarm"> {
+  const liveSwarm = route.scope === "project" ? liveSwarmOf(src) : undefined;
+  return { scope: scopeOf(src, route, params), pageKind: route.page, liveSwarm };
 }
 
 /** The export costs seconds of work per request, so pages from other sites may not start one. */
@@ -355,7 +465,7 @@ function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderC
   const on = live && refreshParam !== "0";
   const pageCtx: RenderContext = {
     ...ctx,
-    ...runContext(src, url, params),
+    ...pageContext(src, route, params),
     refresh: live ? { on, toggleHref: refreshToggle(url, on), seconds: REFRESH_SECONDS } : undefined,
   };
   const body = route.render(vm as never, pageCtx);
@@ -365,13 +475,13 @@ function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderC
 
 /** One page of the static export; errors become pages so no exported link dangles. */
 function exportPage(src: DashboardSource, url: URL): ExportPage {
-  const ctx: RenderContext = { activeId: src.getActive()?.id, href: url.pathname + url.search, export: true };
+  const ctx: RenderContext = { href: url.pathname + url.search, export: true };
   try {
     const matched = routeMatch(url.pathname);
     if (!matched) throw new DashboardError(404, `no such page: ${url.pathname}`);
     const { route, params } = matched;
     const vm = route.load(src, params, url.searchParams);
-    return { body: route.render(vm as never, { ...ctx, ...runContext(src, url, params) }), text: route.text };
+    return { body: route.render(vm as never, { ...ctx, ...pageContext(src, route, params) }), text: route.text };
   } catch (error) {
     const status = error instanceof DashboardError ? error.status : 500;
     const message = error instanceof DashboardError ? error.message : `dashboard error: ${error instanceof Error ? error.message : String(error)}`;
@@ -414,7 +524,6 @@ function exportResponse(src: DashboardSource, url: URL, ctx: RenderContext): Das
 export function routeRequest(src: DashboardSource, method: string, url: URL, host: string | undefined, fetchSite?: string): DashboardResponse {
   const json = url.pathname === "/api" || url.pathname.startsWith("/api/");
   const ctx: RenderContext = {
-    activeId: src.getActive()?.id,
     origin: host ? `http://${host}` : undefined,
     href: url.pathname + url.search,
   };

package/src/ledger/collaboration.ts

@@ -46,6 +46,8 @@ export interface ArtifactRecord {
   snapshot: string;
   criteria: string;
   dependencies: Array<{ target: string; revision: string }>;
+  /** The owner's statement of what a republish changed, required once other artifacts pin it. */
+  changeNote?: string;
   /** Projected from the publishing event; absent in hand-built records. */
   publishedAt?: string;
 }
@@ -57,9 +59,14 @@ export interface ReviewRecord {
   verdict: "supports" | "partially-supports" | "refutes" | "inconclusive";
   support: string;
   checked: string;
+  /** Gaps inside the target's stated claim or criteria; non-empty keeps acceptance open. */
   unchecked: string;
+  /** Disclosures outside the criteria; recorded on the acceptance as limits, never blockers. */
+  limits?: string;
   text: string;
   evidence: string[];
+  /** The reviewer's earlier review of a previous revision that this one carries forward. */
+  reattests?: string;
 }
 export interface ResourceContract {
   target: string;
@@ -153,12 +160,35 @@ export function blockingMessages(state: CollaborationState): PeerMessage[] {
   return state.messages.filter((m) => m.blocking && m.state !== "resolved");
 }
 
-export function artifactAccepted(state: CollaborationState, artifact: ArtifactRecord): boolean {
-  if (blockingMessages(state).some((m) => m.target === artifact.id)) return false;
-  const reviews = state.reviews.filter((r) => r.target === artifact.id && r.revision === artifact.hash);
+/** Each non-owner's latest review of the artifact's current revision. */
+export function latestArtifactReviews(state: CollaborationState, artifact: ArtifactRecord): ReviewRecord[] {
   const latest = new Map<string, ReviewRecord>();
-  for (const review of reviews) latest.set(review.actor, review);
-  if ([...latest.values()].some((r) => r.verdict === "refutes")) return false;
+  for (const review of state.reviews) {
+    if (review.target === artifact.id && review.revision === artifact.hash && review.actor !== artifact.owner) latest.set(review.actor, review);
+  }
+  return [...latest.values()];
+}
+
+function acceptingReview(artifact: ArtifactRecord, review: ReviewRecord): boolean {
   const methods = artifact.kind === "document" ? ["sourced", "derived", "tested", "reproduced"] : ["tested", "reproduced"];
-  return [...latest.values()].some((r) => r.actor !== artifact.owner && r.verdict === "supports" && !r.unchecked && methods.includes(r.support));
+  return review.verdict === "supports" && !review.unchecked && methods.includes(review.support);
+}
+
+export function artifactAccepted(state: CollaborationState, artifact: ArtifactRecord): boolean {
+  if (blockingMessages(state).some((m) => m.target === artifact.id)) return false;
+  const latest = latestArtifactReviews(state, artifact);
+  if (latest.some((r) => r.verdict === "refutes")) return false;
+  return latest.some((r) => acceptingReview(artifact, r));
+}
+
+/** Limits the accepting reviews disclosed outside the criteria, each named with its review. */
+export function artifactLimits(state: CollaborationState, artifact: ArtifactRecord): string[] {
+  return latestArtifactReviews(state, artifact)
+    .filter((r) => acceptingReview(artifact, r) && r.limits?.trim())
+    .map((r) => `${r.id} (${r.actor}): ${r.limits?.trim()}`);
+}
+
+/** Reviews of the current revision that left in-criteria scope unchecked: coverage debt, named. */
+export function partialArtifactReviews(state: CollaborationState, artifact: ArtifactRecord): ReviewRecord[] {
+  return latestArtifactReviews(state, artifact).filter((r) => r.verdict !== "refutes" && r.unchecked.trim());
 }

package/src/ledger/facts.ts

@@ -1,8 +1,11 @@
 import * as fs from "node:fs";
 import { oneLine } from "../format.js";
+import { listClaims } from "./claims.js";
+import { CLUSTER_THRESHOLD } from "./clusters.js";
 import { appendEntry, hordePaths, requireText, writeFileAtomic } from "./files.js";
+import { listIdeas } from "./ideas.js";
 import { withHordeLock } from "./lock.js";
-import { bestTextMatch, factAnchors, salientTokens, stripLeadingId } from "./text-match.js";
+import { bestTextMatch, factAnchors, hardOverlap, salientTokens, stripLeadingId, textOverlap } from "./text-match.js";
 
 export interface FactEntry {
   id: number;
@@ -10,6 +13,8 @@ export interface FactEntry {
   author: string;
   deltaOf?: number | undefined;
   corroborators: string[];
+  /** The open idea (`#12`) or contested claim (`C3`) that was still auditing the subject when the fact was filed. */
+  provisionalOn?: string | undefined;
   headingLine: number;
 }
 
@@ -23,18 +28,58 @@ export function parseFacts(content: string): FactEntry[] {
     const meta = match[4] ?? "";
     const delta = /delta=#?T?(\d+)/.exec(meta);
     const corr = /corr=([^\s]+)/.exec(meta);
+    const prov = /prov=([^\s]+)/.exec(meta);
     facts.push({
       id: Number(match[1]),
       text: match[2] ?? "",
       author: match[3] ?? "",
       deltaOf: delta ? Number(delta[1]) : undefined,
       corroborators: corr?.[1] ? corr[1].split(",").map((s) => s.trim()).filter(Boolean) : [],
+      provisionalOn: prov?.[1],
       headingLine: lineIndex,
     });
   });
   return facts;
 }
 
+/**
+ * A fact asserting what an open idea is still auditing, or what a contested claim disputes, is
+ * provisional: it is recorded, but the answer may not quote it as settled until the idea closes
+ * or the claim resolves. Returns the subject it is provisional on, if any.
+ */
+function provisionalSubject(hordeDir: string, text: string): string | undefined {
+  const matches = (candidates: string[]): number | undefined => {
+    const match = textOverlap(candidates, text);
+    if (!match) return undefined;
+    return hardOverlap(match) || Math.max(match.jaccard, match.overlap) >= CLUSTER_THRESHOLD ? match.index : undefined;
+  };
+  const open = listIdeas(hordeDir).filter((idea) => idea.mark === " " || idea.mark === "~");
+  const idea = matches(open.map((entry) => entry.text));
+  if (idea !== undefined) return `#${open[idea]?.id}`;
+  const contested = listClaims(hordeDir).filter((claim) => claim.state === "contested");
+  const claim = matches(contested.map((entry) => entry.statement));
+  return claim === undefined ? undefined : `C${contested[claim]?.id}`;
+}
+
+/** Whether a fact's provisional subject is still open: an unclosed idea or a still-contested claim. */
+export function factUnsettled(hordeDir: string, fact: FactEntry): boolean {
+  if (!fact.provisionalOn) return false;
+  if (fact.provisionalOn.startsWith("#")) {
+    const idea = listIdeas(hordeDir).find((entry) => entry.id === Number(fact.provisionalOn?.slice(1)));
+    return idea !== undefined && (idea.mark === " " || idea.mark === "~");
+  }
+  const claim = listClaims(hordeDir).find((entry) => entry.id === Number(fact.provisionalOn?.slice(1)));
+  return claim?.state === "contested";
+}
+
+/** T# ids a text quotes whose provisional subject has not closed, each named with that subject. */
+export function unsettledFactCitations(hordeDir: string, text: string): string[] {
+  const cited = new Set([...text.matchAll(/\bT(\d+)\b/g)].map((m) => Number(m[1])));
+  return listFacts(hordeDir)
+    .filter((fact) => cited.has(fact.id) && factUnsettled(hordeDir, fact))
+    .map((fact) => `T${fact.id} (provisional on ${fact.provisionalOn})`);
+}
+
 /** Record a second reporter of the same fact on its heading, mirroring findings. */
 function addFactCorroborator(content: string, entry: FactEntry, author: string): string {
   if (entry.author === author || entry.corroborators.includes(author)) return content;
@@ -46,9 +91,10 @@ function addFactCorroborator(content: string, entry: FactEntry, author: string):
   return lines.join("\n");
 }
 
-function factEntry(author: string, text: string, id: number, deltaOf?: number): string {
+function factEntry(author: string, text: string, id: number, deltaOf?: number, provisionalOn?: string): string {
   const delta = deltaOf !== undefined ? `  delta=#T${deltaOf}` : "";
-  return `\n- [T${id}] ${text}  @${author}${delta}\n`;
+  const prov = provisionalOn ? `  prov=${provisionalOn}` : "";
+  return `\n- [T${id}] ${text}  @${author}${delta}${prov}\n`;
 }
 
 interface AddFactResult {
@@ -117,8 +163,9 @@ export async function addFact(
       if (hit) return accrete(hit);
     }
     const id = facts.reduce((max, fact) => Math.max(max, fact.id), 0) + 1;
-    appendEntry(factsPath, factEntry(author, body, id, deltaOf));
-    return { fact: { id, text: body, author, deltaOf, corroborators: [], headingLine: -1 } };
+    const provisionalOn = provisionalSubject(hordeDir, body);
+    appendEntry(factsPath, factEntry(author, body, id, deltaOf, provisionalOn));
+    return { fact: { id, text: body, author, deltaOf, corroborators: [], provisionalOn, headingLine: -1 } };
   });
 }
 

package/src/ledger/files.ts

@@ -79,7 +79,12 @@ function writeIfMissing(filePath: string, content: string): void {
 }
 
 export function initHordeDir(cwd: string): string {
-  const paths = hordePaths(path.join(cwd, ".horde"));
+  return initHordeDirAt(path.join(cwd, ".horde"));
+}
+
+/** Create a complete horde directory (ledgers, lock, runs/) at `hordeDir`; existing ledgers are kept. */
+export function initHordeDirAt(hordeDir: string): string {
+  const paths = hordePaths(hordeDir);
   fs.mkdirSync(paths.runs, { recursive: true });
   writeIfMissing(paths.gitignore, "runs/\n");
   writeIfMissing(paths.ideas, IDEAS_HEADER);