@programinglive/dev-workflow-mcp-server 1.13.15 → 1.14.0

package/AGENTS.md

@@ -7,16 +7,28 @@ You are connected to the `dev-workflow` MCP server. **You MUST NOT perform any c
 ### The Rule of Operation
 Before taking any action or answering user requests regarding code changes, check your workflow status and follow these exact steps in sequence:
 
-1. **Start Task**: Call `start_task` with a clear description and type (`feature`, `bugfix`, `refactor`, or `other`).
+1. **Start Task**: Call `start_task` with a clear description, type (`feature`, `bugfix`, `refactor`, or `other`), `projectDir`, **and a `definitionOfDone` checklist**. Every task must say, up front, which concrete conditions must be true before it counts as finished.
 2. **Implement**: Write your code changes.
 3. **Mark Fixed**: Call `mark_bug_fixed` with a summary of the implementation.
-4. **Create Tests**: Create appropriate unit/integration tests covering your changes.
-5. **Run Tests**: Execute your test suite and call `run_tests` with `passed: true` and the test command. **Never commit if tests fail!**
-6. **Document**: Update documentation (README, PRD, release notes) and call `create_documentation`.
-7. **Ready Check**: Call `check_ready_to_commit` to verify all steps.
-8. **Commit & Push**: Call `commit_and_push` with a conventional commit message.
-9. **Release**: Call `perform_release` with the release command (or `skip_release` if non-Node/docs-only).
-10. **Complete**: Call `complete_task` to finish the session and reset the workflow.
+4. **Prove the Definition of Done**: For each item, call `mark_dod_item` with `evidence` (5-500 characters naming what you actually ran or checked, e.g. `npm test -> 505 pass`). An item that turned out not to apply is excluded with `waive_dod_item` and a written reason - never silently dropped.
+5. **Create Tests**: Create appropriate unit/integration tests covering your changes.
+6. **Run Tests**: Execute your test suite and call `run_tests` with `passed: true` and the test command. **Never commit if tests fail!**
+7. **Document**: Update documentation (README, PRD, release notes) and call `create_documentation`.
+8. **Ready Check**: Call `check_ready_to_commit` to verify all steps. It fails while any definition-of-done item is still open.
+9. **Commit & Push**: Call `commit_and_push` with a conventional commit message. It refuses while any item is open.
+10. **Release**: Call `perform_release` with the release command (or `skip_release` if non-Node/docs-only).
+11. **Complete**: Call `complete_task` to finish the session and reset the workflow. It refuses while any item is open, and records `dodSummary` in history.
+
+### Definition of Done
+
+`start_task` **requires** `definitionOfDone`: 1-20 items, each 3-300 characters, no duplicates. The workflow will not let you commit or close a task while an item is still open.
+
+- `mark_dod_item { id, evidence }` proves an item. Re-marking a proven item refreshes its evidence.
+- `waive_dod_item { id, reason }` excludes an item with a written reason. A proven item cannot be waived.
+- `set_definition_of_done { items, append }` fills the checklist of a task started before this rule existed. Replacing a list that already has proven items is refused unless `append: true`.
+- When new working changes appear after a commit, `dodRevision` goes up and previously proven items must be re-confirmed against the code that is actually being committed. Waivers survive.
+
+`force_complete_task` remains the audited escape hatch: it records `forced: true` with your reason and the DoD summary.
 
 ### Quick Shortcuts
 - If you have all information ready, you can use `run_full_workflow` to execute all steps safely in sequence.

package/README.md

