projectkeeper 0.0.0-stage → 1.0.0

package/src/context/code-source.ts

@@ -0,0 +1,103 @@
+/**
+ * Source code does not reach an execution agent through ProjectKeeper (D65; Spec §7.1, §7.4, §7.10; CKC-12 AC-43).
+ * What goes instead is where the code is — repository, commit, file, lines — and the agent opens the current version.
+ *
+ * A "code source" is a code file: a file the Keeper judged `Code`, or one whose name says it is program text or build
+ * and tool configuration. A configuration-format file the Keeper judged to be one of the project's intent or record
+ * materials (a plan kept in YAML, a status table in JSON) is that material, not code. Markdown sections, sessions,
+ * commits and command results are never code files; a code block a design document or QC report contains is that
+ * document's own text (Spec §7.1).
+ *
+ * The Keeper's own reading of code is not touched by any of this (Spec §7.1): only what is handed to an agent.
+ */
+import type { FileAnchor, Project, Source } from '../model/types.ts';
+import { isWithin, relativeDisplay } from '../util/paths.ts';
+
+const CODE_EXT = new Set([
+  '.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.py', '.pyi', '.rb', '.go', '.rs', '.java', '.kt', '.kts',
+  '.swift', '.dart', '.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx', '.m', '.mm', '.cs', '.fs', '.vb', '.php',
+  '.pl', '.pm', '.lua', '.r', '.scala', '.clj', '.ex', '.exs', '.erl', '.hs', '.ml', '.sql', '.sh', '.bash', '.zsh', '.fish',
+  '.ps1', '.psm1', '.bat', '.cmd', '.css', '.scss', '.sass', '.less', '.vue', '.svelte', '.gradle', '.groovy', '.cmake',
+]);
+const CODE_NAMES = new Set(['makefile', 'dockerfile', 'cmakelists.txt', 'gemfile', 'rakefile', 'podfile', 'jenkinsfile', 'build.bazel', 'workspace']);
+/** Configuration formats: code, unless the Keeper judged the file to be one of the materials below. */
+const CONFIG_EXT = new Set(['.json', '.json5', '.jsonc', '.yaml', '.yml', '.toml', '.xml', '.ini', '.cfg', '.conf', '.properties', '.plist', '.lock', '.env', '.html', '.htm']);
+const CONFIG_NAMES = new Set(['.gitignore', '.gitattributes', '.editorconfig', '.npmrc', '.env.example', '.dockerignore']);
+const MATERIAL_USE = new Set(['Purpose', 'Decision', 'Requirement', 'Design', 'Plan', 'Task', 'Status', 'QC', 'Run result', 'Session']);
+
+/** Whether a file at this path, used as this, is a code file. */
+export function isCodeFile(path: string, usedAs: string | null | undefined): boolean {
+  if (usedAs === 'Code') return true;
+  const base = (path.split(/[\\/]/).pop() ?? '').toLowerCase();
+  const dot = base.lastIndexOf('.');
+  const ext = dot > 0 ? base.slice(dot) : '';
+  if (CODE_EXT.has(ext) || CODE_NAMES.has(base)) return true;
+  if (CONFIG_EXT.has(ext) || CONFIG_NAMES.has(base)) return !(usedAs && MATERIAL_USE.has(usedAs));
+  return false;
+}
+
+export function isCodeSource(s: Pick<Source, 'anchor' | 'usedAs'>): boolean {
+  if (s.anchor.kind !== 'file') return false;
+  if (s.usedAs === 'Code') return true;
+  // A section under a heading is a document's section (the reader splits only Markdown by heading).
+  if (s.anchor.headingPath.length > 0) return false;
+  return isCodeFile(s.anchor.path, s.usedAs);
+}
+
+/**
+ * The same test on what an object page receives for a source: its label (`<path>[ › heading] (Lx–Ly)` for a file) and
+ * how it is used. Anything that is not a file's label is not a code file.
+ */
+export function isCodeLabel(label: string, usedAs: string | null | undefined): boolean {
+  const m = /^(.*) \(L\d+–L\d+\)$/.exec(label);
+  if (!m) return false;
+  if (usedAs === 'Code') return true;
+  if (m[1]!.includes(' › ')) return false;
+  return isCodeFile(m[1]!, usedAs);
+}
+
+export interface CodeLocation {
+  /** The repository or directory of the project scope the file is in, when it is in one. */
+  readonly repo: string | null;
+  /** The file, relative to `repo` with forward slashes, or the whole path when it is in no scope item. */
+  readonly file: string;
+  readonly lines: string;
+  /** The commit the file was read at, when the project has version control. */
+  readonly commit: string | null;
+}
+
+/** Where a file source is: repository, file, lines, and the commit it was read at (Spec §7.1, §7.10). */
+export function fileLocation(project: Project, s: Source): CodeLocation {
+  const a = s.anchor as FileAnchor;
+  const item = project.scope.find((i) => i.id === s.scopeItemId) ?? project.scope.find((i) => i.relation !== 'Excluded' && i.category !== 'Session source' && isWithin(i.path, a.path));
+  const inRepo = item !== undefined && isWithin(item.path, a.path);
+  return { repo: inRepo ? item.path : null, file: inRepo ? relativeDisplay(item.path, a.path) : a.path, lines: `lines ${a.lineStart}–${a.lineEnd}`, commit: s.version.commit };
+}
+
+/** `D:\repo · app/x.ts, lines 3–9, as read at commit abc1234567` */
+export function locationText(loc: CodeLocation): string {
+  return `${loc.repo ? `${loc.repo} · ` : ''}${loc.file}, ${loc.lines}${loc.commit ? `, as read at commit ${loc.commit.slice(0, 10)}` : ''}`;
+}
+
+/** Just the file and lines, for a statement observed in the code: `app/x.ts, lines 3–9`. */
+export function shortLocationText(loc: CodeLocation): string {
+  return `${loc.file}, ${loc.lines}`;
+}
+
+export interface CommitFacts { readonly subject: string; readonly at: string | null; readonly files: readonly string[] }
+/**
+ * What a commit source records: its message, when, and the files it changed. When it was made is the time its anchor
+ * records (sources/gitobs.ts); a commit source written before the anchor carried it gives the `at:` line its excerpt
+ * has. The message and the files are read from the source as the commit reader wrote it (message, then an indented
+ * `files:` list); what is not there is simply left out.
+ */
+export function commitFacts(s: Source): CommitFacts {
+  const lines = s.excerpt.split('\n');
+  const at = s.anchor.kind === 'commit' && s.anchor.at !== undefined ? s.anchor.at : lines.find((l) => l.startsWith('at: '))?.slice(4).trim() ?? null;
+  const start = lines.findIndex((l) => l.trim() === 'files:');
+  const files = start < 0 ? [] : lines.slice(start + 1).filter((l) => /^\s+\S/.test(l)).map((l) => l.trim());
+  return { subject: (lines[0] ?? s.title).trim(), at, files };
+}
+
+/** How an agent is told to read a code file itself (D65). */
+export const OPEN_CURRENT = 'ProjectKeeper gives where code is, not the code: open the current version in the repository and read it there.';

