@programinglive/dev-workflow-mcp-server 1.14.1 → 1.15.0

package/AGENTS.md

@@ -8,6 +8,8 @@ You are connected to the `dev-workflow` MCP server. **You MUST NOT perform any c
 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, 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.
+
+   `start_task` **refuses** when another live MCP process is working the same project (heartbeat within the last 10 minutes). Two sessions on one working tree overwrite each other's files silently — on 31 October 2026 a session lost every edit in `tools/handler-modules/index.js` that way. Close the other window, use a git worktree, or pass `force: true` when you know the other session is idle. The check runs before any state is touched, so a refused call changes nothing.
 2. **Implement**: Write your code changes.
 3. **Mark Fixed**: Call `mark_bug_fixed` with a summary of the implementation.
 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.
@@ -16,6 +18,12 @@ Before taking any action or answering user requests regarding code changes, chec
 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.
+
+   If the repo also contains another session's uncommitted work, `commit_and_push`
+   refuses to stage the whole tree. Pass `paths` with only the files this task
+   touched (recommended), or `includeForeign: true` after verifying that work
+   belongs in this commit. Never resolve it by overwriting the other session's
+   files.
 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.
 
@@ -32,6 +40,10 @@ Before taking any action or answering user requests regarding code changes, chec
 
 ### Quick Shortcuts
 - If you have all information ready, you can use `run_full_workflow` to execute all steps safely in sequence.
+  It requires `dodEvidence` for every definition-of-done item that is still open — for example
+  `"dodEvidence": { "dod-1": "npm test -> 533 pass" }`. Without it the call stops **before the first step** and
+  lists the items it needs, because it cannot invent proof. The evidence is recorded just before the ready check,
+  so it describes code that has already been written.
 - Use `get_workflow_status` at any time to check what step is next.
 
 **Do not bypass these steps. The MCP server will block commits and releases if any required step is skipped.**

package/README.md