@@ -110,11 +110,14 @@ See [MCP client configuration](#mcp-client-configuration).
 
 ## Available Tools
 
-22 tools.
+25 tools.
 
 | Tool | Purpose |
 |---|---|
-| `start_task` | Begin a task (always the first step) |
+| `start_task` | Begin a task (always the first step); requires `definitionOfDone` |
+| `set_definition_of_done` | Add or replace the checklist of the current task |
+| `mark_dod_item` | Prove one item, with evidence |
+| `waive_dod_item` | Exclude one item, with a reason |
 | `create_feature_flow` | Record the feature flow as Mermaid |
 | `mark_bug_fixed` | Mark the implementation done |
 | `create_tests` | Mark tests as written |
@@ -142,6 +145,33 @@ See [MCP client configuration](#mcp-client-configuration).
 | `claim_factory_task` | Claim a Factory task and start a local workflow |
 | `sync_task_status` | Report a status change back to Factory |
 
+### Definition of Done
+
+Every task carries a checklist of the concrete conditions that must be true before it counts as finished. `start_task` requires it:
+
+```json
+{
+  "description": "Perbaiki validasi form appointment",
+  "type": "bugfix",
+  "projectDir": "D:\\code\\clinic",
+  "definitionOfDone": ["build lulus", "validasi menolak input kosong"]
+}
+```
+
+Each item is later either **proven** or **excluded**, and the workflow refuses to commit or close the task while any item is still open:
+
+```json
+{ "id": "dod-1", "evidence": "php artisan test -> 412 pass" }
+{ "id": "dod-2", "reason": "form ini tidak punya jalur input kosong, sudah dicek di controller" }
+```
+
+- Evidence is required (5-500 characters). It is what separates "proven" from "claimed".
+- An excluded item keeps its reason in the state and in the `history` entry's `definitionOfDoneSummary`.
+- When new working changes appear after a commit, `dodRevision` increments and previously proven items must be re-confirmed against the code that is actually being committed. Waivers survive.
+- A task claimed from the Factory board imports the board checklist as **open** items: a checked box on the board is someone's plan, not proof that this machine ran anything.
+- `set_definition_of_done` fills the checklist of a task started before this rule existed. Replacing a list that already has proven items is refused unless `append: true`.
+- `force_complete_task` is the audited escape hatch: `forced: true`, your reason, and the DoD summary land in history.
+
 ### Factory task integration
 
 Five tools connect this server to the **Factory** board at

package/index.js

@@ -14,7 +14,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { fileURLToPath } from "url";
 import path from "path";
-import { acquireProcessLock, releaseProcessLock, lockWarning } from "./process-lock.js";
+import { acquireProcessLock, releaseProcessLock, lockWarning, projectLockDir } from "./process-lock.js";
 import { exec, setActiveProjectDir } from "./exec.js";
 import { normalizeRequestArgs, shellEscape } from "./utils.js";
 import { createGitFacade } from "./git-facade.js";
@@ -199,26 +199,31 @@ export async function main() {
     // Select request metadata before the first disk write. Creating an idle
     // PID fallback here leaves a phantom session alongside the real sessions.
     safeLog('error', `[${new Date().toISOString()}] Workflow state initialization complete.`);
-
-    // Penanda proses: 31 Oktober 2026 dua proses MCP hidup bersamaan dan
-    // memegang kredensial Factory yang berbeda, sehingga tool yang sama
-    // menjawab berbeda tergantung proses mana yang melayaninya. Proses lain
-    // TIDAK dibunuh (itu berbahaya); cukup dilaporkan supaya pengguna tahu
-    // harus menutup OpenCode dan membukanya lagi.
-    try {
-      const stateDir = path.dirname(path.resolve(workflowState.stateFile));
-      const warning = lockWarning(acquireProcessLock({ dir: stateDir }));
-      if (warning) safeLog('error', warning);
-      process.once('exit', () => releaseProcessLock({ dir: stateDir }));
-    } catch (lockError) {
-      safeLog('error', 'Warning: could not record process lock:', lockError.message);
-    }
   } catch (error) {
     safeLog('error', `[${new Date().toISOString()}] Warning: Failed to initialize workflow state:`, error.message);
     // Continue anyway - workflow state is optional for MCP to function
     workflowState = new WorkflowState();
   }
 
+  // Penanda proses - DI LUAR try di atas, dengan sengaja.
+  //
+  // 31 Oktober 2026: blok ini semula berada di dalam try yang sama dengan
+  // inisialisasi state. Saat dua proses MCP start serempak, satu di antaranya
+  // gagal menginisialisasi state (berebut berkas yang sama), masuk ke catch, dan
+  // penanda prosesnya tidak pernah ditulis. Hasilnya dua proses hidup dengan
+  // satu lock file: proses ganda tidak pernah terdeteksi.
+  //
+  // Lokasinya juga harus di `.state` PROYEK, bukan di direktori user: direktori
+  // user bisa berbeda antar proses, sehingga keduanya tidak saling melihat.
+  try {
+    const lockDir = projectLockDir(workflowState.stateFile);
+    const warning = lockWarning(acquireProcessLock({ dir: lockDir }));
+    if (warning) safeLog('error', warning);
+    process.once('exit', () => releaseProcessLock({ dir: lockDir }));
+  } catch (lockError) {
+    safeLog('error', 'Warning: could not record process lock:', lockError.message);
+  }
+
   const transport = new StdioServerTransport();
   // Cover SDK-generated protocol errors as well as tool-handler responses.
   const send = transport.send.bind(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.13.15",
+  "version": "1.14.0",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "mcpName": "io.github.programinglive/dev-workflow-mcp-server",

package/process-lock.js

@@ -24,6 +24,41 @@ export function processLockPath({ dir }) {
   return path.join(dir, LOCK_FILENAME);
 }
 
+/**
+ * Direktori `.state` milik PROYEK untuk sebuah berkas state.
+ *
+ * Kenapa bukan `path.dirname(stateFile)` saja: berkas state sesi berada di
+ * `.state/users/<user>/`, dan direktori user bisa BERBEDA antar proses (id user
+ * dibuat per direktori state). Pada 31 Oktober 2026 dua proses MCP hidup
+ * bersamaan tetapi hanya satu lock file yang tercipta, karena masing-masing
+ * menulis ke direktori user-nya sendiri - jadi keduanya tidak pernah saling
+ * melihat dan peringatan proses ganda tidak muncul.
+ *
+ * Lock harus satu per PROYEK, bukan per user. Fungsi ini naik sampai menemukan
+ * direktori bernama `.state` dan memakai direktori itu. Kalau tidak ada (state
+ * di luar tata letak itu), pakai direktori berkasnya sendiri.
+ */
+export function projectLockDir(stateFilePath) {
+  const resolved = path.resolve(stateFilePath);
+  let current = path.dirname(resolved);
+  const { root } = path.parse(current);
+
+  while (true) {
+    if (path.basename(current) === ".state") {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current || current === root) {
+      break;
+    }
+
+    current = parent;
+  }
+
+  return path.dirname(resolved);
+}
+
 /**
  * Membaca isi lock, atau null bila tidak ada / tidak terbaca.
  *
@@ -66,7 +101,13 @@ function defaultIsAlive(pid) {
  *   { acquired: true, tookOverFrom: <pid> }   -> pemegang lama sudah mati
  *   { acquired: false, holder: {...} }        -> ada proses lain yang hidup
  */
-export function acquireProcessLock({ dir, pid = process.pid, now = Date.now(), isAlive = defaultIsAlive }) {
+export function acquireProcessLock({
+  dir,
+  pid = process.pid,
+  now = Date.now(),
+  isAlive = defaultIsAlive,
+  writeFileImpl = writeFileSync,
+}) {
   const existing = readProcessLock({ dir });
 
   if (existing && existing.pid !== pid && isAlive(existing.pid)) {
@@ -79,10 +120,17 @@ export function acquireProcessLock({ dir, pid = process.pid, now = Date.now(), i
 
   try {
     mkdirSync(dir, { recursive: true });
-    writeFileSync(processLockPath({ dir }), JSON.stringify(payload), "utf8");
-  } catch {
-    // Tidak bisa menulis penanda bukan alasan mematikan server.
-    return { acquired: true, wrote: false };
+    writeFileImpl(processLockPath({ dir }), JSON.stringify(payload), "utf8");
+  } catch (error) {
+    // Tidak bisa menulis penanda bukan alasan mematikan server, TETAPI juga
+    // tidak boleh ditelan: sampai 31 Oktober 2026 kegagalan ini hanya
+    // mengembalikan { acquired: true } sehingga sistem tampak sehat padahal
+    // tidak ada penanda apa pun di disk. Simpan sebabnya supaya bisa dilaporkan.
+    return {
+      acquired: true,
+      wrote: false,
+      error: (error && (error.code || error.message)) || "unknown",
+    };
   }
 
   return tookOverFrom ? { acquired: true, tookOverFrom } : { acquired: true };
@@ -118,7 +166,16 @@ function safeHostname() {
  * nyata, dan supaya pemanggil bebas memilih tidak menampilkan apa pun.
  */
 export function lockWarning(result) {
-  if (!result || result.acquired !== false || !result.holder) return null;
+  if (!result) return null;
+
+  if (result.wrote === false) {
+    return (
+      `Tidak bisa menulis penanda proses ke ${LOCK_FILENAME} (${result.error}). ` +
+      "Deteksi proses MCP ganda tidak akan bekerja sampai ini diperbaiki."
+    );
+  }
+
+  if (result.acquired !== false || !result.holder) return null;
 
   const started = Number.isFinite(result.holder.startedAt)
     ? new Date(result.holder.startedAt).toISOString()

package/tools/definitions.js

@@ -33,8 +33,87 @@ export function getToolList() {
               "Pass it whenever the session directory is not itself a git repository, " +
               "otherwise the server may fall back to WORKFLOW_PROJECT_DIR and commit to the wrong repo.",
           },
+          definitionOfDone: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            maxItems: 20,
+            description:
+              "REQUIRED. The concrete conditions that must be true before this task counts as done, " +
+              "one condition per item, for example ['build lulus', 'halaman login terverifikasi']. " +
+              "Each item must later be proven with 'mark_dod_item' (evidence required) or waived with " +
+              "'waive_dod_item' (reason required). A task cannot be committed or closed while any item is open.",
+          },
+        },
+        required: ["description", "type", "definitionOfDone"],
+      },
+    },
+    {
+      name: "set_definition_of_done",
+      description:
+        "Add or replace the definition-of-done checklist of the CURRENT task. Use it to fill the checklist of a task started before this feature existed, because a task cannot be committed or closed while any item is open. Replacing a list that already contains proven or waived items is refused unless 'append' is true. Items that are not proven must be waived with a written reason instead of quietly dropped.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          items: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            maxItems: 20,
+            description:
+              "Conditions that must be true before the task is done, 3-300 characters each, for example ['build lulus', 'halaman login terverifikasi'].",
+          },
+          append: {
+            type: "boolean",
+            description:
+              "When true, add the items to the existing checklist instead of replacing it. Required when the current checklist already has proven or waived items.",
+          },
+          reason: {
+            type: "string",
+            description: "Optional note recorded with the change.",
+          },
+        },
+        required: ["items"],
+      },
+    },
+    {
+      name: "mark_dod_item",
+      description:
+        "Mark one definition-of-done item as proven, with the evidence that proves it. Evidence is required: 5-500 characters naming what was actually run or checked, for example 'npm test -> 482 pass'. Marking an already-proven item again is allowed and refreshes its evidence, which is how a stale item is re-confirmed after new changes. Waived items cannot be marked; reinstate them with set_definition_of_done { append: true }.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: "Item id from start_task, get_workflow_status, or set_definition_of_done (for example 'dod-2').",
+          },
+          evidence: {
+            type: "string",
+            description:
+              "What proves the condition is true, 5-500 characters. Name the command and its result, or the page and what you saw.",
+          },
+        },
+        required: ["id", "evidence"],
+      },
+    },
+    {
+      name: "waive_dod_item",
+      description:
+        "Exclude one definition-of-done item with a written reason, for work that turned out not to be needed for this task. The reason is required (5-500 characters) and is recorded in the state and in the history entry, so it must be readable by someone else. A proven item cannot be waived.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: "Item id from start_task or get_workflow_status (for example 'dod-3').",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Why this condition does not apply to this task, 5-500 characters. Do not use it to avoid work that is actually required.",
+          },
         },