package/src/context/k-briefs.ts

@@ -0,0 +1,114 @@
+/** Text for the agent entry's increment K objects. The server hands these views to the CLI as-is. */
+import type { CodeTerritory, EvidenceRef, Occurred, SemanticPatch } from '../model/k-types.ts';
+import type { BreakpointView, CodeView, SendBackView, TerritoryView } from '../model/views-k.ts';
+import { redactCredentials } from '../sources/anchor.ts';
+
+function safe(text: string): string { return redactCredentials(text).text; }
+
+export function occurredText(value: Occurred): string {
+  if (value.undated) return `Undated · first seen ${value.at.slice(0, 10)}`;
+  const one = (at: string, basis: string, anchor: string | null) => `${basis} ${at}${anchor ? ` (${anchor})` : ''}`;
+  const primary = one(value.at, value.basis, value.anchor);
+  return value.other ? `${primary} · ${one(value.other.at, value.other.basis, value.other.anchor)}` : primary;
+}
+
+function evidenceLines(evidence: readonly EvidenceRef[]): string[] {
+  if (!evidence.length) return ['- None recorded'];
+  return evidence.flatMap((e) => [
+    `- ${e.kind} · ${e.label} (${e.id})${e.occurred ? ` · ${occurredText(e.occurred)}` : ''}`,
+    ...(e.line == null ? [] : [`  Original line: ${e.line}`]),
+  ]);
+}
+
+function finish(lines: (string | null)[]): string { return safe(lines.filter((line) => line !== null).join('\n')); }
+
+export function breakpointBrief(view: BreakpointView, targetName: string): string {
+  return finish([
+    `# Breakpoint · ${view.kind} (${view.id})`,
+    `Where: ${targetName} (${view.targetId})`,
+    `What: ${view.why}`,
+    `Status: ${view.lit ? 'Lit' : view.state === 'Candidate' ? 'Candidate (a lead, not a finding: it lights only after a lane looked for the step and the spot-check confirmed it)' : 'Out'}${view.ownerResponse ? ` · No action needed at ${view.ownerResponse.at}: ${view.ownerResponse.reason}` : ''}`,
+    view.looked ? `Looked for, not found: ${view.looked.where.join('; ')} (${view.looked.at.slice(0, 10)})` : null,
+    `Occurred: ${occurredText(view.since)} (next step became due)`,
+    `Basis: ${view.basis}`,
+    view.sixThing ? `Six thing: ${view.sixThing}` : null,
+    view.sendBackId ? `Send-back: ${view.sendBackId}` : null,
+    '', '## Evidence', ...evidenceLines(view.evidence),
+  ]);
+}
+
+export function sendBackBrief(view: SendBackView, targetName: string): string {
+  return finish([
+    `# Send-back · ${view.id}`,
+    `Where: ${targetName} (${view.targetId})`,
+    `What: ${view.what}`,
+    `Send back to: ${view.to} · ${view.suggestion}`,
+    `Status: ${view.stage}${view.lit ? ' · Open' : ' · Not lit'}${view.ownerResponse ? ` · No action needed at ${view.ownerResponse.at}: ${view.ownerResponse.reason}` : ''}`,
+    `Occurred: ${occurredText(view.occurred)}`,
+    view.returned ? `Returned: ${view.returned.label} · ${occurredText(view.returned.occurred)}` : null,
+    view.closed ? `Closed: ${view.closed.label} · ${occurredText(view.closed.occurred)}` : null,
+    view.sixThing ? `Six thing: ${view.sixThing}` : null,
+    '', '## Evidence', ...evidenceLines(view.evidence),
+    '', '## Copy for agent', view.copyForAgent,
+  ]);
+}
+
+export function patchBrief(patch: SemanticPatch, objectName: (id: string) => string): string {
+  return finish([
+    `# Semantic patch · ${patch.title} (${patch.number}; ${patch.id})`,
+    `Where: ${patch.writtenToFolder ? patch.writtenToFolder.path : 'Workbench only; not written to the project folder'}`,
+    `Status: ${patch.status}${patch.partial ? ' · Partial replacement' : ''}`,
+    `Occurred: ${occurredText(patch.occurred)}`,
+    `Invalidated: ${patch.invalidated}`,
+    `Replaced by: ${patch.replacedBy}`,
+    `Affects: ${patch.affectsText}`,
+    ...patch.affects.map((id) => `- ${objectName(id)} (${id})`),
+    `Must not pass as current: ${patch.mustNotPassAsCurrent}`,
+    '', '## Evidence',
+    'Old anchor:', ...evidenceLines([patch.oldAnchor]),
+    'New anchor:', ...evidenceLines(patch.newAnchor ? [patch.newAnchor] : []),
+    'Decision or commit:', ...evidenceLines(patch.decision ? [patch.decision] : []),
+    'Ledger supersession:', ...evidenceLines([patch.candidate]),
+  ]);
+}
+
+export function territoryBrief(
+  territory: CodeTerritory,
+  objectName: (id: string) => string,
+  ledger: { view: TerritoryView; version: CodeView['version'] } | null,
+  firstSeen: string,
+): string {
+  const view = ledger?.view;
+  const areaId = view?.row.kind === 'area' ? view.row.areaId : territory.areaId;
+  const also = view?.alsoServes.map((a) => ({ id: a.areaId, name: a.areaName })) ?? territory.alsoServes.map((id) => ({ id, name: objectName(id) }));
+  const anomalies = view?.anomalies ?? territory.anomalies;
+  const lines: (string | null)[] = [
+    `# Code territory · ${view?.name ?? territory.name} (${territory.id})`,
+    `What: ${view?.summary ?? territory.summary}`,
+    `Where: ${view?.repo ?? territory.repo}`,
+    ...(view?.paths ?? territory.paths).map((path) => `- ${path}`),
+    `Kind: ${view?.row.kind ?? territory.kind}`,
+    `Main area: ${areaId ? `${objectName(areaId)} (${areaId})` : 'None'}`,
+    `Also serves: ${also.length ? also.map((a) => `${a.name} (${a.id})`).join('; ') : 'None'}`,
+    `Occurred: ${ledger ? occurredText(ledger.version.occurred) : `Undated · first seen ${firstSeen}`}`,
+    `Current state: ${view ? view.currentUse : 'the ledger is not connected yet'}`,
+  ];
+  if (view) {
+    lines.push(
+      `Size: ${view.size.files} files, ${view.size.lines} lines; generated ${view.size.generatedFiles} files, ${view.size.generatedLines} lines`,
+      `Depends on: ${view.dependsOn.join(', ') || 'None'}`,
+      `Depended on by: ${view.dependedBy.join(', ') || 'None'}`,
+      `Built by: ${view.builtBy.map((b) => `${b.label} (${b.workId ?? 'unattributed'}): ${b.files} files; ${b.commits.join(', ')}`).join('; ') || 'None recorded'}`,
+      `Generations: ${view.generations.map((g) => `${g.name}: ${g.share}`).join('; ') || 'None recorded'}`,
+      `Tests: ${view.tests}`,
+      view.lastChange ? `Last change: ${view.lastChange.commit} · ${occurredText(view.lastChange.occurred)} · ${view.lastChange.subject}` : 'Last change: None recorded',
+    );
+  } else lines.push('Size, dependencies, who built it, generations, tests and last change: the ledger is not connected yet');
+  lines.push('', '## Anomalies');
+  if (!anomalies.length) lines.push('- None recorded');
+  else for (const anomaly of anomalies) lines.push(
+    `- ${anomaly.kind} · ${anomaly.text} · ${anomaly.basis}${anomaly.sendBackId ? ` · send-back ${anomaly.sendBackId}` : ''}`,
+    ...evidenceLines(anomaly.evidence).map((line) => `  ${line}`),
+  );
+  return finish(lines);
+}

