[codex] Add issue document locking (#6009)

## 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>

server/src/__tests__/documents-service.test.ts

@@ -112,4 +112,85 @@ describeEmbeddedPostgres("documentService system issue documents", () => {
       body: "# Handoff",
     }));
   });
+
+  it("locks and unlocks issue documents", async () => {
+    const { issueId } = await createIssueWithDocuments();
+
+    const locked = await svc.lockIssueDocument({
+      issueId,
+      key: "plan",
+      lockedByUserId: "board-user",
+    });
+
+    expect(locked.changed).toBe(true);
+    expect(locked.document.lockedAt).toBeInstanceOf(Date);
+    expect(locked.document.lockedByUserId).toBe("board-user");
+
+    await expect(svc.upsertIssueDocument({
+      issueId,
+      key: "plan",
+      title: "Plan",
+      format: "markdown",
+      body: "# Updated plan",
+      baseRevisionId: locked.document.latestRevisionId,
+      createdByUserId: "board-user",
+    })).rejects.toMatchObject({
+      status: 409,
+      message: "Document is locked",
+    });
+
+    const unlocked = await svc.unlockIssueDocument(issueId, "plan");
+    expect(unlocked.changed).toBe(true);
+    expect(unlocked.document.lockedAt).toBeNull();
+
+    const updated = await svc.upsertIssueDocument({
+      issueId,
+      key: "plan",
+      title: "Plan",
+      format: "markdown",
+      body: "# Updated plan",
+      baseRevisionId: unlocked.document.latestRevisionId,
+      createdByUserId: "board-user",
+    });
+
+    expect(updated.created).toBe(false);
+    expect(updated.document.body).toBe("# Updated plan");
+  });
+
+  it("creates a new document instead of updating a locked document when requested", async () => {
+    const { issueId } = await createIssueWithDocuments();
+    const locked = await svc.lockIssueDocument({
+      issueId,
+      key: "plan",
+      lockedByUserId: "board-user",
+    });
+
+    const fallback = await svc.upsertIssueDocument({
+      issueId,
+      key: "plan",
+      title: "Plan",
+      format: "markdown",
+      body: "# Agent replacement plan",
+      baseRevisionId: locked.document.latestRevisionId,
+      lockedDocumentStrategy: "create_new_document",
+    });
+
+    expect(fallback.created).toBe(true);
+    expect(fallback.document.key).toBe("plan-2");
+    expect(fallback.document.body).toBe("# Agent replacement plan");
+    expect("redirectedFromLockedDocument" in fallback ? fallback.redirectedFromLockedDocument : null)
+      .toEqual({ id: locked.document.id, key: "plan" });
+
+    const originalPlan = await svc.getIssueDocumentByKey(issueId, "plan");
+    expect(originalPlan).toEqual(expect.objectContaining({
+      body: "# Plan",
+      lockedAt: expect.any(Date),
+    }));
+
+    const newPlan = await svc.getIssueDocumentByKey(issueId, "plan-2");
+    expect(newPlan).toEqual(expect.objectContaining({
+      body: "# Agent replacement plan",
+      lockedAt: null,
+    }));
+  });
 });

server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts

@@ -410,6 +410,7 @@ describe("agent issue mutation checkout ownership", () => {
         key: "plan",
         createdByAgentId: ownerAgentId,
         createdByRunId: ownerRunId,
+        lockedDocumentStrategy: "create_new_document",
       }),
     );
   });