-        required: ["description", "type"],
+        required: ["id", "reason"],
       },
     },
     {

package/tools/handler-modules/commit-handlers.js

@@ -1,5 +1,6 @@
 import { textResponse, isReleaseSatisfied, formatChecklist } from "./shared.js";
 import { handleReadyCheck } from "./status-handlers.js";
+import { openItems, renderChecklist, renderOutstanding, summarize } from "./dod.js";
 import { containsTestFilesInStatus } from "../../git-helpers.js";
 import { resolveProjectDir, setActiveProjectDir, getActiveProjectDir } from "../../exec.js";
 import path from "path";
@@ -122,6 +123,23 @@ export async function handleCommitAndPush(args, context) {
 
   workflowState.state.projectDir = getActiveProjectDir() || workflowState.state.projectDir || "";
 
+  // Guard DoD yang eksplisit. `handleReadyCheck` di bawah sudah menutupi ini
+  // secara transitif, tetapi pesannya generik ("NOT READY"); di sini kita bisa
+  // menyebut item mana yang menghalangi, sebelum satu perintah git pun jalan.
+  const dodItems = Array.isArray(workflowState.state.definitionOfDone)
+    ? workflowState.state.definitionOfDone
+    : [];
+  const outstanding = openItems(dodItems, workflowState.state.dodRevision);
+  if (outstanding.length > 0) {
+    return textResponse(
+      `⚠️ Dibatalkan: ${outstanding.length} item Definition of Done belum terpenuhi.\n\n` +
+        `${renderOutstanding(dodItems, workflowState.state.dodRevision)}\n\n` +
+        `Buktikan dengan 'mark_dod_item' { id, evidence }, atau kecualikan dengan ` +
+        `'waive_dod_item' { id, reason }.\n\n` +
+        `Tidak ada yang di-stage dan tidak ada yang di-commit.`
+    );
+  }
+
   if (!workflowState.state.readyToCommit || !workflowState.state.readyCheckCompleted) {
     const readyResponse = await handleReadyCheck(workflowState);
     if (workflowState.state.currentPhase !== "commit") {
@@ -302,10 +320,35 @@ export async function handleCommitAndPush(args, context) {
 }
 
 export async function handleCompleteTask(args, workflowState) {
+  // Sampai 31 Oktober 2026 fungsi ini tidak memeriksa apa pun: task bisa
+  // ditutup dengan DoD kosong atau masih penuh item terbuka. Sekarang tidak.
+  const dodState = workflowState.state;
+  const dodItems = Array.isArray(dodState.definitionOfDone) ? dodState.definitionOfDone : [];
+  const dod = summarize(dodItems, dodState.dodRevision);
+
+  if (dodItems.length === 0) {
+    return textResponse(
+      `⚠️ Task ini belum punya Definition of Done, jadi belum bisa ditutup.\n\n` +
+        `Isi dulu dengan 'set_definition_of_done' { items: [...] }, buktikan tiap item, lalu ulangi 'complete_task'.\n` +
+        `Kalau memang harus ditutup sekarang, pakai 'force_complete_task' dengan alasan - langkah itu tercatat.`
+    );
+  }
+
+  if (dod.open > 0) {
+    const outstanding = openItems(dodItems, dodState.dodRevision);
+    return textResponse(
+      `⚠️ ${dod.open} item Definition of Done masih terbuka:\n\n` +
+        `${renderOutstanding(dodItems, dodState.dodRevision)}\n\n` +
+        `Buktikan dengan 'mark_dod_item' { id, evidence } atau kecualikan dengan ` +
+        `'waive_dod_item' { id, reason }.`
+    );
+  }
+
   const entry = {
     taskDescription: workflowState.state.taskDescription,
     taskType: workflowState.state.taskType,
     commitMessage: args.commitMessage,
+    definitionOfDoneSummary: dod,
   };
 
   workflowState.addToHistory(entry);
@@ -313,7 +356,8 @@ export async function handleCompleteTask(args, workflowState) {
   await workflowState.save();
 
   return textResponse(
-    `✅ Task completed!\n\nCommit message: ${args.commitMessage}\nHistory recorded.`
+    `✅ Task completed!\n\nCommit message: ${args.commitMessage}\n` +
+      `DoD: ${dod.done}/${dod.total} terbukti, ${dod.waived} dikecualikan.\nHistory recorded.`
   );
 }
 
@@ -331,6 +375,10 @@ export async function handleForceCompleteTask(args, workflowState) {
     commitMessage,
     forced: true,
     forceReason: reason,
+    definitionOfDoneSummary: summarize(
+      Array.isArray(workflowState.state.definitionOfDone) ? workflowState.state.definitionOfDone : [],
+      workflowState.state.dodRevision,
+    ),
   });
 
   workflowState.reset();
@@ -350,6 +398,10 @@ export async function handleDropTask(args, workflowState) {
     commitMessage: workflowState.state.lastCommitMessage,
     dropped: true,
     dropReason: typeof args.reason === "string" ? args.reason : "",
+    definitionOfDoneSummary: summarize(
+      Array.isArray(workflowState.state.definitionOfDone) ? workflowState.state.definitionOfDone : [],
+      workflowState.state.dodRevision,
+    ),
   });
   workflowState.reset();
   await workflowState.save();

package/tools/handler-modules/dod-handlers.js

@@ -0,0 +1,217 @@
+/**
+ * Handler untuk Definition of Done.
+ *
+ * Tipis dengan sengaja: aturan "apa yang sah" hidup di `dod.js`, dan handler di
+ * sini hanya memvalidasi, mengubah state, lalu menyimpan. Kalau logika aturan
+ * ikut masuk ke sini, ia hanya bisa diuji lewat MCP penuh.
+ */
+import { textResponse } from "./shared.js";
+import {
+  MAX_ITEMS,
+  MAX_EVIDENCE,
+  MIN_EVIDENCE,
+  validateItemTexts,
+  nextItemId,
+  renderChecklist,
+} from "./dod.js";
+
+function noActiveTask() {
+  return textResponse("⚠️ No active task. Use 'start_task' first, or 'set_definition_of_done' after starting one.");
+}
+
+function findItem(state, id) {
+  const items = Array.isArray(state.definitionOfDone) ? state.definitionOfDone : [];
+  return items.find((item) => item.id === id) || null;
+}
+
+function itemList(state) {
+  const items = Array.isArray(state.definitionOfDone) ? state.definitionOfDone : [];
+  return items.map((item) => `   ${item.id} [${item.status}]: ${item.text}`).join("\n");
+}
+
+function touch(workflowState) {
+  workflowState.state.readyCheckCompleted = false;
+  workflowState.state.readyToCommit = false;
+}
+
+function newItem(text, state) {
+  return {
+    id: nextItemId(state.definitionOfDone || []),
+    text,
+    status: "open",
+    evidence: "",
+    waivedReason: "",
+    revision: Number(state.dodRevision) || 0,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export async function handleSetDefinitionOfDone(args, workflowState) {
+  const state = workflowState.state;
+  if (!state || state.currentPhase === "idle") {
+    return noActiveTask();
+  }
+
+  const check = validateItemTexts(args.items);
+  if (!check.ok) {
+    return textResponse(
+      `⚠️ ${check.error}\n\n` +
+        `Contoh:\n  items: ["build lulus", "halaman login terverifikasi"]`,
+    );
+  }
+
+  const existing = Array.isArray(state.definitionOfDone) ? state.definitionOfDone : [];
+  const append = args.append === true;
+
+  // Mengganti seluruh daftar saat sudah ada bukti berarti membuang bukti yang
+  // mungkin sudah diperiksa manusia. Itu tidak boleh terjadi diam-diam.
+  if (!append) {
+    const proven = existing.filter((item) => item.status === "done" || item.status === "waived");
+    if (proven.length > 0) {
+      return textResponse(
+        `⚠️ Daftar ini sudah punya ${proven.length} item yang terbukti atau dikecualikan:\n${itemList(state)}\n\n` +
+          `Mengganti seluruh daftar akan membuang bukti itu. Pilih salah satu:\n` +
+          `  - tambahkan item baru: set_definition_of_done { items: [...], append: true }\n` +
+          `  - mulai ulang workflow: rerun_workflow`,
+      );
+    }
+  }
+
+  const total = (append ? existing.length : 0) + check.items.length;
+  if (total > MAX_ITEMS) {
+    return textResponse(
+      `⚠️ Total item DoD akan menjadi ${total}, melebihi batas ${MAX_ITEMS}. ` +
+        `Ringkas kondisi yang sejenis sebelum menambah.`,
+    );
+  }
+
+  // Duplikat terhadap item yang SUDAH ada juga harus ditolak: dua item dengan
+  // teks sama hanya membuat gerbang bertanya dua kali.
+  const seen = new Set((append ? existing : []).map((item) => item.text.toLowerCase()));
+  for (const text of check.items) {
+    if (seen.has(text.toLowerCase())) {
+      return textResponse(
+        `⚠️ Item "${text}" sudah ada di daftar DoD task ini. Hapus duplikatnya dari permintaan.`,
+      );
+    }
+    seen.add(text.toLowerCase());
+  }
+
+  const items = append ? existing.slice() : [];
+  for (const text of check.items) {
+    items.push(newItem(text, { ...state, definitionOfDone: items }));
+  }
+
+  state.definitionOfDone = items;
+  if (state.dodSource !== "factory") {
+    state.dodSource = "manual";
+  }
+  touch(workflowState);
+  await workflowState.save();
+
+  return textResponse(
+    `✅ Definition of Done ${append ? "ditambah" : "disusun"}: ${items.length} item.\n\n` +
+      renderChecklist(items, state.dodRevision) +
+      `\n\nBuktikan dengan 'mark_dod_item' { id, evidence } atau kecualikan dengan 'waive_dod_item' { id, reason }.`,
+  );
+}
+
+export async function handleMarkDodItem(args, workflowState) {
+  const state = workflowState.state;
+  if (!state || state.currentPhase === "idle") {
+    return noActiveTask();
+  }
+
+  const id = typeof args.id === "string" ? args.id.trim() : "";
+  if (!id) {
+    return textResponse(`⚠️ Sebutkan 'id' item DoD. Yang tersedia:\n${itemList(state)}`);
+  }
+
+  const item = findItem(state, id);
+  if (!item) {
+    return textResponse(`⚠️ Tidak ada item DoD dengan id "${id}". Yang tersedia:\n${itemList(state)}`);
+  }
+
+  if (item.status === "waived") {
+    return textResponse(
+      `⚠️ Item "${item.text}" sudah dikecualikan (${item.waivedReason}).\n` +
+        `Kalau sekarang benar-benar perlu dibuktikan, tambahkan sebagai item baru dengan ` +
+        `set_definition_of_done { items: [...], append: true }.`,
+    );
+  }
+
+  const evidence = typeof args.evidence === "string" ? args.evidence.trim() : "";
+  if (evidence.length < MIN_EVIDENCE || evidence.length > MAX_EVIDENCE) {
+    return textResponse(
+      `⚠️ 'evidence' untuk "${item.text}" harus ${MIN_EVIDENCE}-${MAX_EVIDENCE} karakter dan menyebut buktinya, ` +
+        `contoh: "npm test → 482 pass".\n` +
+        `Bukti adalah yang membuat item ini berbeda dari sekadar klaim.`,
+    );
+  }
+
+  item.status = "done";
+  item.evidence = evidence;
+  item.waivedReason = "";
+  item.revision = Number(state.dodRevision) || 0;
+  item.updatedAt = new Date().toISOString();
+
+  touch(workflowState);
+  await workflowState.save();
+
+  const remaining = state.definitionOfDone.filter((candidate) => candidate.status === "open");
+
+  return textResponse(
+    `✅ Item "${item.text}" terbukti: ${evidence}\n\n` +
+      renderChecklist(state.definitionOfDone, state.dodRevision) +
+      (remaining.length === 0
+        ? `\n\nSemua item DoD sudah terpenuhi.`
+        : `\n\nMasih ${remaining.length} item terbuka: ${remaining.map((candidate) => candidate.id).join(", ")}.`),
+  );
+}
+
+export async function handleWaiveDodItem(args, workflowState) {
+  const state = workflowState.state;
+  if (!state || state.currentPhase === "idle") {
+    return noActiveTask();
+  }
+
+  const id = typeof args.id === "string" ? args.id.trim() : "";
+  if (!id) {
+    return textResponse(`⚠️ Sebutkan 'id' item DoD. Yang tersedia:\n${itemList(state)}`);
+  }
+
+  const item = findItem(state, id);
+  if (!item) {
+    return textResponse(`⚠️ Tidak ada item DoD dengan id "${id}". Yang tersedia:\n${itemList(state)}`);
+  }
+
+  if (item.status === "done") {
+    return textResponse(
+      `⚠️ Item "${item.text}" sudah terbukti (${item.evidence}); tidak ada yang perlu dikecualikan.`,
+    );
+  }
+
+  const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+  if (reason.length < MIN_EVIDENCE || reason.length > MAX_EVIDENCE) {
+    return textResponse(
+      `⚠️ 'reason' untuk "${item.text}" harus ${MIN_EVIDENCE}-${MAX_EVIDENCE} karakter dan menjelaskan ` +
+        `mengapa kondisi ini tidak berlaku untuk task ini.\n` +
+        `Alasan ini dicatat di state dan di history, jadi tulis yang bisa dibaca orang lain.`,
+    );
+  }
+
+  item.status = "waived";
+  item.waivedReason = reason;
+  item.evidence = "";
+  item.revision = Number(state.dodRevision) || 0;
+  item.updatedAt = new Date().toISOString();
+
+  touch(workflowState);
+  await workflowState.save();
+
+  return textResponse(
+    `⚠️ Item "${item.text}" dikecualikan: ${reason}\n\n` +
+      renderChecklist(state.definitionOfDone, state.dodRevision) +
+      `\n\nPengecualian tercatat dan akan muncul di history saat task ditutup.`,
+  );
+}