package/src/context/lineage.ts

@@ -0,0 +1,100 @@
+/**
+ * History in a context pack, given as lineage (Spec §2.11, §7.1; CKC-12 AC-35). D82 withdrew D61's "what exists only in
+ * history enters no context": history is a first-hand source, and what bears on the work is given — marked as history,
+ * saying when, and what replaced it or why it was removed. What remains of D61: what exists only in history (old versions,
+ * deleted files, side branches, material kept for recovery) and objects `Removed` from the project's current version never
+ * appear as current content; replaced and abandoned directions still go to `Do not revive`; a current object that still
+ * rests on a removed one says so on its own row.
+ *
+ * Everything here is what the program already has, read and never inferred:
+ * - the assets: the change records (the program records one per deletion, with the commit that deleted the material —
+ *   intake/removal.ts), the round judgements that closed an item as superseded by a later change (§2.10), the sources a
+ *   rule or the history reading made `History only`, and the objects that became `Removed`;
+ * - the ledger's `How it got here` (ledger/views.ts `lineageView`): versions, the lines that say something was superseded,
+ *   deletions, side branches, the plans and commits that name the object, where it stands now — when the project has a
+ *   ledger.
+ */
+import type { ChangeItem, ChangeRecord } from '../model/types.ts';
+import type { LineageStepView } from '../model/views-k.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import type { Ledger } from '../ledger/index.ts';
+import { lineageView } from '../ledger/views.ts';
+import { itemsOf } from '../keeper/adjustment.ts';
+
+/** How an object left the project's current version, as the change records give it. */
+export interface Removal {
+  readonly at: string;
+  readonly changeId: string;
+  readonly effect: string;
+  readonly title: string;
+  readonly why: string | null;
+  readonly sourceIds: readonly string[];
+}
+
+/**
+ * The change that took an object out of the current version: the item that recorded it `Removed` (the program writes one
+ * per deletion, dated by the commit that deleted the material and giving that commit's reason), else the latest item that
+ * gave it up or replaced it. Null when the records hold neither — the pack then says the records do not say when.
+ */
+export function removalOf(store: ProjectStore, id: string): Removal | null {
+  let removed: { c: ChangeRecord; it: ChangeItem } | null = null;
+  let other: { c: ChangeRecord; it: ChangeItem } | null = null;
+  for (const c of store.changes.all()) {
+    for (const it of itemsOf(c)) {
+      if (!it.affects.includes(id)) continue;
+      if (it.effect === 'Removed') { if (!removed || it.at >= removed.it.at) removed = { c, it }; }
+      else if ((it.effect === 'Abandoned' || it.effect === 'Replaced') && (!other || it.at >= other.it.at)) other = { c, it };
+    }
+  }
+  const hit = removed ?? other;
+  return hit ? { at: hit.it.at, changeId: hit.c.id, effect: hit.it.effect, title: hit.it.title, why: hit.it.why ?? null, sourceIds: hit.it.sourceIds } : null;
+}
+
+/** Why a change item that bears on the work is history rather than a change in force. */
+export type HistoryReason =
+  /** A later change superseded it for an object it reached (§2.10): the round closed the item with that change's id. */
+  | { readonly kind: 'superseded'; readonly byChangeId: string | null; readonly reason: string }
+  /** Every source it rests on exists only in history (§1.2 `History only`). */
+  | { readonly kind: 'history only' }
+  /** Everything it set down has since been replaced, given up or removed. */
+  | { readonly kind: 'overtaken' };
+
+export interface HistoryChange { readonly change: ChangeRecord; readonly item: ChangeItem; readonly why: HistoryReason }
+
+const GONE = new Set(['Removed', 'Replaced', 'Abandoned']);
+
+/**
+ * The change items that reached one of `ids` and are history now, oldest first: superseded for one of them by a later
+ * change, written only from material that exists in history, or everything they set down since replaced, given up or
+ * removed. A proposal nobody adopted changed nothing and is not history of the work.
+ */
+export function historyChanges(store: ProjectStore, ids: ReadonlySet<string>): HistoryChange[] {
+  const superseded = new Map<string, { byChangeId: string | null; reason: string }>();
+  for (const j of store.propagation.filter((x) => ids.has(x.nodeId))) {
+    for (const c of j.closed) if (c.close === 'Superseded by a later change') superseded.set(`${c.changeId}|${c.itemId}`, { byChangeId: c.supersededByChangeId ?? null, reason: c.reason });
+  }
+  const validity = (id: string) => store.reference.get(id)?.validity ?? store.threads.get(id)?.validity ?? store.nodes.get(id)?.validity ?? null;
+  const out: HistoryChange[] = [];
+  for (const change of store.changes.all()) {
+    for (const item of itemsOf(change)) {
+      if (!item.affects.some((id) => ids.has(id)) || item.by?.identity === 'Proposal') continue;
+      const over = superseded.get(`${change.id}|${item.id}`);
+      if (over) { out.push({ change, item, why: { kind: 'superseded', ...over } }); continue; }
+      const sources = item.sourceIds.map((id) => store.sources.get(id)).filter((s) => s !== undefined);
+      if (sources.length && sources.every((s) => s.usedAs === 'History only')) { out.push({ change, item, why: { kind: 'history only' } }); continue; }
+      const states = item.affects.map(validity).filter((v): v is NonNullable<typeof v> => v !== null);
+      if (states.length && states.every((v) => GONE.has(v))) out.push({ change, item, why: { kind: 'overtaken' } });
+    }
+  }
+  return out.sort((a, b) => a.item.at.localeCompare(b.item.at));
+}
+
+/** The ledger's `How it got here` for one object, or why it could not be read; empty without a ledger. */
+export function ledgerLineage(ledger: Ledger | null, store: ProjectStore, objectId: string): { readonly steps: readonly LineageStepView[]; readonly error: string | null } {
+  if (!ledger) return { steps: [], error: null };
+  try {
+    return { steps: lineageView(ledger, store, objectId)?.steps ?? [], error: null };
+  } catch (e) {
+    return { steps: [], error: (e as Error).message };
+  }
+}

