@programinglive/dev-workflow-mcp-server 1.4.0 → 1.4.5

package/.github/workflows/npm-publish.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install web dependencies
+        run: npm ci --prefix web
+
       - name: Build package
         run: npm run build
 

package/CHANGELOG.md

@@ -2,12 +2,142 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [1.4.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.9...v1.4.0) (2025-11-22)
+### [1.4.5](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.4.4...v1.4.5) (2025-11-27)
+
+
+### 🐛 Bug Fixes
+
+* display dynamic version in web dashboard from /api/version ([69f561d](https://github.com/programinglive/dev-workflow-mcp-server/commit/69f561d369fa8347399fafe5dcdb3a2dbb485064))
+
+### [1.4.4](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.4.1...v1.4.4) (2025-11-27)
+
+
+### ♻️ Refactors
+
+* consolidate workflow state to root .state folder only ([3d69a14](https://github.com/programinglive/dev-workflow-mcp-server/commit/3d69a14e2abd7897bc91ede5e3c484b90eefc726))
+
+
+### 🐛 Bug Fixes
+
+* ensure release guard uses freshest workflow state ([e07eb42](https://github.com/programinglive/dev-workflow-mcp-server/commit/e07eb42179f17f2da282bff70392ce1b4652346a))
+* remove invalid turbopack experimental config from next.config.ts ([af0a7ea](https://github.com/programinglive/dev-workflow-mcp-server/commit/af0a7ea7906654755a2520693fd81d7fb6633c13))
+* **web:** configure next.js root to silence warnings ([22ed002](https://github.com/programinglive/dev-workflow-mcp-server/commit/22ed00256a4c6d7dbca13d2733baf0f4392b6650))
+* **web:** improve mobile layout for hero section ([53b26bf](https://github.com/programinglive/dev-workflow-mcp-server/commit/53b26bf3271cab3ac029be8ddb72a8d5312b150e))
+
+
+### 📝 Documentation
+
+* add Plesk deployment guide ([de35675](https://github.com/programinglive/dev-workflow-mcp-server/commit/de356753231d1bb29fd3c87fdd9d095932fae4b0))
+
+
+### 🧹 Chores
+
+* add 1.4.3 release notes ([8b165f7](https://github.com/programinglive/dev-workflow-mcp-server/commit/8b165f7a8201f6b8484dce60f3f907cb195abb83))
+* fix release state detection ([ed5dfd1](https://github.com/programinglive/dev-workflow-mcp-server/commit/ed5dfd15d296c555bd5c2731267a87ad4a371af9))
+* prepare for release ([a6ea2d0](https://github.com/programinglive/dev-workflow-mcp-server/commit/a6ea2d0c44f35f2a1e06c4e01bbe026177e9cff2))
+* **release:** 1.4.2 ([fac8999](https://github.com/programinglive/dev-workflow-mcp-server/commit/fac899992d370c0198954a6f7c97ab7645514e25))
+* **release:** 1.4.2 🚀 ([01b0b3c](https://github.com/programinglive/dev-workflow-mcp-server/commit/01b0b3c791c10b76c05bae01e4e8c5ce7435ce14))
+* **release:** 1.4.3 🚀 ([04d8c3b](https://github.com/programinglive/dev-workflow-mcp-server/commit/04d8c3b2873ce819633c95a12f6c48e73fe671ea))
+* update task list ([35663dd](https://github.com/programinglive/dev-workflow-mcp-server/commit/35663dd661d3b97a5fedb5013fbbca36e75605d8))
+* **web:** fix next.js lockfile warning ([05ffce0](https://github.com/programinglive/dev-workflow-mcp-server/commit/05ffce0b171cb804c6a14223521cd1fa876b80ae))
+
+
+### ✨ Features
+
+* add core doc types (PRD/README/RELEASE_NOTES) and fix CI build ([8ed0567](https://github.com/programinglive/dev-workflow-mcp-server/commit/8ed0567e8de772b95de6fb744a936b07ed3e1c32))
+* update hero text and meta description to emphasize Indonesian programmer community ([681547b](https://github.com/programinglive/dev-workflow-mcp-server/commit/681547b764b2fcf3a874cc637d9653c12bf62640))
+* update program tracks and fix fast refresh warning ([aa5bc9c](https://github.com/programinglive/dev-workflow-mcp-server/commit/aa5bc9cbc8a9bf9c9552e00e89b0b97ddeac0592))
+
+### [1.4.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.4.2...v1.4.3) (2025-11-27)
+
+
+### 🧹 Chores
+
+* **release:** 1.4.2 ([fac8999](https://github.com/programinglive/dev-workflow-mcp-server/commit/fac899992d370c0198954a6f7c97ab7645514e25))
+
+
+### 🐛 Bug Fixes
+
+* remove invalid turbopack experimental config from next.config.ts ([af0a7ea](https://github.com/programinglive/dev-workflow-mcp-server/commit/af0a7ea7906654755a2520693fd81d7fb6633c13))
+
+
+### 📝 Documentation
+
+* add Plesk deployment guide ([de35675](https://github.com/programinglive/dev-workflow-mcp-server/commit/de356753231d1bb29fd3c87fdd9d095932fae4b0))
+
+
+### ✨ Features
+
+* update program tracks and fix fast refresh warning ([aa5bc9c](https://github.com/programinglive/dev-workflow-mcp-server/commit/aa5bc9cbc8a9bf9c9552e00e89b0b97ddeac0592))
+
+### [1.4.2](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.4.1...v1.4.2) (2025-11-27)
+
+
+### 🧹 Chores
+
+* fix release state detection ([ed5dfd1](https://github.com/programinglive/dev-workflow-mcp-server/commit/ed5dfd15d296c555bd5c2731267a87ad4a371af9))
+* prepare for release ([a6ea2d0](https://github.com/programinglive/dev-workflow-mcp-server/commit/a6ea2d0c44f35f2a1e06c4e01bbe026177e9cff2))
+* update task list ([35663dd](https://github.com/programinglive/dev-workflow-mcp-server/commit/35663dd661d3b97a5fedb5013fbbca36e75605d8))
+* **web:** fix next.js lockfile warning ([05ffce0](https://github.com/programinglive/dev-workflow-mcp-server/commit/05ffce0b171cb804c6a14223521cd1fa876b80ae))
+
+
+### 🐛 Bug Fixes
+
+* ensure release guard uses freshest workflow state ([e07eb42](https://github.com/programinglive/dev-workflow-mcp-server/commit/e07eb42179f17f2da282bff70392ce1b4652346a))
+* **web:** configure next.js root to silence warnings ([22ed002](https://github.com/programinglive/dev-workflow-mcp-server/commit/22ed00256a4c6d7dbca13d2733baf0f4392b6650))
+* **web:** improve mobile layout for hero section ([53b26bf](https://github.com/programinglive/dev-workflow-mcp-server/commit/53b26bf3271cab3ac029be8ddb72a8d5312b150e))
+
+
+### ♻️ Refactors
+
+* consolidate workflow state to root .state folder only ([3d69a14](https://github.com/programinglive/dev-workflow-mcp-server/commit/3d69a14e2abd7897bc91ede5e3c484b90eefc726))
+
+### [1.4.1](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.4.0...v1.4.1) (2025-11-27)
+
+
+### 🐛 Bug Fixes
+
+* update build test to include postbuild ([b1e2f48](https://github.com/programinglive/dev-workflow-mcp-server/commit/b1e2f481334df825109e3f2934c88b8f14c1b4d0))
+
+
+### ✨ Features
+
+* add custom server.js for Plesk ([b3912cd](https://github.com/programinglive/dev-workflow-mcp-server/commit/b3912cdaf50085ae30cab553a9ebac2b7281ee28))
+
+## [1.4.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.12...v1.4.0) (2025-11-26)
+
+
+### ✨ Features
+
+* migrate dashboard to Next.js with TypeScript and Tailwind CSS ([bce1fec](https://github.com/programinglive/dev-workflow-mcp-server/commit/bce1fec98a7b5e5542644271a77ccaf1019dd83c))
+
+
+### 🧹 Chores
+
+* fix package.json scripts ([fb25e98](https://github.com/programinglive/dev-workflow-mcp-server/commit/fb25e98c763d4b5cac5c321f56a2e533577fc38b))
+* fix tsconfig and remove dist artifact ([282759f](https://github.com/programinglive/dev-workflow-mcp-server/commit/282759f14de6231ad6374dc891b551ca0d70ac28))
+
+### [1.3.12](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.11...v1.3.12) (2025-11-22)
+
+
+### 🐛 Bug Fixes
+
+* **scripts:** update release notes script and backfill versions ([808791e](https://github.com/programinglive/dev-workflow-mcp-server/commit/808791ec4a988fe557fa82be21fb92f6a34d792c))
+* **scripts:** update release notes script to support header format and backfill versions ([e4a5055](https://github.com/programinglive/dev-workflow-mcp-server/commit/e4a5055633ba4d83d43c85ee8b475cd761685519))
+
+### [1.3.11](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.10...v1.3.11) (2025-11-22)
 
 
 ### ♻️ Refactors
 
-* **web:** move static files to public/ subdirectory for Plesk security ([f68c6b6](https://github.com/programinglive/dev-workflow-mcp-server/commit/f68c6b6321fa85e9537f8592dfcbc8fb718f77c4))
+* **web:** move static files to public/ subdirectory for Plesk security ([3e5c321](https://github.com/programinglive/dev-workflow-mcp-server/commit/3e5c321d569e3594d9f29c8762513b95df8dbd84))
+
+### [1.3.10](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.9...v1.3.10) (2025-11-22)
+
+
+### 📝 Documentation
+
+* add workflow best practices to eliminate forced releases ([6bcac42](https://github.com/programinglive/dev-workflow-mcp-server/commit/6bcac42bc9f30cbfa0a27e36a90af303d244d863))
 
 ### [1.3.9](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.8...v1.3.9) (2025-11-22)
 

package/README.md

@@ -205,6 +205,7 @@ npm run web
 - **Environment overrides:** Honors `PORT` (common on hosts like Plesk/Render) or `DEV_WORKFLOW_WEB_PORT` before falling back to auto-selection.
 - **Query parameter:** `?user=<id>` lets you inspect another user’s history (defaults to `default`).
 - **API endpoints:**
+  - `GET /api/version` → current package version from `package.json` (used by dashboard to display version dynamically).
   - `GET /api/summary?user=<id>` → overall stats for the user.
   - `GET /api/history?user=<id>&page=1&pageSize=20&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` → paginated task history.
   - `GET /api/history-summary?user=<id>&frequency=daily|monthly|yearly` → aggregated counts over time.
@@ -431,7 +432,7 @@ Use run_tests with:
 Mark that documentation has been created/updated. This is required before committing.
 
 **Parameters:**
-- `documentationType` (enum, required): "README", "inline-comments", "API-docs", "changelog", or "other"
+- `documentationType` (enum, required): "PRD", "README", "RELEASE_NOTES", "inline-comments", "API-docs", "changelog", or "other"
 - `summary` (string, required): What was documented
 
 ### `check_ready_to_commit`

package/docs/PLESK_DEPLOYMENT.md

@@ -0,0 +1,170 @@
+# Deploying dev-workflow-mcp-server to Plesk
+
+This guide covers deploying the dev-workflow MCP server (Node.js backend + Next.js frontend) to Plesk hosting.
+
+## Prerequisites
+
+- Plesk control panel access
+- Node.js 18+ installed on the server
+- Git installed on the server
+- Domain/subdomain configured in Plesk
+
+## Deployment Steps
+
+### 1. Set Up Node.js Application in Plesk
+
+1. Log in to Plesk control panel
+2. Go to **Domains** → Select your domain
+3. Click **Node.js** (or **Applications** if using newer Plesk)
+4. Click **Add Application**
+5. Configure:
+   - **Application root**: `/var/www/vhosts/yourdomain.com/dev-workflow-mcp-server` (or your path)
+   - **Startup file**: `index.js`
+   - **Node.js version**: 18.x or higher
+   - **Port**: Leave as auto (Plesk assigns a port)
+
+### 2. Clone Repository
+
+SSH into your Plesk server:
+
+```bash
+cd /var/www/vhosts/yourdomain.com
+git clone https://github.com/programinglive/dev-workflow-mcp-server.git
+cd dev-workflow-mcp-server
+```
+
+### 3. Install Dependencies
+
+```bash
+npm install
+```
+
+### 4. Build the Application
+
+```bash
+npm run build
+```
+
+This builds:
+- **Backend**: Vite bundle → `dist/index.mjs`
+- **Frontend**: Next.js static + server → `web/.next/`
+- **Docs**: HTML files → `dist/docs/`
+
+### 5. Configure Environment (if needed)
+
+Create `.env` file in the project root if you need custom settings:
+
+```bash
+# Example (adjust as needed)
+NODE_ENV=production
+PORT=3000
+```
+
+### 6. Start the Application
+
+In Plesk:
+1. Go back to **Node.js Applications**
+2. Find your application
+3. Click **Start** (or it may auto-start)
+
+Alternatively, via SSH:
+
+```bash
+npm start
+```
+
+### 7. Configure Reverse Proxy (Plesk)
+
+Plesk automatically sets up a reverse proxy. Verify:
+1. Go to **Domains** → Your domain → **Web Server Settings**
+2. Ensure **Proxy** is enabled
+3. Verify the proxy points to the Node.js app port
+
+### 8. Verify Deployment
+
+- Visit `https://yourdomain.com` → Should see the Next.js frontend
+- Visit `https://yourdomain.com/docs` → Should see documentation
+- Check browser console for any `_next/static` 500 errors
+
+If you see 500 errors on `_next/static` requests:
+- SSH to server and check logs: `tail -f /var/log/plesk/nodejs/yourdomain.com.log`
+- Ensure `.next` directory exists: `ls -la web/.next/`
+- Verify Node.js is running: `ps aux | grep node`
+
+### 9. Set Up Auto-Restart (Optional)
+
+In Plesk, the Node.js app should auto-restart on failure. To verify:
+1. Go to **Node.js Applications**
+2. Check **Restart policy** is set to auto-restart
+
+### 10. Enable HTTPS (Recommended)
+
+1. Go to **Domains** → Your domain → **SSL/TLS Certificates**
+2. Click **Install** (use Let's Encrypt free certificate)
+3. Plesk auto-redirects HTTP → HTTPS
+
+## Troubleshooting
+
+### `_next/static` returns 500
+
+**Cause**: Next.js build output not deployed or server crashed.
+
+**Fix**:
+```bash
+# SSH to server
+npm run build --prefix web
+npm start
+# Check logs
+tail -f /var/log/plesk/nodejs/yourdomain.com.log
+```
+
+### Application won't start
+
+**Check**:
+1. Node.js version: `node --version` (must be 18+)
+2. Dependencies: `npm install`
+3. Build output: `ls -la dist/` and `ls -la web/.next/`
+4. Logs: Check Plesk control panel logs
+
+### Port conflicts
+
+Plesk assigns ports automatically. If you get a port conflict:
+1. Go to **Node.js Applications** → Edit
+2. Let Plesk auto-assign a new port
+3. Restart the app
+
+## Updating the Application
+
+To deploy a new version:
+
+```bash
+cd /var/www/vhosts/yourdomain.com/dev-workflow-mcp-server
+git pull origin main
+npm install
+npm run build
+# Plesk will auto-restart the app
+```
+
+Or manually restart in Plesk control panel:
+1. **Node.js Applications** → Select app → **Restart**
+
+## Production Checklist
+
+- [ ] Node.js 18+ installed
+- [ ] `npm install` completed
+- [ ] `npm run build` succeeded (no errors)
+- [ ] `.next` directory exists with static files
+- [ ] HTTPS/SSL certificate installed
+- [ ] Reverse proxy configured
+- [ ] Application started and running
+- [ ] `https://yourdomain.com` loads without 500 errors
+- [ ] `_next/static` assets load correctly
+- [ ] Logs show no errors
+
+## Support
+
+For issues:
+1. Check Plesk logs: `/var/log/plesk/nodejs/`
+2. SSH and run `npm start` manually to see real-time errors
+3. Verify Node.js and npm versions
+4. Ensure all dependencies installed: `npm install`

package/docs/WORKFLOW-BEST-PRACTICES.md

@@ -0,0 +1,58 @@
+# Workflow Best Practices
+
+## Correct Release Workflow Order
+
+To avoid needing `--force` flag for releases, follow this exact order:
+
+1. **Start Task**: `mcp0_start_task`
+2. **Fix/Implement**: Make your code changes
+3. **Mark Fixed**: `mcp0_mark_bug_fixed`
+4. **Tests**: `mcp0_create_tests` + `mcp0_run_tests` (or `mcp0_skip_tests` with reason)
+5. **Documentation**: `mcp0_create_documentation`
+6. **Ready Check**: `mcp0_check_ready_to_commit`
+7. **Commit & Push**: `mcp0_commit_and_push`
+8. **Release**: `mcp0_perform_release` ⚠️ **MUST come BEFORE complete_task**
+9. **Complete**: `mcp0_complete_task`
+
+## Common Mistakes
+
+### ❌ Wrong Order (causes forced releases)
+```
+check_ready → commit → complete → release  // WRONG!
+```
+
+### ✅ Correct Order
+```
+check_ready → commit → release → complete  // CORRECT!
+```
+
+## Why This Matters
+
+- `complete_task` **resets the workflow state**
+- `perform_release` **checks the workflow state** before running
+- If you complete before releasing, the state is cleared and release guards fail
+- Using `--force` bypasses guards but doesn't fix the root cause
+
+## State Transitions
+
+1. After `commit_and_push`: `currentPhase = "release"`
+2. After `perform_release`: `currentPhase = "ready_to_complete"`, `released = true`
+3. After `complete_task`: State is reset to idle
+
+## Solution
+
+Always call `perform_release` BEFORE `complete_task`. Never use `--force` unless absolutely necessary.
+
+## Documentation Phase Expectations
+
+During the documentation step (`mcp0_create_documentation`), make sure the core project docs are created or updated as needed:
+
+1. `docs/product/PRD.md` – Product Requirements Document
+2. `README.md` – Project overview and usage
+3. `docs/release-notes/RELEASE_NOTES.md` – Release notes for changes in this task/version
+
+If one or more of these files already exist, **update them** instead of creating new variants. Use the `documentationType` argument to reflect what you touched:
+
+- `"PRD"` when you added/updated the PRD
+- `"README"` when you updated the main README
+- `"RELEASE_NOTES"` when you updated the release notes

package/docs/product/PRD.md

@@ -35,6 +35,7 @@ Developers need structured guidance to maintain disciplined workflows across pro
 - Offer aggregated project summaries (JSON artifacts, SQLite sync, optional web dashboard).
 - Guard release commands to ensure prerequisites are satisfied.
 - Support `run_full_workflow` for scripted execution of all steps with validation.
+- Web dashboard displays version dynamically from `package.json` via `/api/version` endpoint to stay in sync after releases.
 
 ## 8. Technical Considerations
 - Node.js (ESM) codebase leveraging `@modelcontextprotocol/sdk`.

package/docs/release-notes/RELEASE_NOTES.md

@@ -4,6 +4,65 @@ Authoritative history of user-visible changes for the Development Workflow MCP S
 
 ## Unreleased
 
+## 1.4.4 — 2025-11-27 — ♻️ Refactors
+- consolidate workflow state to root .state folder only (3d69a14)
+- ensure release guard uses freshest workflow state (e07eb42)
+- remove invalid turbopack experimental config from next.config.ts (af0a7ea)
+- **web:** configure next.js root to silence warnings (22ed002)
+- **web:** improve mobile layout for hero section (53b26bf)
+- add Plesk deployment guide (de35675)
+- add 1.4.3 release notes (8b165f7)
+- fix release state detection (ed5dfd1)
+- prepare for release (a6ea2d0)
+- **release:** 1.4.2 (fac8999)
+- **release:** 1.4.2 🚀 (01b0b3c)
+- **release:** 1.4.3 🚀 (04d8c3b)
+- update task list (35663dd)
+- **web:** fix next.js lockfile warning (05ffce0)
+- add core doc types (PRD/README/RELEASE_NOTES) and fix CI build (8ed0567)
+- update hero text and meta description to emphasize Indonesian programmer community (681547b)
+- update program tracks and fix fast refresh warning (aa5bc9c)
+
+## 1.4.3 — 2025-11-27 — 🧹 Chores
+- **release:** 1.4.2 (fac8999)
+- remove invalid turbopack experimental config from next.config.ts (af0a7ea)
+- add Plesk deployment guide (de35675)
+- update program tracks and fix fast refresh warning (aa5bc9c)
+
+## 1.4.2 — 2025-11-27 — 🧹 Chores
+- fix release state detection (ed5dfd1)
+- prepare for release (a6ea2d0)
+- update task list (35663dd)
+- **web:** fix next.js lockfile warning (05ffce0)
+- ensure release guard uses freshest workflow state (e07eb42)
+- **web:** configure next.js root to silence warnings (22ed002)
+- **web:** improve mobile layout for hero section (53b26bf)
+- consolidate workflow state to root .state folder only (3d69a14)
+
+## 1.4.1 — 2025-11-27 — 🐛 Bug Fixes
+- update build test to include postbuild (b1e2f48)
+- add custom server.js for Plesk (b3912cd)
+- migrate dashboard to Next.js with TypeScript and Tailwind CSS (bce1fec)
+- fix package.json scripts (fb25e98)
+- fix tsconfig and remove dist artifact (282759f)
+
+## 1.4.0 — 2025-11-26
+- See CHANGELOG for details.
+
+## 1.3.11 — 2025-11-23
+- Re-applied Plesk security fix (moved static files to `web/public/`).
+- Updated build configuration and server paths.
+
+## 1.3.10 — 2025-11-23
+- Fixed workflow state synchronization issue that caused forced releases.
+- Added `docs/WORKFLOW-BEST-PRACTICES.md`.
+
+## 1.3.9 — 2025-11-23
+- Improved documentation modal layout and readability.
+
+## 1.3.8 — 2025-11-23
+- Fixed documentation loading in production by tracking `dist/docs` in git.
+
 ## 1.3.0 — 2025-11-22
 - Added comprehensive Antigravity integration documentation and examples.
 - Fixed Windows shell escaping for commit messages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.4.0",
+  "version": "1.4.5",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "type": "module",
@@ -9,10 +9,11 @@
     "dev-workflow-mcp": "index.js"
   },
   "scripts": {
-    "build": "vite build",
-    "build:web": "npx tailwindcss -i ./web/public/input.css -o ./web/public/output.css --minify",
-    "watch:web": "npx tailwindcss -i ./web/public/input.css -o ./web/public/output.css --watch",
-    "postbuild": "npm run build:web && node scripts/build-docs.js",
+    "build": "npm run build:server && npm run build:web",
+    "build:server": "vite build",
+    "build:web": "npm run build --prefix web",
+    "watch:web": "npm run dev --prefix web",
+    "postbuild": "node scripts/build-docs.js",
     "dev": "node --watch index.js",
     "start": "node index.js",
     "local": "node index.js",
@@ -24,7 +25,7 @@
     "release:major": "node release-wrapper.js major",
     "release:minor": "node release-wrapper.js minor",
     "release:patch": "node release-wrapper.js patch",
-    "web": "node web/server.js"
+    "web": "npm start --prefix web"
   },
   "keywords": [
     "mcp",

package/release-wrapper.js

@@ -3,9 +3,71 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { resolveStateFile } from './workflow-state.js';
 
 const RELEASE_TYPES = new Set(['major', 'minor', 'patch']);
 
+async function readStateCandidate(filePath) {
+  if (!filePath) {
+    return null;
+  }
+
+  try {
+    const [raw, stats] = await Promise.all([fs.readFile(filePath, 'utf8'), fs.stat(filePath)]);
+    return {
+      state: JSON.parse(raw),
+      path: filePath,
+      mtimeMs: stats.mtimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function loadWorkflowStateCandidates(projectRoot) {
+  const candidates = [];
+
+  try {
+    candidates.push(resolveStateFile());
+  } catch {
+    // resolver may throw before state exists; fall through to other candidates
+  }
+
+  const legacyStatePath = path.join(projectRoot, '.state', 'workflow-state.json');
+  candidates.push(legacyStatePath);
+
+  // Add explicit DEV_WORKFLOW_STATE_FILE if provided (resolver would have used it, but keep explicit just in case)
+  if (process.env.DEV_WORKFLOW_STATE_FILE) {
+    candidates.push(path.resolve(process.env.DEV_WORKFLOW_STATE_FILE));
+  }
+
+  const seen = new Set();
+  let freshest = null;
+
+  for (const candidate of candidates) {
+    if (!candidate) {
+      continue;
+    }
+
+    const resolved = path.resolve(candidate);
+    if (seen.has(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+
+    const result = await readStateCandidate(resolved);
+    if (!result) {
+      continue;
+    }
+
+    if (!freshest || result.mtimeMs > freshest.mtimeMs) {
+      freshest = result;
+    }
+  }
+
+  return freshest;
+}
+
 async function main() {
   const releaseTypeArg = (process.argv[2] || '').toLowerCase();
   const forceFlag = process.argv.includes('--force') || process.env.DEV_WORKFLOW_FORCE_RELEASE === '1';
@@ -26,44 +88,17 @@ async function main() {
   }
   const projectRoot = projectRootCandidate;
 
-  // Prefer state under INIT_CWD to support per-project runs and tests.
-  // If DEV_WORKFLOW_USER_ID is set and a user-scoped file exists, use it; otherwise fall back to legacy path.
-  const baseStateDir = path.join(projectRoot, '.state');
-  const legacyStatePath = path.join(baseStateDir, 'workflow-state.json');
-  let resolvedUserId = (process.env.DEV_WORKFLOW_USER_ID || '').trim();
-  if (!resolvedUserId) {
-    try {
-      const fileUserId = (await fs.readFile(path.join(baseStateDir, 'user-id'), 'utf8')).trim();
-      if (fileUserId) {
-        resolvedUserId = fileUserId;
-      }
-    } catch {
-      // no user-id file; legacy layout likely
-    }
-  }
-  const userStatePath = resolvedUserId ? path.join(baseStateDir, 'users', resolvedUserId, 'workflow-state.json') : null;
-
-  let statePath = legacyStatePath;
-  if (userStatePath) {
-    try {
-      await fs.access(userStatePath);
-      statePath = userStatePath;
-    } catch {
-      // fall back to legacy path
-    }
-  }
-  let state;
-
-  try {
-    const raw = await fs.readFile(statePath, 'utf8');
-    state = JSON.parse(raw);
-  } catch (error) {
+  const result = await loadWorkflowStateCandidates(projectRoot);
+  if (!result) {
     console.error(
-      `❌ Release guard: cannot locate workflow state at ${statePath}. Make sure the dev-workflow MCP is installed and you have started a task.`
+      `❌ Release guard: cannot locate workflow state under ${path.join(projectRoot, '.state')}.
+Make sure the dev-workflow MCP is installed and you have started a task.`
     );
     process.exit(1);
   }
 
+  const { state, path: statePath } = result;
+
   const errors = [];
   if (state.currentPhase !== 'release') {
     errors.push(