mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-14 01:50:39 +09:00
03ad5c5bea
## Thinking Path > - Paperclip orchestrates AI-agent companies through company-scoped issues, comments, and issue documents. > - Issue documents are the durable place where plans, handoffs, and other work artifacts are revised over time. > - Some documents need to be preserved as operator-approved snapshots while agents continue working on the same issue. > - Without document locking, a later board or agent write can overwrite the document key that reviewers expected to remain stable. > - This pull request adds board-managed issue document locks and makes agent writes to locked keys create a derived document instead of mutating the locked document. > - The benefit is safer document handoffs: approved or frozen issue documents stay immutable until the board explicitly unlocks them. ## What Changed - Added `locked_at`, `locked_by_agent_id`, and `locked_by_user_id` document fields plus migration `0085_tranquil_the_executioner.sql`. - Added document lock/unlock service behavior, route endpoints, activity events, and locked-document write protections. - Made agent document writes to locked keys create a new derived key such as `plan-2` rather than overwriting the locked document. - Surfaced lock state through shared issue document types, UI API methods, document header lock controls, and activity formatting. - Added server and UI tests for lock/unlock behavior, locked document immutability, and UI action visibility. - Updated `doc/SPEC-implementation.md` with the V1 document lock contract and endpoints. ## Verification - `git rebase public-gh/master` completed cleanly after committing the branch changes. - `git diff --check` passed before commit. - `pnpm run preflight:workspace-links && pnpm exec vitest run server/src/__tests__/documents-service.test.ts server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts ui/src/components/IssueDocumentsSection.test.tsx ui/src/components/IssueContinuationHandoff.test.tsx ui/src/lib/document-revisions.test.ts` passed: 5 files, 32 tests. ## Risks - Medium risk because this changes the document persistence contract and adds a migration. - The migration uses `ADD COLUMN IF NOT EXISTS` and guarded foreign-key creation so it remains safe for users who may have already applied an earlier copy of the migration. - Locked documents intentionally reject board edits/deletes/restores until unlocked; any existing workflows that expected direct overwrite need to unlock first. - Agent writes to locked keys now create derived documents, which may create extra issue documents when agents retry locked writes. ## Model Used - OpenAI Codex coding agent based on GPT-5, with tool use and local code execution in the Paperclip worktree. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
98 lines
3.7 KiB
TypeScript
98 lines
3.7 KiB
TypeScript
import type { DocumentRevision, IssueDocument } from "@paperclipai/shared";
|
|
import { describe, expect, it } from "vitest";
|
|
import { deriveDocumentRevisionState } from "./document-revisions";
|
|
|
|
function createDocument(overrides: Partial<IssueDocument> = {}): IssueDocument {
|
|
return {
|
|
id: "document-1",
|
|
companyId: "company-1",
|
|
issueId: "issue-1",
|
|
key: "plan",
|
|
title: "Plan",
|
|
format: "markdown",
|
|
body: "# Current plan",
|
|
latestRevisionId: "revision-2",
|
|
latestRevisionNumber: 2,
|
|
createdByAgentId: "agent-1",
|
|
createdByUserId: null,
|
|
updatedByAgentId: "agent-1",
|
|
updatedByUserId: null,
|
|
lockedAt: null,
|
|
lockedByAgentId: null,
|
|
lockedByUserId: null,
|
|
createdAt: new Date("2026-04-10T15:00:00.000Z"),
|
|
updatedAt: new Date("2026-04-10T16:00:00.000Z"),
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
function createRevision(overrides: Partial<DocumentRevision> = {}): DocumentRevision {
|
|
return {
|
|
id: "revision-1",
|
|
companyId: "company-1",
|
|
documentId: "document-1",
|
|
issueId: "issue-1",
|
|
key: "plan",
|
|
revisionNumber: 1,
|
|
title: "Plan",
|
|
format: "markdown",
|
|
body: "# Revision body",
|
|
changeSummary: null,
|
|
createdByAgentId: "agent-1",
|
|
createdByUserId: null,
|
|
createdAt: new Date("2026-04-10T15:00:00.000Z"),
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
describe("deriveDocumentRevisionState", () => {
|
|
it("falls back to a synthetic current revision when no revision history has been fetched yet", () => {
|
|
const state = deriveDocumentRevisionState(createDocument({
|
|
latestRevisionId: null,
|
|
latestRevisionNumber: 0,
|
|
body: "# Draft plan",
|
|
}), []);
|
|
|
|
expect(state.currentRevision.id).toBe("document-1-latest");
|
|
expect(state.currentRevision.body).toBe("# Draft plan");
|
|
expect(state.revisions.map((revision) => revision.id)).toEqual(["document-1-latest"]);
|
|
});
|
|
|
|
it("sorts fetched revisions newest-first even when the API payload is out of order", () => {
|
|
const state = deriveDocumentRevisionState(createDocument(), [
|
|
createRevision({ id: "revision-1", revisionNumber: 1, createdAt: new Date("2026-04-10T15:00:00.000Z") }),
|
|
createRevision({ id: "revision-2", revisionNumber: 2, body: "# Current plan", createdAt: new Date("2026-04-10T16:00:00.000Z") }),
|
|
]);
|
|
|
|
expect(state.currentRevision.id).toBe("revision-2");
|
|
expect(state.revisions.map((revision) => revision.id)).toEqual(["revision-2", "revision-1"]);
|
|
});
|
|
|
|
it("keeps the latest document revision current when the revision history cache is stale", () => {
|
|
const state = deriveDocumentRevisionState(createDocument(), [
|
|
createRevision({ id: "revision-1", revisionNumber: 1, body: "# Original plan" }),
|
|
]);
|
|
|
|
expect(state.currentRevision.id).toBe("revision-2");
|
|
expect(state.currentRevision.body).toBe("# Current plan");
|
|
expect(state.revisions.map((revision) => revision.id)).toEqual(["revision-2", "revision-1"]);
|
|
});
|
|
|
|
it("trusts the fetched revision history when it is newer than the document summary cache", () => {
|
|
const staleDocument = createDocument({
|
|
body: "# Original plan",
|
|
latestRevisionId: "revision-1",
|
|
latestRevisionNumber: 1,
|
|
updatedAt: new Date("2026-04-10T15:00:00.000Z"),
|
|
});
|
|
|
|
const state = deriveDocumentRevisionState(staleDocument, [
|
|
createRevision({ id: "revision-2", revisionNumber: 2, body: "# Current plan", createdAt: new Date("2026-04-10T16:00:00.000Z") }),
|
|
createRevision({ id: "revision-1", revisionNumber: 1, body: "# Original plan", createdAt: new Date("2026-04-10T15:00:00.000Z") }),
|
|
]);
|
|
|
|
expect(state.currentRevision.id).toBe("revision-2");
|
|
expect(state.currentRevision.body).toBe("# Current plan");
|
|
expect(state.revisions.map((revision) => revision.id)).toEqual(["revision-2", "revision-1"]);
|
|
});
|
|
});
|