package/src/context/object-brief.ts

@@ -0,0 +1,300 @@
+/**
+ * What `pk get <id>` returns for an object that is not a context pack, a source or a note (Spec §7.10; CKC-12 AC-23):
+ * the same facts the workbench's object detail shows (§6.4), written for an agent to read.
+ *
+ * The rule (D59): the object's own content goes in whole — its explanation, the owner's words, its validity, progress
+ * and acceptance. Everything around it — relations, the change records that reach it, notes and marks — is named by
+ * the other end's name and id, and fetched by id when the agent wants it. A change record does not carry its whole
+ * propagation list: the objects that have not followed it are named, the rest are counted. None of the workbench's own
+ * bookkeeping (the job trace, node flags, internal timestamps) is returned.
+ *
+ * Basis: on 2026-09-18 `pk get` on one reference item returned 82 KB of raw workbench JSON, 63% of it the full records
+ * of the changes that reached it, each with its whole propagation list; the item itself was about 3%. About 70% of the
+ * 18.1 MB the CLI produced for a subagent that only used the CLI came from fetching reference items (D59).
+ */
+
+import { isCodeLabel } from './code-source.ts';
+
+export interface BriefSource { readonly id: string; readonly title: string; readonly label: string; readonly excerpt?: string; readonly usedAs?: string | null; readonly availability?: string | null }
+export interface BriefRelation { readonly id: string; readonly type: string; readonly from: string; readonly to: string; readonly fromLabel?: string; readonly toLabel?: string; readonly claim?: string; readonly basis?: string; readonly assessment?: string }
+export interface BriefNote { readonly id: string; readonly title: string; readonly ask?: string }
+export interface BriefMark { readonly id: string; readonly kind: string; readonly clue?: string; readonly targetId?: string }
+export interface BriefPropagation { readonly nodeId: string; readonly state: string; readonly sourceOrReason?: string }
+/** One net change of a piece of work (Spec §1.8): what changed, why, and what it changed. */
+export interface BriefChangeItem {
+  readonly id: string; readonly at: string; readonly effect: string; readonly material?: string; readonly title: string;
+  readonly summary?: string; readonly before?: string | null; readonly after?: string | null; readonly why?: string | null;
+  readonly affects?: readonly string[];
+}
+export interface BriefChange {
+  readonly id: string; readonly at: string; readonly effect: string; readonly material?: string; readonly title: string;
+  readonly summary?: string; readonly before?: string | null; readonly after?: string | null;
+  readonly segment?: { readonly name: string } | null;
+  /** The piece of work the record is (Spec §1.8, D56), and its net changes. A record from before pieces of work has neither. */
+  readonly work?: { readonly kind: string; readonly label: string; readonly startedAt?: string; readonly endedAt?: string; readonly openEnded?: boolean } | null;
+  readonly items?: readonly BriefChangeItem[];
+  readonly affectsLabels?: readonly { readonly id: string; readonly label: string }[];
+  readonly propagationLabels?: readonly { readonly id: string; readonly label: string }[];
+  readonly propagation?: readonly BriefPropagation[];
+  /** What the piece of work recorded and no one judges: a finished work item, a session, a commit (§2.10). */
+  readonly notJudgedLabels?: readonly { readonly id: string; readonly label: string }[];
+  /** What it reached that has since been removed from the current version. */
+  readonly removed?: readonly { readonly id: string; readonly label: string }[];
+  readonly sources?: readonly { readonly id: string; readonly title: string; readonly label: string }[];
+}
+export interface BriefNode {
+  readonly node?: { readonly id: string; readonly label: string; readonly category: string; readonly refKind: string; readonly refId: string; readonly validity?: string; readonly progress?: string | null; readonly acceptance?: string; readonly basis?: string; readonly attribution?: { readonly holder?: { readonly role: string } | null; readonly author?: { readonly kind: string; readonly name: string | null } | null; readonly identity?: string } | null; readonly updatedAt?: string };
+  readonly reference?: { readonly name: string; readonly ids?: readonly string[]; readonly category: string; readonly text: string; readonly quote?: string | null; readonly answers?: string | null; readonly validity?: string; readonly basis?: string; readonly asOf?: string; readonly replacedBy?: string | null; readonly refines?: readonly string[] } | null;
+  readonly area?: { readonly effectNow: string; readonly gaps: string; readonly asOf?: string } | null;
+  readonly thread?: { readonly title: string; readonly ids?: readonly string[]; readonly doing?: string; readonly changed?: string; readonly results?: string; readonly unresolved?: string; readonly doneMeans?: string; readonly acceptanceMeans?: string; readonly progress?: string; readonly validity?: string; readonly acceptance?: string; readonly servesLabels?: readonly { readonly referenceId: string; readonly name: string; readonly claim: string }[]; readonly dependsOn?: readonly { readonly threadId: string; readonly claim: string }[]; readonly executionFacts?: readonly { readonly type: string; readonly text: string }[]; readonly qcFacts?: readonly { readonly type: string; readonly text: string }[]; readonly facts?: readonly { readonly id: string; readonly title: string }[] } | null;
+  readonly change?: BriefChange | null;
+  readonly relations?: readonly BriefRelation[];
+  readonly notes?: readonly BriefNote[];
+  readonly changes?: readonly BriefChange[];
+  readonly marks?: readonly BriefMark[];
+  readonly sources?: readonly BriefSource[];
+  readonly updatePending?: boolean;
+  /** The changes `Update pending` waits for (Spec §7.1), each with the parts to read and how it reaches the object. */
+  readonly waitsFor?: readonly BriefWait[];
+  /** When they will be taken in (§3.8). */
+  readonly pendingWhen?: string | null;
+}
+export interface BriefWait { readonly ref: string; readonly label: string; readonly sourceIds: readonly string[]; readonly reasons: readonly { readonly link: string; readonly detail: string }[] }
+export interface BriefFact {
+  readonly id: string; readonly title: string; readonly asOf?: string;
+  readonly statements?: readonly { readonly type: string; readonly text: string; readonly sourceIds?: readonly string[] }[];
+  readonly openQuestions?: readonly string[];
+  readonly aboutSourceIds?: readonly string[];
+  readonly sources?: readonly BriefSource[];
+}
+
+const text = (s: string | null | undefined) => (s ?? '').trim();
+const line = (label: string, value: string | null | undefined) => (text(value) ? `${label}: ${text(value)}` : null);
+const keep = (lines: (string | null | undefined | false)[]) => lines.filter((l): l is string => typeof l === 'string' && l.length > 0).join('\n');
+
+/**
+ * An object's sources are part of its own content: each with its id and its excerpt, whole (Spec §7.10; CKC-12 AC-23,
+ * AC-31). A code file is named by where it is, never quoted (D65; AC-43): the agent opens the current version. The
+ * excerpt used to be shown only under 400 characters, when the workbench cut its excerpts at that length; the workbench
+ * gives them whole now, so a longer one no longer turned into a bare id (QC AH #12).
+ */
+function sourceLines(sources: readonly BriefSource[] | undefined, how: string): string[] {
+  if (!sources || !sources.length) return [];
+  return [`\n## Sources (${sources.length})`, ...sources.map((s) => {
+    const code = isCodeLabel(s.label, s.usedAs);
+    const excerpt = code ? '' : text(s.excerpt);
+    const history = s.usedAs === 'History only' ? ' · history only, not the current version' : '';
+    return `- \`${s.id}\` ${s.title} — ${s.label}${s.availability ? ` · ${s.availability}` : ''}${history}${code ? ' · a code file: open the current version and read it there' : ''}${excerpt ? `\n  “${excerpt.split('\n').join('\n  ')}”` : ''}`;
+  }), how];
+}
+
+/** What the agent entry receives for a source id (Spec §7.10 item 3; CKC-12 AC-22, AC-43). */
+export interface OriginalData {
+  readonly title: string;
+  readonly kind: string;                          // the anchor's kind: file, session, commit …
+  readonly label: string;
+  readonly readAt: string;
+  readonly commit: string | null;
+  readonly fingerprint: string;
+  readonly usedAs: string | null;
+  readonly origin: { readonly relation: string; readonly path: string } | null;
+  readonly availabilityNow: string | null;
+  readonly currentState: 'same' | 'changed' | 'missing';
+  readonly hasCredential: boolean;
+  readonly excerpt: string;
+  readonly lineStart: number;
+  /** Set for a code file: where it is — repository, file, lines, commit — given in place of its lines (D65). */
+  readonly code: { readonly location: string; readonly file: string } | null;
+  readonly otherParts: readonly { readonly id: string; readonly label: string }[];
+}
+
+/**
+ * A source as the agent entry gives it: the same as the workbench's original reading — title, kind, location, when it
+ * was read, version, the excerpt with line numbers, and what changed since — except for a code file, which gives where
+ * it is, the version read and whether it changed since, and tells the agent to open the current version (D65).
+ */
+export function sourceOriginal(d: OriginalData): string {
+  const version = `${d.commit ? `${d.commit.slice(0, 10)} · ` : ''}${d.fingerprint.slice(0, 23)}`;
+  const credential = d.hasCredential ? 'Credential: this source contains a credential; its value is not shown or stored.' : null;
+  const origin = d.origin ? `Origin: ${d.origin.relation} · ${d.origin.path}` : null;
+  const parts = d.otherParts.length ? ['', `Other parts of this document (${d.otherParts.length}), by id:`, ...d.otherParts.map((x) => `- ${x.id}  ${x.label}`)] : [];
+  if (d.code) {
+    return keep([
+      `# ${d.title}`, `Kind: ${d.kind} · code`, `Location: ${d.code.location}`, `Read at: ${d.readAt}`, `Version when read: ${version}`, `Used as: ${d.usedAs ?? 'Not yet judged'}`, origin,
+      d.currentState === 'same' ? 'Unchanged since it was read.' : d.currentState === 'changed' ? 'Changed since it was read: the file at this path is no longer the version above.' : 'No longer at this path: it was moved or deleted after it was read.',
+      credential,
+      `\nThis is a code file. ProjectKeeper gives where code is, not the code: open the current version of ${d.code.file} in the repository and read it there.`,
+      ...parts,
+    ]);
+  }
+  const lines = d.excerpt.split('\n');
+  const width = String(d.lineStart + lines.length - 1).length;
+  return [
+    `# ${d.title}`, `Kind: ${d.kind}`, `Location: ${d.label}`, `Read at: ${d.readAt}`, `Version: ${version}`, `Used as: ${d.usedAs ?? 'Not yet judged'}`,
+    origin, d.availabilityNow ? `Availability: ${d.availabilityNow}` : null, credential,
+    d.currentState === 'changed' ? 'This source changed after it was read; the excerpt below is what was read.' : d.currentState === 'missing' ? 'This source is no longer available at its path; the excerpt below is what was read.' : null,
+    '', ...(d.excerpt ? lines.map((l, i) => `${String(d.lineStart + i).padStart(width)} | ${l}`) : ['(No text was read from this source: it is binary or could not be read as text; nothing is reproduced.)']),
+    '', 'Excerpts keep the original text. Interpretations and relations built on them can be corrected; the original is never changed.',
+    ...parts,
+  ].filter((l) => l !== null).join('\n');
+}
+
+function relationLines(relations: readonly BriefRelation[] | undefined, selfId: string, alreadyListed: ReadonlySet<string>): string[] {
+  // Every change record that reaches an object also hangs off it as an `affects` relation; it is listed once, under
+  // the change records, not twice.
+  const shown = (relations ?? []).filter((r) => !(r.type === 'affects' && alreadyListed.has(r.from === selfId ? r.to : r.from)));
+  if (!shown.length) return [];
+  return [`\n## Relations (${shown.length})`, ...shown.map((r) => {
+    const outgoing = r.from === selfId;
+    const otherId = outgoing ? r.to : r.from;
+    const otherLabel = (outgoing ? r.toLabel : r.fromLabel) ?? otherId;
+    // Only a questioned assessment is written; `Holds` and `Not assessed` are normal states and stay in the assets (D59).
+    return `- ${outgoing ? '' : '← '}${r.type} ${otherLabel} (\`${otherId}\`)${r.basis === 'Inferred' ? ' · Inferred' : ''}${r.assessment === 'Questioned' ? ' · Questioned' : ''}${text(r.claim) ? `: ${text(r.claim)}` : ''}`;
+  })];
+}
+
+/**
+ * `Update pending` says which changes the object waits for and when they are taken in (Spec §7.1, §7.6): each change by
+ * name with the id to read it now and how it reaches the object. Nobody has to wait for the round to check.
+ */
+function pendingLines(d: BriefNode): string[] {
+  const waits = d.waitsFor ?? [];
+  if (!waits.length) return [];
+  return [
+    `\n## Update pending (${waits.length})`,
+    ...waits.map((w) => `- ${w.label} (${w.sourceIds.length ? w.sourceIds.map((id) => `\`${id}\``).join(', ') : `\`${w.ref}\``})${w.reasons.length ? ` — ${w.reasons.map((r) => r.detail).join('; ')}` : ''}`),
+    `What is written above may be out of date until these are taken in${d.pendingWhen ? `, ${d.pendingWhen}` : ''}. Read any of them now with \`pk get <id>\`; asking the Keeper about this object reads them in.`,
+  ];
+}
+
+function neighbourLines(d: BriefNode): string[] {
+  const out: string[] = [];
+  if (d.changes && d.changes.length) {
+    out.push(`\n## Change records that reach it (${d.changes.length})`, ...d.changes.map((c) => `- ${c.at.slice(0, 10)} · ${c.effect} · ${c.title} (\`${c.id}\`)`), 'Each by id with `pk get`; the record says what changed, why, and which objects have not followed it.');
+  }
+  if (d.notes && d.notes.length) out.push(`\n## Notes on it (${d.notes.length})`, ...d.notes.map((n) => `- ${n.title} (\`${n.id}\`${n.ask ? ` · ${n.ask}` : ''})`), 'The whole note: `pk get <note id>`.');
+  const marks = (d.marks ?? []).filter((m) => text(m.clue).length > 0);
+  if (marks.length) out.push(`\n## Entry marks on it (${marks.length})`, ...marks.map((m) => `- ${m.kind} (\`${m.id}\`): ${text(m.clue)}`));
+  return out;
+}
+
+/**
+ * A change record, without its whole propagation list (D59; Spec §7.10): the piece of work it is and each of its net
+ * changes — what changed, why, what it changed (QC AH #4: only the record's first line reached the agent) — then what
+ * has not followed it, and the rest counted.
+ */
+export function changeBrief(c: BriefChange): string {
+  const prop = c.propagation ?? [];
+  // An object that has not followed the change is usually not one the change itself altered, so its name comes from
+  // the propagation labels; `affects` covers the ones it did alter.
+  const labelOf = (id: string) => c.propagationLabels?.find((a) => a.id === id)?.label ?? c.affectsLabels?.find((a) => a.id === id)?.label ?? c.removed?.find((a) => a.id === id)?.label ?? id;
+  // What it reached that has since been removed from the current version is named as removed (CKC-12 AC-35).
+  const named = (id: string) => `${labelOf(id)} (\`${id}\`${c.removed?.some((r) => r.id === id) ? ', removed from the current version' : ''})`;
+  const behind = prop.filter((p) => p.state === 'Still on old understanding');
+  const rest = new Map<string, number>();
+  for (const p of prop) if (p.state !== 'Still on old understanding') rest.set(p.state, (rest.get(p.state) ?? 0) + 1);
+  const items = c.items ?? [];
+  const byWork = c.work && items.length > 0;
+  const itemLines = (it: BriefChangeItem) => keep([
+    `- ${it.at} · ${it.effect}${it.material ? ` · ${it.material}` : ''} · **${text(it.title)}**`,
+    text(it.summary) && text(it.summary) !== text(it.title) ? `  ${text(it.summary).split('\n').join('\n  ')}` : null,
+    it.before || it.after ? `  Before: ${text(it.before) || '—'} → after: ${text(it.after) || '—'}` : null,
+    text(it.why) ? `  Why: ${text(it.why)}` : null,
+    it.affects && it.affects.length ? `  Affects: ${it.affects.map(named).join('; ')}` : null,
+  ]);
+  return keep([
+    `# ${c.title} (\`${c.id}\`)`,
+    byWork
+      ? `Change record of one piece of work · ${c.work!.kind}: ${c.work!.label}${c.work!.startedAt ? ` · ${c.work!.startedAt}${c.work!.endedAt && c.work!.endedAt !== c.work!.startedAt ? ` → ${c.work!.endedAt}` : ''}` : ''}${c.work!.openEnded ? ' · still going when its round began' : ''}`
+      : `Change · ${c.effect}${c.material ? ` · ${c.material}` : ''} · ${c.at}${c.segment ? ` · from ${c.segment.name}` : ''}`,
+    '',
+    ...(byWork
+      ? [`## Its net changes (${items.length})`, ...items.map(itemLines)]
+      : [
+        text(c.summary),
+        c.before || c.after ? `\nBefore: ${text(c.before) || '—'} → after: ${text(c.after) || '—'}` : null,
+        c.affectsLabels && c.affectsLabels.length ? `\nAffects: ${[...new Map(c.affectsLabels.map((a) => [a.id, a])).values()].map((a) => named(a.id)).join('; ')}` : null,
+      ]),
+    c.notJudgedLabels && c.notJudgedLabels.length ? `\nRecorded at the time, not judged: ${c.notJudgedLabels.map((a) => named(a.id)).join('; ')}` : null,
+    c.sources && c.sources.length ? `${byWork ? '\n' : ''}Sources: ${c.sources.map((s) => `${s.title} (\`${s.id}\`) — ${s.label}`).join('; ')}` : null,
+    behind.length ? `\n## Not followed yet (${behind.length})\n${behind.map((p) => `- ${labelOf(p.nodeId)} (\`${p.nodeId}\`)${text(p.sourceOrReason) ? ` — ${text(p.sourceOrReason)}` : ''}`).join('\n')}` : null,
+    rest.size ? `\nThe other ${[...rest.values()].reduce((a, b) => a + b, 0)} object(s) this record reached: ${[...rest].map(([state, n]) => `${state} ${n}`).join(', ')}. Those are the normal states; they stay in the assets, and \`pk get <id>\` reads any one of them.` : (behind.length ? null : '\nNo object is recorded as still on the old understanding of this change.'),
+  ]);
+}
+
+/** A fact record: its statements and open questions in full, its sources by id. */
+export function factBrief(f: BriefFact): string {
+  return keep([
+    `# ${f.title} (\`${f.id}\`)`,
+    `Fact record${f.asOf ? ` · as of ${f.asOf}` : ''}`,
+    '',
+    ...(f.statements ?? []).map((s) => `- ${s.type}: ${text(s.text)}${s.sourceIds && s.sourceIds.length ? ` [${s.sourceIds.join(', ')}]` : ''}`),
+    (f.openQuestions ?? []).length ? `\n## Still open\n${(f.openQuestions ?? []).map((q) => `- ${q}`).join('\n')}` : null,
+    ...sourceLines(f.sources, 'Each source by id with `pk get`, which gives the original with line numbers.'),
+  ]);
+}
+
+/** A relation on its own: what it claims, on what evidence, and both ends by name and id. */
+export function relationBrief(r: BriefRelation & { readonly evidence?: { readonly factsSoFar?: string; readonly sourceIds?: readonly string[] }; readonly evidenceSources?: readonly BriefSource[]; readonly notes?: readonly BriefNote[]; readonly assessedAt?: string | null }): string {
+  return keep([
+    `# ${r.fromLabel ?? r.from} ${r.type} ${r.toLabel ?? r.to} (\`${r.id}\`)`,
+    `From ${r.fromLabel ?? r.from} (\`${r.from}\`) to ${r.toLabel ?? r.to} (\`${r.to}\`)${r.basis === 'Inferred' ? ' · Inferred' : ''}${r.assessment === 'Questioned' ? ` · Questioned${r.assessedAt ? ` on ${r.assessedAt}` : ''}` : ''}`,
+    '',
+    text(r.claim),
+    line('So far', r.evidence?.factsSoFar),
+    ...sourceLines(r.evidenceSources, 'Each source by id with `pk get`.'),
+    (r.notes ?? []).length ? `\n## Notes on it (${(r.notes ?? []).length})\n${(r.notes ?? []).map((n) => `- ${n.title} (\`${n.id}\`)`).join('\n')}` : null,
+  ]);
+}
+
+/**
+ * Any other object of the graph — a product reference item, an area, a work item, a change, a session or a result —
+ * as the workbench's object detail says it, in prose.
+ */
+export function nodeBrief(d: BriefNode): string {
+  const n = d.node;
+  const selfId = n?.id ?? '';
+  if (d.change) return changeBrief(d.change);
+  const r = d.reference;
+  const t = d.thread;
+  const name = r?.name ?? t?.title ?? n?.label ?? selfId;
+  const ids = r?.ids ?? t?.ids ?? [];
+  const category = r?.category ?? n?.category ?? 'Object';
+  const validity = r?.validity ?? t?.validity ?? n?.validity ?? '';
+  const progress = t?.progress ?? n?.progress ?? '';
+  const acceptance = t?.acceptance ?? n?.acceptance ?? '';
+  const holder = n?.attribution?.holder?.role ?? (n?.attribution?.author?.kind === 'role' ? n.attribution.author.name : null);
+  const head = [
+    category,
+    validity && validity !== 'Current' ? validity : '',   // `Current` is the normal state and is not written (D59)
+    progress,
+    acceptance,
+    holder ? `held by ${holder}` : '',
+    (r?.basis ?? n?.basis) === 'Inferred' ? 'Inferred' : '',
+    d.updatePending ? 'Update pending' : '',
+  ].filter((x) => text(x).length).join(' · ');
+  return keep([
+    `# ${name}${ids.length ? ` (${ids.join(', ')})` : ''} (\`${selfId}\`)`,
+    head,
+    r?.asOf || n?.updatedAt ? `As of ${r?.asOf ?? n?.updatedAt}` : null,
+    '',
+    // The object's own content, whole (AC-31).
+    text(r?.text),
+    r?.quote ? `Owner’s words: “${text(r.quote)}”${r.answers ? ` — in answer to: “${text(r.answers)}”` : ''}` : null,
+    r?.replacedBy ? `Replaced by \`${r.replacedBy}\` — \`pk get ${r.replacedBy}\` reads it.` : null,
+    d.area ? keep(['\n## Area understanding', line('Now', d.area.effectNow), line('Still missing', d.area.gaps)]) : null,
+    t ? keep([
+      line('Doing', t.doing), line('Done means', t.doneMeans), line('Owner acceptance means', t.acceptanceMeans),
+      line('Changed on the way', t.changed), line('Results', t.results), line('Unresolved', t.unresolved),
+      (t.servesLabels ?? []).length ? `Serves: ${(t.servesLabels ?? []).map((s) => `${s.name} (\`${s.referenceId}\`)${text(s.claim) ? ` — ${text(s.claim)}` : ''}`).join('; ')}` : null,
+      (t.dependsOn ?? []).length ? `Depends on: ${(t.dependsOn ?? []).map((x) => `\`${x.threadId}\`${text(x.claim) ? ` — ${text(x.claim)}` : ''}`).join('; ')}` : null,
+      [...(t.executionFacts ?? []), ...(t.qcFacts ?? [])].length ? `\n## Results and failures recorded\n${[...(t.executionFacts ?? []), ...(t.qcFacts ?? [])].map((s) => `- ${s.type}: ${text(s.text)}`).join('\n')}` : null,
+      (t.facts ?? []).length ? `\nFact records behind it: ${(t.facts ?? []).map((f) => `${f.title} (\`${f.id}\`)`).join('; ')}` : null,
+    ]) : null,
+    ...pendingLines(d),
+    ...sourceLines(d.sources, 'Each source by id with `pk get`, which gives the original with line numbers and says whether it changed since it was read.'),
+    ...relationLines(d.relations, selfId, new Set((d.changes ?? []).map((c) => c.id))),
+    ...neighbourLines(d),
+    '\nEvery id above is read with `pk get <id>`. A work item or an area gives its context pack; anything else gives a page like this one.',
+  ]);
+}