Q30: documents keep every version

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/main/database/migrations/065-document-versions.ts

@@ -0,0 +1,26 @@
+export const documentVersionsSchema = `
+  alter table documents add column version integer not null default 1;
+
+  create table if not exists document_versions (
+    id text primary key,
+    org_id text not null references organizations(id) on delete cascade,
+    document_id text not null,
+    version integer not null,
+    title text not null,
+    content text not null,
+    status text not null,
+    changed_by_type text not null,
+    changed_by_id text,
+    reason text not null,
+    created_at text not null,
+    unique (document_id, version)
+  );
+
+  insert into document_versions(id, org_id, document_id, version, title, content, status, changed_by_type, changed_by_id, reason, created_at)
+  select 'dov_' || lower(hex(randomblob(16))), org_id, id, 1, title, content, status,
+         case when author_agent_id is null then 'employee' else 'agent' end, author_agent_id, 'created', created_at
+  from documents;
+
+  insert into schema_migrations(version, name, applied_at)
+  values (65, 'document_versions', datetime('now'));
+`;

src/main/database/schema.ts

@@ -63,6 +63,7 @@ import { taskRunContextSchema } from "./migrations/061-task-run-context";
 import { providerContextWindowSchema } from "./migrations/062-provider-context-window";
 import { knowledgeScopeSchema } from "./migrations/063-knowledge-scope";
 import { knowledgeRevisionsSchema } from "./migrations/064-knowledge-revisions";