@@ -125,14 +125,14 @@ See [MCP client configuration](#mcp-client-configuration).
 | `run_tests` | Record test results (blocks commit when failing) |
 | `create_documentation` | Mark docs as written |
 | `check_ready_to_commit` | Verify every required step is complete |
-| `commit_and_push` | `git add` → `commit` → `push` |
-| `perform_release` | Record a release |
+| `commit_and_push` | `git add` → `commit` → `push`, refusing to sweep in another session's work |
+| `perform_release` | Record a release; runs even when only another session's files are left unstaged |
 | `skip_release` | Skip the release step with a justification |
 | `complete_task` | Finish and reset the workflow |
 | `get_workflow_status` | Show the current phase |
 | `continue_workflow` | Get guidance on the next step |
 | `view_history` | List completed tasks |
-| `run_full_workflow` | Run every step in one call |
+| `run_full_workflow` | Run every step in one call (requires `dodEvidence` for open items) |
 | `rerun_workflow` | Restart the current task from the beginning |
 | `drop_task` | Abandon the task without completing it |
 | `force_complete_task` | Complete despite missing steps, with a reason |
@@ -611,6 +611,66 @@ fail on husky.
 - Committing without documentation
 - Forgetting a workflow step
 - Releasing without committing and pushing
+- Committing another session's uncommitted work by accident
+- Blocking a release because another session's work is deliberately left alone
+
+---
+
+## Committing when someone else is editing the same repo
+
+`commit_and_push` stages the working tree, so pre-existing changes from another
+session ride along into your commit — and once committed, they cannot be
+separated from yours. Observed on 31 Oct 2026: two lines of another session's
+`billing.yaml` landed in an unrelated commit, and a `devices.yaml` being edited
+elsewhere nearly got overwritten.
+
+The guard has three parts:
+
+1. **`start_task` records a baseline** (`dirtyAtStart`): every path that was
+   already dirty when the task began.
+2. **`commit_and_push` refuses** when any of those paths is still dirty. Files
+   that appear *during* the task are never blamed — there is no way to tell a
+   new file of yours from a new file of theirs, and false accusations would get
+   the check ignored.
+3. **You choose explicitly**:
+
+   ```jsonc
+   // recommended: stage only what this task touched
+   {"commitMessage": "fix: ...", "paths": ["src/app.js", "tests/app.test.js"]}
+
+   // or, after verifying the other work belongs here
+   {"commitMessage": "fix: ...", "includeForeign": true}
+   ```
+
+With `paths`, staging is `git add -- <paths>` instead of `git add .`, and any
+file left unstaged is listed in the success message so it is not silently
+forgotten.
+
+Failure is closed, not open: the refusal happens *before* `git add`, so nothing
+is staged and nothing is committed. Tasks started before this feature have no
+baseline and keep the old behaviour.
+
+Known limit: this catches work that was **already** dirty when the task started.
+A file created by another session mid-task cannot be attributed, because git
+records content, not authorship.
+
+### What this means for `perform_release`
+
+Release used to require a completely clean working tree, which was correct while
+commits swept everything. Once `commit_and_push` deliberately *leaves* another
+session's work unstaged, that rule would block every release — and its advice
+("commit or stash all changes") would ask you to commit exactly what the guard
+just refused.
+
+So `perform_release` now distinguishes two kinds of dirt:
+
+| Working tree contains | Release |
+|---|---|
+| only paths from `dirtyAtStart` | runs, and lists them as deliberately left alone |
+| any path that is not in the baseline | refused, naming those files |
+
+Without a baseline (tasks started before this feature) the old strict rule
+applies: anything dirty blocks the release.
 
 ---
 
@@ -619,14 +679,23 @@ fail on husky.
 1. Always start with `start_task` — it sets the intent for the session
 2. Do not skip tests unless it is genuinely impossible — use `skip_tests` with a clear reason
 3. Call `get_workflow_status` whenever you lose track of the phase
-4. `run_full_workflow` is a shortcut for simple tasks where all the data is already known
+4. `run_full_workflow` is a shortcut for simple tasks where all the data is already known. Pass
+   `dodEvidence` keyed by item id (`{ "dod-1": "npm test -> 533 pass" }`); without it the call refuses up front
+   instead of stopping halfway with implementation, tests and docs already recorded but nothing committed
 5. For docs-only work, use `skip_release` rather than forcing a release
 
 ---
 
 ## Troubleshooting
 
-**`ERR_MODULE_NOT_FOUND: Cannot find package 'dotenv'`** — dependencies are not
+**`start_task` refuses because another session is working the same project.** A
+second session on one working tree silently overwrites the first session's files.
+Close the other OpenCode window, or give this session its own checkout with
+`git worktree add <path> -b <branch>` and run it from there. The check ignores
+locks with no heartbeat for 10 minutes, so a leftover MCP process does not block
+you; `force: true` overrides it when you know the other session is idle.
+
+**`ERR_MODULE_NOT_FOUND: Cannot find package 'dotenv'`** - dependencies are not
 installed. Run `npm install` in the repo.
 
 **`gyp ERR! find VS` on Windows** — the native module is compiling from source

package/db/adapters/sqlite.js

@@ -1,6 +1,6 @@
 import { safeLog } from '../../security/sanitizer.js';
 import Database from "better-sqlite3";
-import { existsSync } from "fs";
+import { existsSync, mkdirSync } from "fs";
 import path from "path";
 import { DbAdapter, normalizeTaskType } from "./base.js";
 import { assertSafeKnowledge, classify } from '../../security/policy.js';
@@ -43,6 +43,11 @@ export class SqliteAdapter extends DbAdapter {
     async connect() {
         if (!this.db) {
             const dbPath = this.getDbPath();
+            // Direktori induk belum tentu ada: pada clone bersih, `.state/`
+            // belum pernah dibuat. Tanpa ini SQLite melempar
+            // "Cannot open database because the directory does not exist" -
+            // hijau di mesin penulis, merah di tempat lain.
+            mkdirSync(path.dirname(dbPath), { recursive: true });
             this.db = new Database(dbPath);
             this.db.pragma("journal_mode = WAL");
             await this.migrate();

package/git-facade.js

@@ -20,6 +20,9 @@ import {
   hasStagedChanges,
   hasTestChanges,
   hasWorkingChanges,
+  foreignDirtyEntries,
+  hasOnlyForeignChanges,
+  parseStatusEntries,
   workingTreeSummary,
 } from "./git-helpers.js";
 
@@ -37,5 +40,8 @@ export function createGitFacade() {
     getStatusOutput,
     getToplevel,
     workingTreeSummary,
+    parseStatusEntries,
+    foreignDirtyEntries,
+    hasOnlyForeignChanges,
   };
 }

package/git-helpers.js

@@ -94,6 +94,93 @@ export function containsTestFilesInStatus(statusOutput) {
     .some((path) => isTestFilePath(path));
 }
 
+/**
+ * `git status --porcelain` -> [{code, path}].
+ *
+ * Dipakai untuk dua hal: mencatat berkas yang SUDAH kotor saat `start_task`
+ * (baseline), dan membandingkannya lagi saat commit. Tanpa ini, `git add .`
+ * tidak bisa membedakan pekerjaan sesi ini dari pekerjaan sesi lain.
+ *
+ * Path TIDAK dibaca dengan `slice(3)`: format porcelain adalah `XY path`
+ * (X = index, Y = worktree), jadi perubahan yang belum di-stage berbentuk
+ * `" M path"` sementara berkas baru berbentuk `"?? path"`. Memotong kolom tetap
+ * memakan huruf pertama nama berkas - pernah menghasilkan `nowledge/...`.
+ */
+export function parseStatusEntries(statusOutput) {
+  if (typeof statusOutput !== "string") {
+    return [];
+  }
+
+  return statusOutput
+    .split("\n")
+    .filter((line) => line && line.trim().length > 0)
+    .map((line) => {
+      const match = /^\s*([MADRCU?!]{1,2})\s+(.*)$/.exec(line);
+      if (!match) {
+        return null;
+      }
+      const rawPath = match[2].trim();
+      const target = rawPath.includes(" -> ")
+        ? rawPath.split(" -> ").pop().trim()
+        : rawPath;
+      return target ? { code: match[1], path: target } : null;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Berkas yang sudah kotor SEBELUM task dimulai dan masih kotor sekarang.
+ *
+ * Ini satu-satunya atribusi yang bisa dipercaya: berkas yang sudah kotor di
+ * baseline bukan hasil pekerjaan sesi ini. Berkas baru yang muncul selama task
+ * sengaja TIDAK masuk sini - tidak ada cara membedakan berkas baru milik kita
+ * dari berkas baru milik sesi lain, dan menebaknya akan menghasilkan tuduhan
+ * palsu yang membuat fitur ini diabaikan.
+ */
+export function foreignDirtyEntries(baselineEntries, statusOutput) {
+  const baseline = new Set(
+    (Array.isArray(baselineEntries) ? baselineEntries : [])
+      .map((entry) => String(entry?.path || "").trim())
+      .filter(Boolean),
+  );
+  if (baseline.size === 0) {
+    return [];
+  }
+
+  return parseStatusEntries(statusOutput).filter((entry) => baseline.has(entry.path));
+}
+
+/**
+ * Apakah SELURUH working tree hanya berisi berkas yang sudah kotor sejak
+ * `start_task`.
+ *
+ * Dipakai `perform_release`. Sebelumnya rilis menuntut working tree benar-benar
+ * bersih, dan itu benar selama commit menyapu semua. Setelah `commit_and_push`
+ * sengaja MENINGGALKAN pekerjaan sesi lain, syarat itu berubah jadi jebakan:
+ * rilis menolak selamanya dan menyarankan "commit or stash", padahal
+ * meng-commit berkas itu justru yang kita cegah.
+ *
+ * Mengembalikan false kalau baseline kosong: tanpa baseline tidak ada dasar
+ * untuk menyatakan sesuatu "bukan milik kita", jadi perilaku lama dipertahankan.
+ */
+export function hasOnlyForeignChanges(baselineEntries, statusOutput) {
+  const baseline = new Set(
+    (Array.isArray(baselineEntries) ? baselineEntries : [])
+      .map((entry) => String(entry?.path || "").trim())
+      .filter(Boolean),
+  );
+  if (baseline.size === 0) {
+    return false;
+  }
+
+  const current = parseStatusEntries(statusOutput);
+  if (current.length === 0) {
+    return false;
+  }
+
+  return current.every((entry) => baseline.has(entry.path));
+}
+
 function parseNameStatusLine(line) {
   if (!line) {
     return null;

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, projectLockDir } from "./process-lock.js";
+import { acquireProcessLock, releaseProcessLock, lockWarning, projectLockDir, refreshProcessLock, HEARTBEAT_MS } from "./process-lock.js";
 import { exec, setActiveProjectDir } from "./exec.js";
 import { normalizeRequestArgs, shellEscape } from "./utils.js";
 import { createGitFacade } from "./git-facade.js";
@@ -220,6 +220,16 @@ export async function main() {
     const warning = lockWarning(acquireProcessLock({ dir: lockDir }));
     if (warning) safeLog('error', warning);
     process.once('exit', () => releaseProcessLock({ dir: lockDir }));
+
+    // Detak jantung penanda proses.
+    //
+    // Tanpa ini, penanda hanya menyebut KAPAN proses start. Proses MCP yang
+    // tertinggal hidup setelah jendela OpenCode-nya ditutup akan terlihat sama
+    // hidupnya dengan sesi yang benar-benar bekerja, sehingga aturan "satu
+    // penulis per repo" tidak bisa ditegakkan tanpa memblokir sesi yang sah.
+    // Dengan detak, "hidup" berarti "hidup DAN baru saja bekerja".
+    const heartbeat = setInterval(() => refreshProcessLock(), HEARTBEAT_MS);
+    heartbeat.unref?.();
   } catch (lockError) {
     safeLog('error', 'Warning: could not record process lock:', lockError.message);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.14.1",
+  "version": "1.15.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

@@ -80,8 +80,7 @@ export function readProcessLock({ dir }) {
   }
 }
 
-function defaultIsAlive(pid) {
-  if (!Number.isFinite(pid) || pid <= 0) return false;
+function defaultIsAlive(pid) {  if (!Number.isFinite(pid) || pid <= 0) return false;
 
   try {
     // Sinyal 0 tidak mengirim apa pun; ia hanya memeriksa apakah proses ada.
@@ -111,12 +110,13 @@ export function acquireProcessLock({
   const existing = readProcessLock({ dir });
 
   if (existing && existing.pid !== pid && isAlive(existing.pid)) {
+    rememberLockDir(dir);
     return { acquired: false, holder: existing };
   }
 
   const tookOverFrom = existing && existing.pid !== pid ? existing.pid : undefined;
 
-  const payload = { pid, startedAt: now, host: safeHostname() };
+  const payload = { pid, startedAt: now, heartbeatAt: now, host: safeHostname() };
 
   try {
     mkdirSync(dir, { recursive: true });
@@ -133,8 +133,7 @@ export function acquireProcessLock({
     };
   }
 
-  return tookOverFrom ? { acquired: true, tookOverFrom } : { acquired: true };
-}
+  return tookOverFrom ? { acquired: true, tookOverFrom } : { acquired: true };}
 
 /** Melepas lock hanya bila memang milik kita. */
 export function releaseProcessLock({ dir, pid = process.pid }) {
@@ -189,3 +188,86 @@ export function lockWarning(result) {
     "memastikan hanya satu proses yang hidup."
   );
 }
+
+/**
+ * Berapa lama penanda proses dianggap masih "baru saja bekerja".
+ *
+ * Dipakai untuk membedakan sesi yang benar-benar aktif dari proses MCP yang
+ * tertinggal hidup setelah jendela OpenCode-nya ditutup. Tanpa batas ini,
+ * "satu penulis per repo" hanya bisa ditegakkan dengan memblokir sesi yang sah.
+ */
+export const DEFAULT_LOCK_STALE_MS = 10 * 60 * 1000;
+
+/** Interval detak jantung; sepertiga dari batas basi, supaya ada toleransi. */
+export const HEARTBEAT_MS = Math.floor(DEFAULT_LOCK_STALE_MS / 3);
+
+/** Direktori lock yang terakhir dipegang proses ini (diisi acquireProcessLock). */
+let rememberedLockDir = null;
+
+function lockStamp(lock) {
+  const value = Number(lock?.heartbeatAt ?? lock?.startedAt);
+  return Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Menyegarkan penanda milik kita sendiri.
+ *
+ * Mengembalikan false bila penanda bukan milik kita atau tidak bisa ditulis.
+ * Tidak pernah melempar: gagal menyegarkan penanda tidak boleh mematikan server,
+ * tetapi juga tidak boleh diam-diam dianggap berhasil.
+ */
+export function refreshProcessLock({ dir = rememberedLockDir, pid = process.pid, now = Date.now(), writeFileImpl = writeFileSync } = {}) {
+  if (!dir) return false;
+
+  const existing = readProcessLock({ dir });
+  if (!existing || existing.pid !== pid) return false;
+
+  try {
+    writeFileImpl(processLockPath({ dir }), JSON.stringify({ ...existing, heartbeatAt: now }), "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pemegang lock lain yang masih hidup DAN masih bekerja, atau null.
+ *
+ * Inilah yang membuat aturan "satu penulis per repo" punya gigi: pemanggil bisa
+ * menolak memulai pekerjaan alih-alih menimpanya. Penanda yang basi (tidak ada
+ * detak dalam `staleMs`) diabaikan, karena proses MCP yang tertinggal hidup
+ * bukan alasan memblokir sesi baru.
+ */
+export function activeForeignLock({
+  dir = rememberedLockDir,
+  pid = process.pid,
+  now = Date.now(),
+  staleMs = DEFAULT_LOCK_STALE_MS,
+  isAlive = defaultIsAlive,
+} = {}) {
+  if (!dir) return null;
+
+  const lock = readProcessLock({ dir });
+  if (!lock || lock.pid === pid) return null;
+  if (!isAlive(lock.pid)) return null;
+
+  const age = now - lockStamp(lock);
+  if (age > staleMs) return null;
+
+  return { ...lock, ageMs: age };
+}
+
+/** Mengingat direktori lock supaya detak jantung tidak perlu parameter. */
+export function rememberLockDir(dir) {
+  rememberedLockDir = dir || null;
+}
+
+/** Hanya untuk tes: mengganti pemeriksa "proses hidup". */
+let isAliveOverride = null;
+export function setIsAliveForTests(fn) {
+  isAliveOverride = typeof fn === "function" ? fn : null;
+}
+
+export function currentIsAlive() {
+  return isAliveOverride || defaultIsAlive;
+}

package/scripts/setup-stack.js

@@ -301,6 +301,12 @@ Before taking any action or answering user requests regarding code changes, chec
 6. **Document**: Update documentation 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.
+
+   If the repo also contains another session's uncommitted work, \`commit_and_push\`
+   refuses to stage the whole tree. Pass \`paths\` with only the files this task
+   touched (recommended), or \`includeForeign: true\` after verifying that work
+   belongs in this commit. Never resolve it by overwriting the other session's
+   files.
 9. **Release**: Call \`perform_release\` with the release command (or \`skip_release\` if docs-only).
 10. **Complete**: Call \`complete_task\` to finish the session and reset the workflow.
 

package/tools/definitions.js

@@ -44,6 +44,13 @@ export function getToolList() {
               "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.",
           },
+          force: {
+            type: "boolean",
+            description:
+              "Start anyway when another live MCP process is working the same project. Only for the machine owner: " +
+              "two sessions on one working tree overwrite each other's files silently. Prefer closing the other " +
+              "session or using a git worktree.",
+          },
         },
         required: ["description", "type", "definitionOfDone"],
       },
@@ -228,7 +235,9 @@ export function getToolList() {
     {
       name: "commit_and_push",
       description:
-        "Automatically run git add, commit, and push once the ready check passes.",
+        "Automatically run git add, commit, and push once the ready check passes. " +
+        "Refuses to stage the whole tree when files were already dirty before the task " +
+        "started (another session's work): pass 'paths' to stage only your files.",
       inputSchema: {
         type: "object",
         properties: {
@@ -246,6 +255,19 @@ export function getToolList() {
               "Absolute path to the repository to commit in. Overrides the repo pinned by 'start_task' " +
               "for this call. Use it to fix a misdirected commit without restarting the task.",
           },
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Stage only these paths instead of the whole tree. Use this when the repo " +
+              "also contains another session's uncommitted work.",
+          },
+          includeForeign: {
+            type: "boolean",
+            description:
+              "Stage everything anyway, including files that were already dirty before this " +
+              "task started. Only after verifying that work belongs in this commit.",
+          },
         },
         required: [],
       },
@@ -423,6 +445,15 @@ export function getToolList() {
             type: "string",
             description: "Optional release notes to record",
           },
+          dodEvidence: {
+            type: "object",
+            additionalProperties: { type: "string" },
+            description:
+              "Evidence for each open definition-of-done item, keyed by item id and applied just before the ready check, " +
+              "for example { \"dod-1\": \"npm test -> 533 pass\" }. Required whenever an item is still open: the workflow " +
+              "refuses to run at all rather than stop halfway through, because it cannot invent proof. Each value must be " +
+              "at least 5 characters. Items that do not apply must be waived with 'waive_dod_item' first.",
+          },
           releaseType: {
             type: "string",
             description: "Optional release type override (major/minor/patch)",

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

@@ -250,8 +250,44 @@ export async function handleCommitAndPush(args, context) {
     return textResponse("⚠️ Please include test updates in your changes before running 'commit_and_push'. Ensure at least one test file is modified.");
   }
 
+  /*
+   * `git add .` men-staging SELURUH working tree, termasuk pekerjaan sesi lain
+   * yang kebetulan ada di repo yang sama - lalu commit ini mengakuinya sebagai
+   * miliknya. Itu bukan teori: pada 31 Okt 2026 dua baris `billing.yaml` milik
+   * sesi lain ikut masuk commit sesi ini, dan sebuah `devices.yaml` yang
+   * ditulis ulang di tengah task nyaris tertimpa.
+   *
+   * Baseline dicatat `start_task`. Yang bisa dipastikan bukan milik kita adalah
+   * berkas yang SUDAH kotor sejak baseline. Berkas baru selama task tidak
+   * dituduh - tidak ada cara membedakannya, dan tuduhan palsu akan membuat
+   * pemeriksaan ini diabaikan.
+   */
+  const foreignDirty = typeof git.foreignDirtyEntries === "function"
+    ? git.foreignDirtyEntries(workflowState.state.dirtyAtStart, statusOutput)
+    : [];
+  const explicitPaths = Array.isArray(args.paths)
+    ? args.paths.map((entry) => String(entry).trim()).filter(Boolean)
+    : [];
+
+  if (foreignDirty.length > 0 && explicitPaths.length === 0 && args.includeForeign !== true) {
+    const list = foreignDirty.map((entry) => `   ${entry.code.padEnd(3)} ${entry.path}`).join("\n");
+    return textResponse(
+      `❌ Refusing to stage the whole tree: ${foreignDirty.length} file(s) were already dirty ` +
+        `before this task started, so they are almost certainly another session's work.\n\n` +
+        `${list}\n\n` +
+        `Choose one:\n` +
+        `   • pass 'paths' with only the files this task changed (recommended),\n` +
+        `   • or pass 'includeForeign: true' if you have verified that work belongs in this commit.\n\n` +
+        `Nothing was staged and nothing was committed.`
+    );
+  }
+
   try {
-    await exec("git add .");
+    if (explicitPaths.length > 0) {
+      await exec("git add", { executable: "git", arguments: ["add", "--", ...explicitPaths] });
+    } else {
+      await exec("git add .");
+    }
   } catch (error) {
     return textResponse(
       `❌ Failed to stage files:\n\n${error.stderr || error.stdout || error.message}`
@@ -314,8 +350,15 @@ export async function handleCommitAndPush(args, context) {
   workflowState.state.currentPhase = isReleaseSatisfied(workflowState.state) ? "ready_to_complete" : "release";
   await workflowState.save();
 
+  // Berkas yang ditinggalkan sengaja tetap disebut: kalau tidak, orang
+  // mengira seluruh pekerjaan sudah ter-commit padahal ada yang tertinggal.
+  const foreignNote = foreignDirty.length > 0
+    ? `\n\nℹ️ Left unstaged (already dirty before this task, not committed):\n` +
+      foreignDirty.map((entry) => `   ${entry.code.padEnd(3)} ${entry.path}`).join("\n")
+    : "";
+
   return textResponse(
-    `✅ Commit and push completed!\nRepo: ${repoName}\n\nCommit message: ${generatedSummary}\nPushed to: ${branchForPush} (verified at ${pushed.head.slice(0, 8)})\n\nNext: Run 'perform_release' to handle the release and push tags.`
+    `✅ Commit and push completed!\nRepo: ${repoName}\n\nCommit message: ${generatedSummary}\nPushed to: ${branchForPush} (verified at ${pushed.head.slice(0, 8)})${foreignNote}\n\nNext: Run 'perform_release' to handle the release and push tags.`
   );
 }
 

package/tools/handler-modules/index.js

@@ -11,6 +11,7 @@ import { handleCommitAndPush, handleCompleteTask, handleForceCompleteTask, handl
 import { handleProjectSummary, handleProjectSummaryData, handleProjectSummaryDb, handleViewHistory } from "./summary-handlers.js";
 import { handleGetWorkflowStatus, handleReadyCheck, handleContinueWorkflow, handleRerunWorkflow } from "./status-handlers.js";
 import { handleSetDefinitionOfDone, handleMarkDodItem, handleWaiveDodItem } from "./dod-handlers.js";
+import { openItems, MIN_EVIDENCE } from "./dod.js";
 import { handleListFactoryTasks, handleClaimFactoryTask, handleSyncTaskStatus, handleListFactoryProjects, handleCreateFactoryTask, handleUpdateFactoryTask } from "./factory-handlers.js";
 
 function summarizeResponse(label, response) {
@@ -49,7 +50,52 @@ async function handleRunFullWorkflow(args, { workflowState, exec, git, utils })
     }
   }
 
+  // Definition of done diperiksa di DEPAN, bukan setelah tujuh langkah.
+  //
+  // `start_task` mewajibkan DoD, jadi setiap task baru punya item terbuka. Sejak
+  // gerbang DoD ada (1.14.0), `run_full_workflow` tidak punya langkah untuk
+  // membuktikan item - jadi ia selalu berhenti di ready check, SETELAH
+  // mark_bug_fixed, create_tests, run_tests, dan create_documentation semuanya
+  // tercatat padahal commit belum pernah terjadi. Task seperti itu tertinggal
+  // setengah jadi dan membingungkan `get_workflow_status`.
+  //
+  // Lebih baik menolak di awal dengan daftar item yang perlu dibuktikan.
+  const dodEvidenceArg = args.dodEvidence;
+  const dodEvidence = dodEvidenceArg && typeof dodEvidenceArg === "object" && !Array.isArray(dodEvidenceArg)
+    ? dodEvidenceArg
+    : {};
+
+  const dodItemsBefore = Array.isArray(workflowState.state.definitionOfDone)
+    ? workflowState.state.definitionOfDone
+    : [];
+  const dodRevisionBefore = Number(workflowState.state.dodRevision) || 0;
+  const outstandingBefore = openItems(dodItemsBefore, dodRevisionBefore);
+
+  const missingEvidence = outstandingBefore.filter((item) => {
+    const value = dodEvidence[item.id];
+    return typeof value !== "string" || value.trim().length < MIN_EVIDENCE;
+  });
+
+  if (missingEvidence.length > 0) {
+    const list = missingEvidence.map((item) => `   ${item.id}: ${item.text}`).join("\n");
+    const example = missingEvidence
+      .map((item) => `"${item.id}": "npm test -> 533 pass"`)
+      .join(", ");
+
+    return textResponse(
+      `⚠️ Dibatalkan sebelum satu langkah pun berjalan: ${missingEvidence.length} item Definition of Done belum terbukti.\n\n` +
+        `${list}\n\n` +
+        `'run_full_workflow' tidak bisa menebak buktinya. Kirim 'dodEvidence' berisi bukti untuk tiap item, ` +
+        `atau buktikan dulu lewat 'mark_dod_item' lalu panggil 'run_full_workflow' lagi.\n\n` +
+        `Contoh:\n  "dodEvidence": { ${example} }\n\n` +
+        `Bukti minimal ${MIN_EVIDENCE} karakter dan harus menyebut apa yang benar-benar dijalankan atau diperiksa. ` +
+        `Item yang memang tidak berlaku kecualikan dengan 'waive_dod_item' { id, reason }.\n\n` +
+        `Tidak ada langkah yang dicatat; workflow tidak berubah.`
+    );
+  }
+
   const steps = [];
+  let dodApplied = false;
   const testsPassed = typeof args.testsPassed === "boolean" ? args.testsPassed : true;
   const testDetails = typeof args.testDetails === "string" ? args.testDetails : "";
   const releaseArgs = {
@@ -121,6 +167,28 @@ async function handleRunFullWorkflow(args, { workflowState, exec, git, utils })
     }
 
     if (!state.readyCheckCompleted) {
+      // Buktikan item DoD dari `dodEvidence` sebelum ready check, sekali saja.
+      //
+      // Diletakkan di sini, bukan di awal, karena bukti baru benar setelah
+      // implementasi dan tes selesai. Kalau dicatat di awal, bukti yang dikirim
+      // bersama panggilan ini akan menempel pada kode yang belum ditulis.
+      if (!dodApplied) {
+        const applied = [];
+        for (const item of openItems(state.definitionOfDone || [], Number(state.dodRevision) || 0)) {
+          const evidence = dodEvidence[item.id];
+          if (typeof evidence !== "string" || evidence.trim() === "") continue;
+          const resp = await handleMarkDodItem({ id: item.id, evidence }, workflowState);
+          if (isErrorResponse(resp)) return resp;
+          applied.push(item.id);
+        }
+        dodApplied = true;
+        if (applied.length > 0) {
+          steps.push(`mark_dod_item: ${applied.join(", ")}`);
+          await workflowState.load();
+          continue;
+        }
+      }
+
       const resp = await executeStep("check_ready_to_commit", handleReadyCheck, [workflowState]);
       if (isErrorResponse(resp)) return resp;
       continue;
@@ -197,7 +265,7 @@ async function dispatchToolCall({
         return textResponse(JSON.stringify(report));
       }
       case "start_task":
-        return handleStartTask(args, workflowState);
+        return handleStartTask(args, workflowState, git);
       case "set_definition_of_done":
         return handleSetDefinitionOfDone(args, workflowState);
       case "mark_dod_item":

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

@@ -80,6 +80,30 @@ export async function handleSkipRelease(args, workflowState) {
   );
 }
 
+/**
+ * Perubahan yang BUKAN berasal dari sebelum task.
+ *
+ * Dipakai untuk menyebutkan berkas mana yang menghalangi rilis. Pesan lama
+ * hanya berkata "detected new changes" tanpa menyebut apa pun, sehingga orang
+ * harus menebak sendiri yang mana.
+ */
+async function unexpectedChanges(git, baselineEntries) {
+  try {
+    const statusOutput = await git.getStatusOutput();
+    if (typeof git.parseStatusEntries !== "function") {
+      return [];
+    }
+    const known = new Set(
+      (Array.isArray(baselineEntries) ? baselineEntries : [])
+        .map((entry) => String(entry?.path || "").trim())
+        .filter(Boolean),
+    );
+    return git.parseStatusEntries(statusOutput).filter((entry) => !known.has(entry.path));
+  } catch {
+    return [];
+  }
+}
+
 export async function handlePerformRelease(args, context) {
   const { workflowState, exec, git, utils } = context;
 
@@ -111,8 +135,14 @@ export async function handlePerformRelease(args, context) {
   }
 
   if (hasNewChanges) {
+    const unexpected = await unexpectedChanges(git, workflowState.state.dirtyAtStart);
+    const details = unexpected.length > 0
+      ? `\n\nBerkas yang bukan bagian dari pekerjaan task ini:\n` +
+        unexpected.map((entry) => `   • ${entry.code.padEnd(3)} ${entry.path}`).join("\n")
+      : "";
     return textResponse(
-      "⚠️ Detected new changes after the last commit. Please run 'commit_and_push' again before recording a release."
+      "⚠️ Detected new changes after the last commit. Please run 'commit_and_push' again before recording a release." +
+        details
     );
   }
 
@@ -203,7 +233,16 @@ export async function handlePerformRelease(args, context) {
   }
 
   const statusSummary = git.workingTreeSummary(statusOutput);
-  if (statusSummary.hasChanges) {
+
+  // "Bersih" di sini berarti: tidak ada perubahan yang BELUM kita putuskan.
+  // Berkas yang sudah kotor sejak `start_task` adalah pekerjaan sesi lain yang
+  // sengaja ditinggalkan `commit_and_push` - rilis boleh lanjut, asalkan
+  // disebutkan supaya tidak tampak seperti repo yang bersih total.
+  const onlyForeign =
+    typeof git.hasOnlyForeignChanges === "function" &&
+    git.hasOnlyForeignChanges(workflowState.state.dirtyAtStart, statusOutput);
+
+  if (statusSummary.hasChanges && !onlyForeign) {
     const changeDetails =
       statusSummary.lines.length > 0
         ? statusSummary.lines.map((line) => `• ${line}`).join("\n")
@@ -214,6 +253,11 @@ export async function handlePerformRelease(args, context) {
     );
   }
 
+  const leftOverNote = onlyForeign && statusSummary.lines.length > 0
+    ? `\n\nℹ️ Dibiarkan tidak ter-commit (sudah kotor sebelum task ini, milik sesi lain):\n` +
+      statusSummary.lines.map((line) => `   • ${line}`).join("\n")
+    : "";
+
   const lastCommitMessage = await git.getLastCommitMessage();
   if (!releaseType) {
     releaseType = utils.determineReleaseTypeFromCommit(
@@ -313,8 +357,8 @@ export async function handlePerformRelease(args, context) {
 
   const message = summarizeHistory(workflowState.state.history, args.limit || 10);
   if (!message) {
-    return textResponse("📜 No workflow history yet.");
+    return textResponse(`📜 No workflow history yet.${leftOverNote}`);
   }
 
-  return textResponse(message);
+  return textResponse(`${message}${leftOverNote}`);
 }

package/tools/handler-modules/shared.js

@@ -39,6 +39,23 @@ export async function resetToCommitIfWorkingChanges(workflowState, git) {
     return false;
   }
 
+  // Berkas yang SUDAH kotor sejak `start_task` sengaja ditinggalkan
+  // `commit_and_push` (pekerjaan sesi lain). Itu bukan alasan untuk membatalkan
+  // rilis: kalau dihitung sebagai "perubahan baru", rilis menolak selamanya dan
+  // menyarankan meng-commit berkas yang justru tidak boleh di-commit.
+  if (typeof git.hasOnlyForeignChanges === "function" &&
+      typeof git.getStatusOutput === "function") {
+    let statusOutput = "";
+    try {
+      statusOutput = await git.getStatusOutput();
+    } catch {
+      statusOutput = "";
+    }
+    if (git.hasOnlyForeignChanges(workflowState.state.dirtyAtStart, statusOutput)) {
+      return false;
+    }
+  }
+
   workflowState.state.commitAndPushCompleted = false;
   workflowState.state.released = false;
   workflowState.state.releaseSkipped = false;
@@ -105,7 +122,18 @@ export function getContinueGuidance(status) {
   switch (status.currentPhase) {
     case "coding": {
       const task = status.taskDescription ? ` "${status.taskDescription}"` : "";
-      return `Describe your feature flow with Mermaid using 'create_feature_flow', then finish implementing${task} and run 'mark_bug_fixed' with a brief summary of the change.`;
+      // Item DoD yang masih terbuka disebut di sini karena agen sering berhenti
+      // di "implementasi selesai" dan lupa bahwa task-nya masih terkunci.
+      const open = (status.definitionOfDone || []).filter(
+        (item) => item && item.status !== "waived" && !(item.status === "done" && item.revision === status.dodRevision),
+      );
+      const dodHint =
+        open.length > 0
+          ? ` Prove each definition-of-done item with 'mark_dod_item' { id, evidence } - still open: ${open
+              .map((item) => `${item.id} (${item.text})`)
+              .join(", ")}.`
+          : "";
+      return `Describe your feature flow with Mermaid using 'create_feature_flow', then finish implementing${task} and run 'mark_bug_fixed' with a brief summary of the change.${dodHint}`;
     }
     case "testing":
       if (!status.testsCreated) {

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

@@ -1,6 +1,7 @@
 import { classify } from '../../security/policy.js';
 import { textResponse, isReleaseSatisfied, isErrorResponse, ensurePrdExists } from "./shared.js";
 import { validateItemTexts } from "./dod.js";
+import { activeForeignLock, projectLockDir, currentIsAlive, DEFAULT_LOCK_STALE_MS } from "../../process-lock.js";
 import { resolveProjectDir, setActiveProjectDir } from "../../exec.js";
 
 /**
@@ -68,7 +69,66 @@ function pinProjectDir(args, workflowState) {
   return { message };
 }
 
-export async function handleStartTask(args, workflowState) {
+/**
+ * Daftar berkas yang sudah kotor sebelum task dimulai.
+ *
+ * Kegagalan git di sini tidak boleh menggagalkan `start_task`: baseline hanya
+ * dipakai untuk memperingatkan saat commit, dan task tanpa baseline tetap sah
+ * (perilaku lama).
+ */
+async function captureDirtyAtStart(git) {
+  if (!git || typeof git.getStatusOutput !== "function" ||
+      typeof git.parseStatusEntries !== "function") {
+    return [];
+  }
+  try {
+    return git.parseStatusEntries(await git.getStatusOutput());
+  } catch {
+    return [];
+  }
+}
+
+export async function handleStartTask(args, workflowState, git) {
+  // Satu penulis per repo.
+  //
+  // 31 Oktober 2026 dua sesi OpenCode menulis satu working tree yang sama. Satu
+  // sesi kehilangan seluruh suntingannya di `tools/handler-modules/index.js`
+  // tanpa pesan apa pun: berkasnya kembali ke versi HEAD di tengah pekerjaan.
+  // Penanda proses sudah ada sejak sebelumnya, tetapi hanya DICATAT sebagai
+  // peringatan, jadi tidak ada yang menghentikan tabrakan.
+  //
+  // Sekarang `start_task` menolak memulai bila ada proses MCP lain yang hidup
+  // DAN baru saja bekerja (ada detak dalam 10 menit) pada proyek yang sama.
+  // Penanda yang basi diabaikan supaya proses MCP yang tertinggal tidak
+  // memblokir selamanya. `force: true` tetap tersedia untuk pemilik mesin yang
+  // tahu apa yang ia lakukan, dan alasannya dicatat di jawaban.
+  const foreignLock = activeForeignLock({
+    dir: projectLockDir(workflowState.stateFile),
+    isAlive: currentIsAlive(),
+  });
+
+  if (foreignLock && args.force !== true) {
+    const minutes = Math.max(1, Math.round(foreignLock.ageMs / 60000));
+    const host = foreignLock.host ? ` di ${foreignLock.host}` : "";
+    const started = Number.isFinite(Number(foreignLock.startedAt))
+      ? new Date(Number(foreignLock.startedAt)).toISOString()
+      : "waktu tidak diketahui";
+
+    return textResponse(
+      `⚠️ Dibatalkan: sesi lain sedang mengerjakan proyek ini.\n\n` +
+        `Proses MCP PID ${foreignLock.pid}${host} berdetak ${minutes} menit lalu ` +
+        `(hidup sejak ${started}).\n` +
+        `Dua sesi pada satu working tree saling menimpa berkas: pada 31 Oktober 2026 ` +
+        `satu sesi kehilangan seluruh suntingannya tanpa pesan.\n\n` +
+        `Pilih salah satu:\n` +
+        `  1. Tutup jendela OpenCode yang lain, lalu ulangi 'start_task'.\n` +
+        `  2. Beri sesi ini worktree sendiri: opencode.worktree_create, lalu jalankan sesi dari sana.\n` +
+        `  3. Kalau Anda yakin sesi itu sudah tidak dipakai, ulangi dengan { "force": true }.\n\n` +
+        `Penanda dianggap basi setelah ${Math.round(DEFAULT_LOCK_STALE_MS / 60000)} menit tanpa detak.\n` +
+        `Task BELUM dimulai; tidak ada state yang diubah.`
+    );
+  }
+
   // Validasi DoD SEBELUM menyentuh state apa pun. Task yang ditolak tidak boleh
   // mengganti task yang sedang berjalan, dan tidak boleh meninggalkan state
   // setengah jadi yang membuat `get_workflow_status` membingungkan.
@@ -111,6 +171,15 @@ export async function handleStartTask(args, workflowState) {
   workflowState.state.lastPushBranch = "";
   // Setelah reset(), karena reset mengosongkan projectDir.
   const project = pinProjectDir(args, workflowState);
+
+  // Catat berkas yang SUDAH kotor sebelum task ini dimulai.
+  //
+  // Saat commit nanti, berkas itu tidak boleh ikut ter-stage lewat `git add .`:
+  // itu pekerjaan sesi lain yang kebetulan berada di working tree yang sama.
+  // Kejadian nyata 31 Okt 2026: dua baris `billing.yaml` milik sesi lain masuk
+  // commit sesi ini, dan tidak ada yang bisa membedakannya dari luar.
+  workflowState.state.dirtyAtStart = await captureDirtyAtStart(git);
+
   // start_task memang bermaksud MENGGANTI task, jadi ia boleh menang atas
   // task berjalan. Task yang diganti tetap diarsipkan oleh reconcileWithDisk,
   // bukan dihapus.