hanoman 0.1.45 → 0.1.47

package/docs/agent-integration.md

@@ -169,6 +169,10 @@ dan tak memakai agent token.
 | `POST /api/specs` | `backlog:write` | buat backlog item — bentuk payload di §7. |
 | `PATCH /api/specs/:id` | `backlog:write` | ubah item; konten hanya selagi belum dimulai. |
 | `POST /api/specs/:id/done` | `backlog:write` | tandai item **selesai** tanpa menjalankan sesi — untuk pekerjaan yang beres di luar hanoman. Body `{ reason?: string (≤280), confirm?: boolean }`, keduanya opsional; balasannya `Spec` yang sudah `stage:"done"`. Tak menjalankan maupun menghentikan sesi apa pun. |
+| `GET /api/specs/:id/attachments` | `backlog:read` | lampiran backlog item — gambar & dokumen yang dilampirkan manusia sebagai konteks kerja. |
+| `POST /api/specs/:id/attachments` | `backlog:write` | unggah lampiran (`multipart/form-data`, beberapa berkas per request). Berkas yang ditolak **tak** menggagalkan yang lain — periksa `rejected[]`. |
+| `GET /api/specs/:id/attachments/:attId` | `backlog:read` | byte satu lampiran. |
+| `DELETE /api/specs/:id/attachments/:attId` | `backlog:write` | hapus satu lampiran. |
 | `GET /api/specs/:id/docs` | `backlog:read` | dokumen yang ditulis sesi item itu. |
 | `GET /api/specs/:id/review` | `backlog:read` | diff hasil kerja sesi. |
 | `GET /api/projects/:id/docs` | `docs:read` | index Source of Truth project. |
@@ -299,6 +303,7 @@ memanggilnya; jangan lakukan tanpa manusia.
 | `branchFrom` yang tak ada di repo project → **400**, bukan diterima lalu gagal di tengah sesi | ambil kandidatnya dari `GET /api/projects/:id/branches` |
 | **401 telanjang** tak memisahkan "host salah" dari "token salah" dari "master switch mati" | probe `GET /api/health` sekali: 200 = host benar → masalahnya token atau master switch |
 | **403** bukan kegagalan permanen | bacalah field `need`, sampaikan ke manusia, minta capability itu ditambahkan |
+| **Lampiran backlog tak menyeberang sync** (`SpecAttachment` LOCAL-only, ADR-0124) | item yang sama di instance lain tampil **tanpa** lampiran. Kalau lampiran yang disebut manusia tak kamu temukan, kemungkinan besar kamu bicara ke instance yang bukan tempat lampiran itu diunggah — tanyakan, jangan simpulkan lampirannya tak ada |
 
 ## 10. Contoh alur end-to-end
 
@@ -461,6 +466,11 @@ dan seluruh `/api/vps*` (remote exec) **tidak ikut**, begitu pula merge/rebase (
 penghapusan backlog, dan perubahan `stage`. Batasan ini ada di katalog toolnya, bukan di token:
 token yang punya `sessions:write` sekalipun tak akan menemukan tool untuk memakainya. Lihat §8.
 
+**Lampiran backlog** (`/api/specs/:id/attachments*`, SPEC-843 · ADR-0124) juga sengaja **tak punya
+tool**: berkasnya lahir dari disk manusia, bukan dari model, dan tool MCP berbentuk JSON sehingga
+byte biner tak punya representasi di sana. REST-nya tetap terjangkau agent token
+ber-`backlog:read`/`backlog:write` — yang tak dipajang adalah **tool**-nya.
+
 ### Opsi
 
 | Variabel / flag | Arti |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanoman",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "Orchestrator + dashboard workflow docs-driven untuk sesi Claude Code / Codex",
   "type": "module",
   "repository": {

package/prisma/migrations/20260819120000_spec_attachment/migration.sql

@@ -0,0 +1,19 @@
+-- SPEC-843 · ADR-0124 · lampiran per backlog item.
+--
+-- Ditulis tangan (bukan `migrate dev`): worktree tetangga membuat `migrate dev` me-reset DB saat
+-- ada drift. ADITIF murni — satu tabel baru, tak ada tabel yang diredefinisi.
+--
+-- TANPA kolom `version`: entitas ini LOCAL-only dan tak pernah masuk changefeed sync.
+CREATE TABLE "SpecAttachment" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "specId" TEXT NOT NULL,
+    "projectId" TEXT NOT NULL,
+    "filename" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "SpecAttachment_specId_fkey" FOREIGN KEY ("specId") REFERENCES "Spec" ("id") ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE INDEX "SpecAttachment_specId_idx" ON "SpecAttachment"("specId");

package/prisma/schema.prisma

@@ -87,6 +87,30 @@ model Spec {
   sourceHistory Json?
   updatedAt  DateTime @updatedAt
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  attachments SpecAttachment[]
+}
+
+// SPEC-843 · ADR-0124 · lampiran per backlog item — konteks yang dipegang manusia saat memfilekan
+// item, dibaca agen di dalam sesi. Byte hidup di HANOMAN_UPLOAD_DIR (server-local, di luar repoDir);
+// `storageKey` opaque, `filename` nama asli tersanitasi untuk tampilan saja.
+//
+// LOCAL-only: TANPA `version`, jadi ia tak pernah masuk changefeed sync (cermin LeadFlow,
+// WebhookEndpoint, Changelog). Byte memang tak menyeberang (ADR-0062), dan metadata yang menyeberang
+// TANPA byte-nya hanya menghasilkan lampiran yang tak bisa dibuka di mesin lain — keadaan terburuk
+// dari ketiga pilihan. Sengaja BUKAN TicketAttachment: tiket dan backlog dua domain dengan aturan
+// sync dan tingkat kepercayaan yang berbeda (ADR-0124 §1/§4).
+model SpecAttachment {
+  id         String   @id @default(cuid())
+  specId     String
+  projectId  String   // denormal — kuota & isolasi per project, cermin TicketAttachment
+  filename   String
+  mimeType   String
+  size       Int
+  storageKey String
+  createdAt  DateTime @default(now())
+  spec       Spec     @relation(fields: [specId], references: [id], onDelete: Cascade)
+
+  @@index([specId])
 }
 
 // SPEC-516 · ADR-0105 · changelog naratif per project yang sudah dibangkitkan.