hanoman 0.1.16 → 0.1.19

package/docs/agent-integration.md

@@ -168,12 +168,53 @@ dan tak memakai agent token.
 | `GET /api/specs/:id/review` | `backlog:read` | diff hasil kerja sesi. |
 | `GET /api/projects/:id/docs` | `docs:read` | index Source of Truth project. |
 | `GET /api/projects/:id/docs/<path>` | `docs:read` | isi satu dokumen. |
+| `GET /api/projects/:id/changelog` | `docs:read` | changelog yang sudah dibangkitkan (paginated). |
+| `POST /api/projects/:id/changelog` | `docs:write` | bangkitkan changelog baru — bentuknya di **§6a**. |
 | `GET /api/terminal/sessions` | `sessions:read` | sesi yang sedang hidup. |
-| `GET /api/notifications` | `notifications:read` | notifikasi. |
+| `GET /api/notifications` | `notifications:read` | notifikasi. **Tanpa `limit` → 50 teratas**, bukan seluruhnya (lihat jebakan di §10). |
 | `GET /api/tickets` | `support:read` | tiket Help Center. |
-| `GET /api/lead/decisions` | `lead:read` | jejak keputusan hanoman-lead. |
+| `GET /api/lead/decisions` | `lead:read` | jejak keputusan hanoman-lead. Menerima `page`/`limit`; `take`/`skip` lama tetap jalan. |
+| `GET /api/scheduler/queue` | `settings:read` | antrean scheduler (`?status=queued\|launched\|done\|failed`). `GET /api/scheduler/state` **tak lagi** memuat `queue` — ia memuat `queueCounts`. |
 | `POST /api/lead/decisions` | `lead:write` | minta putusan — baca **§8** dan **§11** dulu. |
 
+## 6a. Changelog per project
+
+Ringkasan perubahan **berorientasi pemakai** — bukan daftar commit. Tiga mode, satu endpoint;
+`mode` menentukan field lainnya:
+
+```bash
+# 1) backlog yang selesai di rentang tanggal (dua field opsional → 30 hari terakhir)
+curl -sS -X POST "$HANOMAN_HOST/api/projects/<id>/changelog" \
+  -H "Authorization: Bearer $HANOMAN_AGENT_TOKEN" -H 'Content-Type: application/json' \
+  -d '{"mode":"backlog","from":"2026-07-01","to":"2026-07-31"}'
+
+# 2) rentang commit di repo project
+  -d '{"mode":"commit","fromSha":"4f2a1c9","toSha":"HEAD"}'
+
+# 3) versi/tag rilis (fromTag opsional → sejak versi sebelumnya)
+  -d '{"mode":"version","toTag":"v1.2.0"}'
+```
+
+Jawaban **201** berisi `body` (markdown siap pakai), `title`, `itemCount`, `generator`, dan
+`warning`. Ambil ulang atau unduh kapan saja:
+
+```bash
+curl -sS "$HANOMAN_HOST/api/projects/<id>/changelog/<cid>?download=md" \
+  -H "Authorization: Bearer $HANOMAN_AGENT_TOKEN"
+```
+
+Tiga hal yang perlu kamu tahu sebelum memanggilnya:
+
+- **Panggil `GET /api/projects/:id/changelog/sources` dulu.** Ia memberi tag yang tersedia, HEAD
+  singkat, rentang default, dan — bila repo belum ditautkan di mesin itu atau belum punya tag — satu
+  `reason` yang menjelaskan sebabnya. Ia menjawab **200**, bukan galat, jadi jangan perlakukan
+  `reason` sebagai kegagalan.
+- **422 berarti permintaanmu sah tapi tak ada isinya** (rentang kosong, repo tanpa tag, revisi tak
+  dikenal) — pesannya bisa langsung diteruskan ke manusia. **400** berarti bentuknya salah
+  (mis. `from` lebih baru dari `to`).
+- **`generator:"fallback"` bukan kegagalan.** Artinya narasi otomatis tak tersedia dan yang kamu
+  terima adalah draf ringkas deterministik; alasannya ada di `warning`.
+
 ## 7. `POST /api/specs` — bentuk payload per `source`
 
 `source` dan bentuk `payload` **saling mengikat**. Salah pasang → **400**
