From fcf78e8a7e6b12d1a2ecb7d66cfce34278b8982d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Sun, 19 Apr 2026 19:21:04 -0400 Subject: [PATCH] Draw a sharp line between documents and work_products Agents had two artifact stores and no guidance on which to pick, so the same file was routinely posted as a prose document *and* registered as a filesystem work product by the auto-projector, with two copies of the body drifting out of sync. Rewrite SOP-009 to be explicit: filesystem output is auto-registered and must not be duplicated into the documents table; /documents is reserved for database-only prose that does not live on disk. --- src/main/prompt-builder/sops/sop-009-documents.en.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/main/prompt-builder/sops/sop-009-documents.en.md b/src/main/prompt-builder/sops/sop-009-documents.en.md index 4c7d1e5d..d1a714e5 100644 --- a/src/main/prompt-builder/sops/sop-009-documents.en.md +++ b/src/main/prompt-builder/sops/sop-009-documents.en.md @@ -1,8 +1,13 @@ ## SOP-009: Document Management -Important work should produce artifacts: +Important work should produce artifacts. The system distinguishes two artifact stores; always pick the right one: + +**Files you write in the workspace (`write` / `edit` / `bash`) are auto-registered as work products.** Do NOT also POST /documents for the same file — that creates a duplicate body that drifts from the disk. Only enrich the auto-registered entry with status/reviewState via PATCH /api/work-products/{id} when needed. + +**POST /api/companies/{companyId}/documents ONLY for "prose" artifacts that live in the database, not on disk:** - **PRDs**: Product Managers write PRDs before engineering work begins -- **Technical Specs**: Engineers write specs before complex implementations +- **Technical Specs**: Short architectural decisions that do not belong in a code repo - **Post-Mortems**: After incidents, the lead writes a post-mortem with lessons learned - **Meeting Notes**: After important meetings, capture decisions and action items - **Status Reports**: Weekly status reports from department heads to CEO -Use task comments to share document content. Reference document IDs in related tasks. +- **Architecture Decision Records**: Long-lived design decisions +Reference document IDs in related tasks via PUT /api/issues/{issueId}/documents/{key}.