+import { documentVersionsSchema } from "./migrations/065-document-versions";
 
 interface Migration {
   version: number;
@@ -135,6 +136,7 @@ const MIGRATIONS: Migration[] = [
   { version: 62, name: "provider_context_window", sql: providerContextWindowSchema },
   { version: 63, name: "knowledge_scope", sql: knowledgeScopeSchema },
   { version: 64, name: "knowledge_revisions", sql: knowledgeRevisionsSchema },
+  { version: 65, name: "document_versions", sql: documentVersionsSchema },
 ];
 
 const SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;

src/main/services/agent-document-tools.ts

@@ -7,6 +7,8 @@ import type { ToolDefinition } from "./provider-tool-turn";
 import { relevantItems } from "./relevance";
 import { PAGE_TOOL_PROPERTIES, pageText, readPageArgs } from "./text-paging";
 
+const PAGE_ARGUMENTS = ["version", "start_line", "line_count", "start_column", "search"] as const;
+
 export const DOCUMENT_TYPES = ["prd", "spec", "memo", "report", "runbook", "proposal", "policy", "guide"] as const;
 
 interface DocumentRow {
@@ -15,6 +17,7 @@ interface DocumentRow {
   doc_type: string;
   status: string;
   content: string;
+  version: number;
   updated_at: string;
   task_id: string | null;
   task_title: string | null;
@@ -37,11 +40,16 @@ export const DOCUMENT_TOOLS: ToolDefinition[] = [
   },
   {
     name: "read_document",
-    description: "Read a company document by doc_id — whole, a range of lines, or only the lines matching a search.",
+    description: "Read a company document by doc_id — whole, a range of lines, or only the lines matching a search. Pass version to read an earlier version; pass history=true to list every version.",
     parameters: {
       type: "object",
       additionalProperties: false,
-      properties: { doc_id: { type: "string" }, ...PAGE_TOOL_PROPERTIES },
+      properties: {
+        doc_id: { type: "string" },
+        version: { type: "number", description: "An earlier version number; omit for the current one." },
+        history: { type: "boolean", description: "List every version with who changed it and why." },
+        ...PAGE_TOOL_PROPERTIES,
+      },
       required: ["doc_id"],
     },
   },
@@ -67,21 +75,35 @@ export function listDocumentsTool(deps: AgentToolDeps, ctx: AgentToolContext, ar
   const docType = args.doc_type === undefined ? null : optionalEnum(args.doc_type, "doc_type", DOCUMENT_TYPES, "");
   const limit = optionalLimit(args.limit, "limit", 10, 30);
   const rows = deps.db.prepare(`
-    select d.id, d.title, d.doc_type, d.status, d.content, d.updated_at, d.task_id, t.title as task_title
+    select d.id, d.title, d.doc_type, d.status, d.content, d.version, d.updated_at, d.task_id, t.title as task_title
     from documents d left join tasks t on t.id = d.task_id
     where d.org_id = ? and (? is null or d.doc_type = ?) order by d.updated_at desc
   `).all(ctx.orgId, docType, docType) as unknown as DocumentRow[];
   const found = query ? relevantItems(rows, (row) => `${row.title} ${row.content}`, query, limit) : rows.slice(0, limit);
   if (found.length === 0) return query ? `No documents match "${query}".` : "No documents yet.";
-  return found.map((row) => `${row.title} (doc_id=${row.id}, ${row.doc_type}, ${row.status}, ${row.content.length} chars, updated ${row.updated_at}${producedBy(row)})`).join("\n");
+  return found.map((row) => `${row.title} (doc_id=${row.id}, ${row.doc_type}, ${row.status}, v${row.version}, ${row.content.length} chars, updated ${row.updated_at}${producedBy(row)})`).join("\n");
 }
 
 export function readDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string {
   const id = requireString(args.doc_id, "doc_id");
-  const doc = deps.db.prepare("select title, doc_type, status, content from documents where id = ? and org_id = ?")
-    .get(id, ctx.orgId) as { title: string; doc_type: string; status: string; content: string } | undefined;
-  if (!doc) throw new Error(`No document with doc_id "${id}".`);
-  return `${doc.title} (${doc.doc_type}, ${doc.status})\n\n${pageText(doc.title, doc.content, readPageArgs(args))}`;
+  const page = readPageArgs(args);
+  if (args.history !== undefined && typeof args.history !== "boolean") throw new Error('"history" must be true or false.');
+  const doc = deps.db.prepare("select doc_type, version from documents where id = ? and org_id = ?")
+    .get(id, ctx.orgId) as { doc_type: string; version: number } | undefined;
+  const versions = new DocumentService(deps.db).versions(ctx.orgId, id);
+  if (versions.length === 0) throw new Error(`No document with doc_id "${id}".`);
+  const latest = versions[versions.length - 1].version;
+  const kind = doc ? doc.doc_type : "deleted";
+  if (args.history === true) {
+    if (PAGE_ARGUMENTS.some((name) => args[name] !== undefined)) {
+      throw new Error("history=true lists versions; it takes no version or paging arguments.");
+    }
+    return versions.map((v) => `v${v.version} ${v.created_at} by ${v.changed_by_type}${v.changed_by_id ? ` ${v.changed_by_id}` : ""} — ${v.reason} (${v.content.length} chars)`).join("\n");
+  }
+  const wanted = optionalLimit(args.version, "version", latest, latest);
+  const picked = versions.find((v) => v.version === wanted);
+  if (!picked) throw new Error(`Document ${id} has no version ${wanted}.`);
+  return `${picked.title} (${kind}, ${picked.status}, v${picked.version} of ${latest})\n\n${pageText(picked.title, picked.content, page)}`;
 }
 
 export function updateDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, args: JsonRecord): string {
@@ -92,14 +114,16 @@ export function updateDocumentTool(deps: AgentToolDeps, ctx: AgentToolContext, a
   const content = requireString(args.content, "content");
   const title = optionalText(args.title, "title") ?? doc.title;
   const reason = requireString(args.reason, "reason");
-  new DocumentService(deps.db).update({ orgId: ctx.orgId, documentId: id, title, content, status: doc.status });
+  const version = new DocumentService(deps.db).update({
+    orgId: ctx.orgId, documentId: id, title, content, status: doc.status, reason, changedByType: "agent", changedById: ctx.agent.id,
+  });
   const review = requestDeliverableReview(deps, ctx, {
     title: `Review ${doc.doc_type} update: ${title}`,
-    details: `Document "${title}" was updated by an agent run (${content.length} chars). Reason: ${reason}`,
+    details: `Document "${title}" v${version} was updated by an agent run (${content.length} chars). Reason: ${reason}`,
     sourceEntityType: "document",
     sourceEntityId: id,
   });
-  return `Updated document "${title}" (doc_id=${id}).${review ? " The update is queued for board review in Approvals." : ""}`;
+  return `Updated document "${title}" to v${version} (doc_id=${id}).${review ? " The update is queued for board review in Approvals." : ""}`;
 }
 
 function producedBy(row: DocumentRow): string {

src/main/services/document-service.ts

@@ -3,6 +3,17 @@ import type { CreateDocumentInput, UpdateDocumentInput, DeleteDocumentInput } fr
 import { createId } from "../../shared/ids";
 import { AuditService } from "./audit-service";
 
+export interface DocumentVersion {
+  version: number;
+  title: string;
+  content: string;
+  status: string;
+  changed_by_type: string;
+  changed_by_id: string | null;
+  reason: string;
+  created_at: string;
+}
+
 export class DocumentService {
   private readonly audit: AuditService;
 
@@ -14,9 +25,13 @@ export class DocumentService {
     const id = createId("doc");
     const now = new Date().toISOString();
     this.db.prepare(`
-      insert into documents(id, org_id, title, doc_type, content, status, author_agent_id, reviewer_agent_id, project_id, goal_id, task_id, created_at, updated_at)
-      values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      insert into documents(id, org_id, title, doc_type, content, status, author_agent_id, reviewer_agent_id, project_id, goal_id, task_id, version, created_at, updated_at)
+      values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
     `).run(id, input.orgId, input.title.trim(), input.docType, input.content, "draft", input.authorAgentId, input.reviewerAgentId, input.projectId, input.goalId, input.taskId, now, now);
+    this.writeVersion({
+      orgId: input.orgId, documentId: id, version: 1, title: input.title.trim(), content: input.content, status: "draft",
+      changedByType: input.authorAgentId ? "agent" : "employee", changedById: input.authorAgentId, reason: "created", at: now,
+    });
     this.audit.record({
       orgId: input.orgId,
       entityType: "document",
@@ -29,15 +44,44 @@ export class DocumentService {
     return id;
   }
 
-  update(input: UpdateDocumentInput): void {
-    const result = this.db.prepare(`
-      update documents set title = ?, content = ?, status = ?, updated_at = ? where id = ? and org_id = ?
-    `).run(input.title.trim(), input.content, input.status, new Date().toISOString(), input.documentId, input.orgId);
-    if (result.changes === 0) throw new Error("Document was not found.");
+  /** Saves a new version; earlier versions stay readable. */
+  update(input: UpdateDocumentInput): number {
+    const reason = input.reason.trim();
+    if (!reason) throw new Error("A document update needs a reason.");
+    const current = this.db.prepare("select version from documents where id = ? and org_id = ?")
+      .get(input.documentId, input.orgId) as { version: number } | undefined;
+    if (!current) throw new Error("Document was not found.");
+    const version = current.version + 1;
+    const now = new Date().toISOString();
+    this.db.prepare(`
+      update documents set title = ?, content = ?, status = ?, version = ?, updated_at = ? where id = ? and org_id = ?
+    `).run(input.title.trim(), input.content, input.status, version, now, input.documentId, input.orgId);
+    this.writeVersion({
+      orgId: input.orgId, documentId: input.documentId, version, title: input.title.trim(), content: input.content, status: input.status,
+      changedByType: input.changedByType, changedById: input.changedById, reason, at: now,
+    });
+    return version;
+  }
+
+  versions(orgId: string, documentId: string): DocumentVersion[] {
+    return this.db.prepare(`
+      select version, title, content, status, changed_by_type, changed_by_id, reason, created_at
+      from document_versions where document_id = ? and org_id = ? order by version asc
+    `).all(documentId, orgId) as unknown as DocumentVersion[];
   }
 
   delete(input: DeleteDocumentInput): void {
     const result = this.db.prepare("delete from documents where id = ? and org_id = ?").run(input.documentId, input.orgId);
     if (result.changes === 0) throw new Error("Document was not found.");
   }
+
+  private writeVersion(input: {
+    orgId: string; documentId: string; version: number; title: string; content: string; status: string;
+    changedByType: string; changedById: string | null; reason: string; at: string;
+  }): void {
+    this.db.prepare(`
+      insert into document_versions(id, org_id, document_id, version, title, content, status, changed_by_type, changed_by_id, reason, created_at)
+      values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(createId("dov"), input.orgId, input.documentId, input.version, input.title, input.content, input.status, input.changedByType, input.changedById, input.reason, input.at);
+  }
 }

src/shared/commands/collaboration.ts

@@ -16,6 +16,10 @@ export interface UpdateDocumentInput {
   title: string;
   content: string;
   status: string;
+  /** Why it changed; kept with the new version. */
+  reason: string;
+  changedByType: "employee" | "agent";
+  changedById: string | null;
 }
 
 export interface DeleteDocumentInput {

src/shared/domain.ts

@@ -406,6 +406,7 @@ export interface DocumentRecord {
   projectId: string | null;
   goalId: string | null;
   taskId: string | null;
+  version: number;
   createdAt: string;
   updatedAt: string;
 }