@@ -243,6 +284,8 @@ memanggilnya; jangan lakukan tanpa manusia.
 | **`GET /api/specs/:id` tidak ada** | `GET /api/specs?q=SPEC-489` lalu cocokkan `id` **persis** — `q` itu substring, jadi ia bisa mengembalikan lebih dari satu |
 | daftar mengembalikan amplop `{ items, total, page, pageSize }` | jangan perlakukan responsnya sebagai array |
 | tanpa `limit`, daftar mengembalikan **seluruh** item dalam satu halaman | kirim `limit` untuk backlog besar |
+| **`GET /api/notifications` adalah pengecualiannya**: tanpa `limit` ia mengembalikan **50 teratas**, bukan seluruhnya — angka penuhnya ada di `total` | kirim `page`/`limit` bila kamu butuh riwayat lama; jangan simpulkan `items.length` = seluruh notifikasi |
+| `GET /api/scheduler/state` **tidak lagi** memuat `queue` (SPEC-523/ADR-0107) | baca `queueCounts` untuk hitungan, `GET /api/scheduler/queue?status=…&page&limit` untuk barisnya |
 | `PATCH /api/specs/:id` menolak edit konten begitu item pernah dimulai | ubah `title`/`payload` hanya selagi item belum punya sesi |
 | `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 |

package/package.json

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

package/prisma/migrations/20260803000000_spec_done_at/migration.sql

@@ -0,0 +1,16 @@
+-- SPEC-516 · ADR-0105 · stempel selesai backlog sebagai kolom.
+--
+-- Ditulis tangan (bukan `migrate dev`): worktree tetangga membuat `migrate dev` me-reset DB saat
+-- ada drift. ADITIF murni — satu kolom NULLABLE tanpa default, tak ada tabel diredefinisi.
+-- Larangan SQLite atas `ADD COLUMN … DEFAULT <non-konstan>` (lihat migration SPEC-408) tak
+-- berlaku karena tak ada default sama sekali.
+ALTER TABLE "Spec" ADD COLUMN "doneAt" DATETIME;
+
+-- Backfill sekali-jalan dari stempel yang SUDAH ada: `Notification` ber-key `done:<specId>`
+-- ditulis `recordCompletion` tepat pada transisi ke `done` sejak SPEC-180, di ketiga jalur
+-- persist (dasar yang sama dipakai sweep auto-merge ADR-0103). Item yang selesai sebelum
+-- SPEC-180 — atau yang notifikasinya dihapus operator — tetap NULL; itu keadaan sah yang
+-- dilaporkan sebagai catatan di hasil changelog, bukan disamarkan.
+UPDATE "Spec" SET "doneAt" = (
+  SELECT n."createdAt" FROM "Notification" n WHERE n."key" = 'done:' || "Spec"."id"
+) WHERE "doneAt" IS NULL;

package/prisma/migrations/20260803001000_changelog/migration.sql

@@ -0,0 +1,21 @@
+-- SPEC-516 · ADR-0105 · changelog naratif per project.
+--
+-- Ditulis tangan (bukan `migrate dev`). ADITIF murni — satu tabel baru, nol tabel diredefinisi,
+-- nol baris disentuh. TANPA kolom `version`: tabel ini LOCAL-only dan tak pernah masuk
+-- changefeed sync, persis alasan `LeadFlow` & `WebhookEndpoint`.
+CREATE TABLE "Changelog" (
+    "id"        TEXT NOT NULL PRIMARY KEY,
+    "projectId" TEXT NOT NULL,
+    "mode"      TEXT NOT NULL,
+    "title"     TEXT NOT NULL,
+    "params"    JSONB NOT NULL,
+    "body"      TEXT NOT NULL,
+    "generator" TEXT NOT NULL,
+    "warning"   TEXT,
+    "itemCount" INTEGER NOT NULL DEFAULT 0,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" DATETIME NOT NULL,
+    CONSTRAINT "Changelog_projectId_fkey" FOREIGN KEY ("projectId")
+      REFERENCES "Project" ("id") ON DELETE CASCADE ON UPDATE CASCADE
+);
+CREATE INDEX "Changelog_projectId_createdAt_idx" ON "Changelog"("projectId", "createdAt");

package/prisma/schema.prisma

@@ -28,6 +28,7 @@ model Project {
   tickets      Ticket[]
   customAgents CustomAgent[] // SPEC-450 · ADR-0094 · custom agent milik project ini
   githubIssues GithubIssue[] // SPEC-471 · ADR-0095 · cermin issue repo GitHub project ini
+  changelogs   Changelog[]   // SPEC-516 · ADR-0105 · changelog tersimpan project ini
 }
 
 model Spec {
@@ -51,6 +52,12 @@ model Spec {
   // sama dengan `baseSha` (services/session-launch.ts); jalur RESUME (ADR-0084) sengaja tidak
   // menimpanya — melanjutkan sesi bukan "mulai lagi". null = belum pernah dikerjakan.
   startedAt  DateTime?
+  // SPEC-516 · ADR-0105 · kapan item PERTAMA kali masuk stage `done`. Ditulis HANYA di dalam
+  // `recordCompletion()` — satu-satunya fungsi yang sudah dipanggil oleh KETIGA jalur persist
+  // `done` (advanceStage, scheduler/reconcile, live-specs). Menyalin bookkeeping ini ke call
+  // site adalah kelas bug SPEC-431/448/475. Tulis-sekali: reopen lalu selesai lagi tak
+  // memindahkannya, cermin `startedAt` = mulai pertama (ADR-0090).
+  doneAt     DateTime?
   // SPEC-447 · ADR-0093 · id spec lain yang harus SELESAI & commit-nya sudah ada di branch basis
   // sebelum item ini boleh diluncurkan. Array JSON of string; null/[] = tak bergantung apa pun.
   // Sengaja kolom, bukan tabel join: SQLite melarang scalar list, `Json` sudah dipakai `payload`,
@@ -64,6 +71,29 @@ model Spec {
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
 }
 
+// SPEC-516 · ADR-0105 · changelog naratif per project yang sudah dibangkitkan.
+//
+// LOCAL-only: TANPA kolom `version`, jadi ia tak pernah masuk changefeed sync (cermin LeadFlow,
+// WebhookEndpoint, dan Project.autoMerge). Dua dari tiga modenya diturunkan dari checkout git di
+// MESIN INI, jadi barisnya fakta lokal; yang portabel adalah keluarannya, dan jalannya sudah ada
+// — unduh .md.
+model Changelog {
+  id         String   @id @default(cuid())
+  projectId  String
+  mode       String   // "backlog" | "commit" | "version" (zChangelogMode di @hanoman/shared)
+  title      String   // judul di daftar: rentang tanggal / nama tag / rentang tag
+  params     Json     // parameter pembangkitan apa adanya (zChangelogRequest)
+  body       String   // markdown hasil akhir, sudah lewat scrubOutput
+  generator  String   // "agent" | "fallback"
+  warning    String?  // alasan fallback + catatan cakupan; null = mulus
+  itemCount  Int      @default(0)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+  project    Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([projectId, createdAt])
+}
+
 // SPEC-450 · ADR-0094 · custom agent: persona yang bisa dipilih ulang & dibagi.
 // `projectId` null = GLOBAL (semua project); terisi = milik satu project, dan agen project
 // MENIMPA agen global bernama sama.
@@ -369,7 +399,7 @@ model SchedulerQueueItem {
   projectId  String
   source     String    // backlog | triase (asal checker) — SPEC-384 · `errors` dicabut (ADR-0092)
   priority   String    // tinggi | sedang | rendah (urutan drain)
-  status     String    @default("queued") // queued | launched | done | failed
+  status     String    @default("queued") // queued | launched | done | failed | canceled (SPEC-522 · tombstone operator)
   sessionId  String?
   note       String?   // alasan gagal (diisi daun #5)
   enqueuedAt DateTime  @default(now())