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.
This commit is contained in:
ZacharyZhang-NY committed 2026-04-19 19:21:04 -04:00
1 parent b6184b5bf3
commit fcf78e8a7e
1 file changed
+8 -3
@@ -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}.