@programinglive/dev-workflow-mcp-server 1.1.11 → 1.1.16

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

@@ -0,0 +1,47 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Publish package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          registry-url: https://registry.npmjs.org
+          scope: "@programinglive"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Verify tag matches package version
+        run: |
+          EXPECTED_TAG="${GITHUB_REF#refs/tags/}"
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          if [ "v${PACKAGE_VERSION}" != "${EXPECTED_TAG}" ]; then
+            echo "Package version ${PACKAGE_VERSION} does not match tag ${EXPECTED_TAG}"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --provenance

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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.1.16](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.15...v1.1.16) (2025-10-31)
+
+
+### 🧹 Chores
+
+* align npm provenance metadata ([459572e](https://github.com/programinglive/dev-workflow-mcp-server/commit/459572e07efa340ef87cc679535fb24413d8c997))
+
+### [1.1.15](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.14...v1.1.15) (2025-10-31)
+
+
+### 📝 Documentation
+
+* add npm publish workflow automation ([c923734](https://github.com/programinglive/dev-workflow-mcp-server/commit/c923734ab4399afbcb0166abcd16cd01c3e50c0e))
+
+
+### 👷 Continuous Integration
+
+* **npm:** build + provenance in npm-publish workflow ([5ae04db](https://github.com/programinglive/dev-workflow-mcp-server/commit/5ae04db33e33fe64c33d8eac08db70e98754ea64))
+
+### [1.1.14](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.13...v1.1.14) (2025-10-31)
+
+
+### 🐛 Bug Fixes
+
+* improve workflow state project root resolution ([a575e24](https://github.com/programinglive/dev-workflow-mcp-server/commit/a575e2404d26e550c8e52e4a524a75a3fa64752d))
+
+### [1.1.13](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.12...v1.1.13) (2025-10-30)
+
+### [1.1.12](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.11...v1.1.12) (2025-10-30)
+
+
+### ✨ Features
+
+* **cli:** add 'call' subcommand to invoke MCP tools directly (e.g., node index.js call drop_task) ([c9b8fae](https://github.com/programinglive/dev-workflow-mcp-server/commit/c9b8fae7e24e0915d857135d03fa969b10dcac67))
+* **web:** docs modal, docs API, navbar redesign ([902242b](https://github.com/programinglive/dev-workflow-mcp-server/commit/902242b1318b01f8f62ef7c4c0f6347cb8517617))
+* **web:** embed docs modal and redesign dashboard ([d2cf2fb](https://github.com/programinglive/dev-workflow-mcp-server/commit/d2cf2fb4ae90e61b20c72ed26f25dc0e5119247a))
+
 ### [1.1.11](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.10...v1.1.11) (2025-10-30)
 
 

package/README.md

@@ -34,6 +34,26 @@ cd dev-workflow-mcp-server
 npm install
 ```
 
+> **Windows prerequisites:** Installing dependencies from source compiles native modules such as `better-sqlite3`. Make sure Python 3 (added to PATH) and the Visual Studio Build Tools “Desktop development with C++” workload are installed before running `npm install`. Without them, npm will fail with a “need python” or build error.
+
+### Option 3: Install on Plesk Hosting
+
+Plesk supports Node.js applications through its Node.js extension. To deploy the MCP server on a Plesk subscription:
+
+1. **Enable Node.js support** – Ensure the Plesk administrator has installed the Node.js extension and enabled SSH access for your subscription.
+2. **Upload the project** – Either clone the repository or upload an archive into the directory you will run it from (e.g., `httpdocs/dev-workflow-mcp-server`). From SSH you can run:
+   ```bash
+   cd httpdocs
+   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
+   cd dev-workflow-mcp-server
+   ```
+3. **Install dependencies** – In Plesk’s **Node.js** panel use “NPM install” (or run `npm install --production` over SSH). Linux hosts already ship the Python/build toolchain required for `better-sqlite3`; if your plan uses a Windows host, install Python 3 and the Visual Studio Build Tools beforehand or ask your provider to enable them.
+4. **Define environment variables** – In the Node.js panel add any environment variables you need (for example `DEV_WORKFLOW_USER_ID` or `DEV_WORKFLOW_STATE_FILE`). This keeps state files outside the web root if desired.
+5. **Configure the application** – Set **Application startup file** to `index.js` and **Application mode** to `production`. Plesk will run the server with `node index.js`.
+6. **Start/Restart the app** – Click “Restart App” so Plesk launches the MCP server with the new configuration. When you update the code, rerun “NPM install” and restart.
+
+> **Tip:** The MCP server communicates over stdio. If you only need it as a CLI tool, you can also run `npx @programinglive/dev-workflow-mcp-server` directly in an SSH session without keeping it running under the Node.js panel.
+
 #### Two Usage Modes
 
 - **Local (source)**: Point your MCP client to `index.js`. This runs directly from source and requires no build step. Recommended for MCP usage.
@@ -142,6 +162,25 @@ This project includes a Vite-based build system for creating optimized distribut
 - `npm run build` - Bundle the source into `dist/index.mjs` for distribution
 - `npm run dev` - Run in development mode with file watching
 - `npm run local` - Alias for running from source (same as `npm start`)
+- `npm run web` - Launch the lightweight workflow dashboard for browsing task history (see [Web Dashboard docs](./docs/web-dashboard.md))
+
+#### `npm run web`
+
+This command starts the dashboard defined in `web/server.js`, giving you a quick view of workflow history and summary statistics.
+
+```bash
+npm run web
+# 🌐 Dev Workflow Dashboard running at http://localhost:3111
+```
+
+- **Default port:** 3111 (or the next free port if occupied). Override with `DEV_WORKFLOW_WEB_PORT`.
+- **Query parameter:** `?user=<id>` lets you inspect another user’s history (defaults to `default`).
+- **API endpoints:**
+  - `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.
+
+Open `http://localhost:3111` in a browser to view the dashboard UI (`web/index.html`).
 
 ### Build Output
 
@@ -249,6 +288,19 @@ If any requirements are missing, the guard exits with guidance to return to the
 1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client.
 2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
 
+### Automated npm Publishing
+
+This repository ships with `.github/workflows/npm-publish.yml`, which publishes the package to npm whenever a git tag matching `v*` is pushed (for example, `v1.1.14`). To enable the workflow:
+
+1. Create an npm automation token with publish rights (`npm token create --read-only false`).
+2. In the repository settings, add a secret named **`NPM_TOKEN`** containing that token.
+3. Ensure your release process pushes tags after running `npm run release:<type>` so the workflow triggers.
+4. Confirm `npm run build` succeeds locally; the workflow runs the build before publishing so broken bundles block the release.
+5. GitHub provenance is enabled via `npm publish --provenance`. Leave GitHub Actions' default OIDC permissions enabled so the job can request an ID token.
+6. Keep the `repository.url` field in `package.json` pointing at this GitHub repo. Provenance validation fails if it does not match the repository that built the package.
+
+The workflow verifies that the tag version matches `package.json` before publishing and fails fast if they diverge.
+
 ## 🛠️ Available Tools
 
 ### Tool Argument Requirements

package/docs/product/PRD.md

@@ -0,0 +1,64 @@
+# Product Requirements Document (PRD)
+
+## 1. Overview
+- **Product**: Development Workflow MCP Server
+- **Prepared by**: Cascade (AI assistant)
+- **Date**: 2025-10-31
+- **Status**: Draft v0.1
+
+## 2. Problem Statement
+Developers need structured guidance to maintain disciplined workflows across projects. Existing tooling lacks enforcement of sequential best practices (testing, documentation, release hygiene) and offers limited visibility into historical task execution.
+
+## 3. Goals & Objectives
+1. Enforce a consistent, auditable development workflow across teams.
+2. Provide actionable guidance for each workflow phase within IDE-integrated environments.
+3. Maintain per-project, per-user workflow state while supporting shared infrastructure (e.g., SQLite summaries, dashboard).
+
+## 4. Non-Goals
+- Replacing full-featured project management tools.
+- Implementing source control hosting or CI/CD pipelines.
+- Providing opinionated task estimation or prioritization features.
+
+## 5. Target Users & Personas
+- **Individual developers** seeking workflow discipline.
+- **Team leads** requiring enforced process compliance.
+- **Tool integrators** embedding MCP capabilities into IDEs or agents.
+
+## 6. User Stories
+1. As a developer, I want to be guided through the workflow steps so I can avoid skipping critical tasks.
+2. As a team lead, I want an auditable history of workflow completion so I can ensure compliance.
+3. As an integrator, I want a simple API (tools/prompts) so I can plug the MCP server into existing agent workflows.
+
+## 7. Functional Requirements
+- Provide MCP tools covering the full workflow lifecycle (start task, fix, test, document, commit, release, complete).
+- Persist workflow state per project and per user, with compatibility handling for legacy locations.
+- 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.
+
+## 8. Technical Considerations
+- Node.js (ESM) codebase leveraging `@modelcontextprotocol/sdk`.
+- File-based state stored under `.state/users/<user>/workflow-state.json` with compatibility symlinks.
+- Optional SQLite integration for history and summary caching.
+- Vite build pipeline for distribution bundle; source usage recommended for MCP.
+- Windows compatibility requirements (Python, Build Tools for native modules).
+
+## 9. Success Metrics
+- ≥90% of workflow operations executed via MCP tools (vs. manual overrides).
+- Reduction in release guard violations to <5% of attempts.
+- Positive qualitative feedback on guidance clarity from pilot teams.
+
+## 10. Milestones
+1. **MVP**: Core workflow tools, state persistence, basic history (complete).
+2. **Enhancements**: Improved project root detection, compatibility mirrors, `run_full_workflow` automation (in progress).
+3. **Future**: Expanded dashboard analytics, customizable workflows, richer integrations.
+
+## 11. Risks & Mitigations
+- **Risk**: Workflow feels overly prescriptive. **Mitigation**: Provide escape hatches (`force_complete_task`, `drop_task`) with audit trails.
+- **Risk**: State corruption due to concurrent access. **Mitigation**: File locking and defensive JSON parsing (existing code handles gracefully, but monitor).
+- **Risk**: Integration friction with IDE clients. **Mitigation**: Maintain detailed README instructions and example configurations.
+
+## 12. Open Questions
+- Should additional workflow phases (e.g., design review) be supported?
+- How should multi-branch workflows be represented in history summaries?
+- What telemetry or analytics are acceptable within privacy constraints?

package/docs/web-dashboard.md

@@ -0,0 +1,163 @@
+# Dev Workflow Web Dashboard
+
+Learn how to start and use the Dev Workflow dashboard included with the MCP server. The dashboard exposes project history, summaries, and aggregates through a small Node.js service.
+
+## Prerequisites
+
+Before launching the dashboard, confirm the following:
+
+- Node.js 18+ installed (same requirement as the MCP server)
+- Project dependencies installed with `npm install`
+- Workflow history stored under `.state/` (created automatically when using the MCP server)
+
+> **Plesk users:** follow the [Plesk installation guide](../README.md#option-3-install-on-plesk-hosting) first and ensure SSH access is enabled.
+
+## Features
+
+- **Task history browser** – Paginated list of completed workflow entries.
+- **Summary stats** – Counts of tasks by type and recent activity timeline.
+- **Aggregated trends** – Daily, monthly, or yearly breakdowns of workflow activity.
+- **Multi-user support** – Switch between user identifiers recorded in the `.state` directory.
+
+## Getting Started
+
+Launch the dashboard from your project directory:
+
+```bash
+npm run web
+```
+
+When the server is ready you will see:
+
+```
+🌐 Dev Workflow Dashboard running at http://localhost:3111
+```
+
+Open the URL in your browser. If port 3111 is in use, the script automatically selects a nearby free port.
+
+### Choosing a Port
+
+Set `DEV_WORKFLOW_WEB_PORT` to force a specific port:
+
+```bash
+DEV_WORKFLOW_WEB_PORT=5000 npm run web
+```
+
+### Selecting a User
+
+The dashboard defaults to the `default` user. Append `?user=<USER_ID>` to view another user’s data. User IDs map to the subdirectories under `.state/users/`.
+
+```
+http://localhost:3111/?user=my-teammate
+```
+
+## Navigation
+
+The HTML frontend lives in `web/index.html`. The default UI includes:
+
+- **Summary cards** – Total tasks completed and last active date.
+- **Recent tasks table** – Paginated entries with task descriptions and timestamps.
+- **Charts** (if script extensions are enabled) – Visual trends per frequency selection.
+
+## API Reference
+
+Interact with the dashboard programmatically using the JSON endpoints served by `web/server.js`.
+
+### `GET /api/summary`
+
+Returns aggregate statistics for a user.
+
+**Query parameters**
+
+- `user` *(optional, string)* – User identifier (default `default`).
+
+**Response**
+
+```json
+{
+  "summary": {
+    "totalTasks": 12,
+    "taskTypes": { "feature": 8, "bugfix": 3, "refactor": 1 },
+    "lastActive": "2025-10-01T09:25:41.123Z",
+    "recentTasks": [
+      { "description": "feat: add billing webhooks", "type": "feature", "timestamp": "2025-10-01T09:25:41.123Z" }
+    ],
+    "updatedAt": "2025-10-01T09:30:00.000Z"
+  }
+}
+```
+
+### `GET /api/history`
+
+Returns paginated task history.
+
+**Query parameters**
+
+- `user` *(optional, string)* – User identifier (default `default`).
+- `page` *(optional, number)* – Page number (default `1`).
+- `pageSize` *(optional, number)* – Items per page (default `20`, max `100`).
+- `startDate` *(optional, string)* – Filter by ISO date (inclusive).
+- `endDate` *(optional, string)* – Filter by ISO date (inclusive).
+
+**Response**
+
+```json
+{
+  "entries": [
+    {
+      "id": 42,
+      "user_id": "default",
+      "task_description": "feat: add reporting endpoint",
+      "task_type": "feature",
+      "commit_message": "feat: add reporting endpoint",
+      "timestamp": "2025-09-30T09:18:00.000Z"
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "pageSize": 20
+}
+```
+
+### `GET /api/history-summary`
+
+Returns an array of task counts grouped by period.
+
+**Query parameters**
+
+- `user` *(optional, string)* – User identifier (default `default`).
+- `frequency` *(optional, string)* – `daily`, `monthly`, or `yearly` (default `daily`).
+- `startDate`, `endDate` *(optional, string)* – Limit range by ISO dates.
+
+**Response**
+
+```json
+{
+  "summary": [
+    { "period": "2025-09-30", "count": 3 },
+    { "period": "2025-09-29", "count": 1 }
+  ]
+}
+```
+
+## Configuration
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `DEV_WORKFLOW_WEB_PORT` | Port for the dashboard | `3111` or next available |
+| `DEV_WORKFLOW_USER_ID` | User identifier when launching via MCP | auto-generated |
+| `DEV_WORKFLOW_STATE_FILE` | Overrides path to workflow state JSON | auto-detected |
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Server fails with `better-sqlite3` build error | Install Python 3 and build tools (Windows) or ensure SQLite build dependencies exist (Linux/macOS). |
+| Dashboard shows empty data | Confirm the MCP server has generated `.state/users/<user>/workflow-state.json` and that the chosen `user` matches. |
+| Port already in use | Set `DEV_WORKFLOW_WEB_PORT` to a free port before running `npm run web`. |
+
+## Related Topics
+
+- [Main README](../README.md)
+- [Workflow State Internals](./state.md) *(coming soon)*
+- [CLI Tools](../README.md#🛠️-available-tools)

package/index.js

@@ -199,9 +199,74 @@ export async function main() {
   console.error("Dev Workflow MCP Server running on stdio");
 }
 
-if (process.argv[1] === __filename) {
-  main().catch((error) => {
-    console.error("Server error:", error);
+// --- Lightweight CLI: dev-workflow-mcp call <toolName> [--args '<json>'] ---
+async function cliMain(argv) {
+  const [, , subcommand, toolName, ...rest] = argv;
+  if (subcommand !== "call") return false;
+
+  if (!toolName || typeof toolName !== "string" || toolName.trim() === "") {
+    console.error("Usage: dev-workflow-mcp call <toolName> [--args '<json>']");
+    process.exit(2);
+  }
+
+  // Parse --args '<json>' if provided
+  let rawArgs = undefined;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--args") {
+      rawArgs = rest[i + 1];
+      break;
+    }
+  }
+
+  try {
+    // Initialize workflow state similar to the server path
+    workflowState = new WorkflowState();
+    await workflowState.load();
+    await workflowState.ensurePrimaryFile();
+
+    const request = {
+      params: {
+        name: toolName,
+        arguments: rawArgs ?? {},
+      },
+    };
+
+    const response = await handleToolCall({
+      request,
+      normalizeRequestArgs,
+      workflowState,
+      exec,
+      git: {
+        hasWorkingChanges,
+        hasTestChanges,
+        hasStagedChanges,
+        getStagedChanges,
+        getCurrentBranch,
+        getLastCommitMessage,
+        workingTreeSummary,
+      },
+      utils: { shellEscape, determineReleaseTypeFromCommit, createCommitMessageParts },
+    });
+
+    const text = response?.content?.[0]?.text || "";
+    console.log(text);
+    const isError = /^\s*[⚠️❌]/u.test(text);
+    process.exit(isError ? 1 : 0);
+  } catch (error) {
+    console.error("CLI error:", error.message || String(error));
     process.exit(1);
-  });
+  }
+}
+
+const isDirectRun = process.argv[1] === __filename;
+if (isDirectRun) {
+  // If invoked with a CLI subcommand, run it; otherwise start MCP server
+  if (process.argv[2] === "call") {
+    cliMain(process.argv);
+  } else {
+    main().catch((error) => {
+      console.error("Server error:", error);
+      process.exit(1);
+    });
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.1.11",
+  "version": "1.1.16",
   "description": "MCP server to enforce development workflow discipline",
   "type": "module",
   "main": "index.js",
@@ -30,6 +30,10 @@
   ],
   "author": "",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/programinglive/dev-workflow-mcp-server.git"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^11.8.0",

package/release-wrapper.js

@@ -22,7 +22,32 @@ async function main() {
     process.exit(1);
   }
 
-  const statePath = path.join(projectRoot, '.state', 'workflow-state.json');
+  // 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 {

package/tests/exec.test.js

@@ -6,17 +6,20 @@ import { mkdtemp, rm } from 'fs/promises';
 import path from 'path';
 
 test('exec runs commands successfully', async () => {
-  const { stdout } = await exec('echo "hello world"');
-  assert.strictEqual(stdout.trim(), 'hello world');
+  const echoCommand = process.platform === 'win32' ? 'echo hello world' : 'echo "hello world"';
+  const { stdout } = await exec(echoCommand);
+  const normalized = stdout.trim().replace(/^"(.*)"$/, '$1');
+  assert.strictEqual(normalized, 'hello world');
 });
 
 test('exec respects explicit cwd option', async () => {
   const tempDir = await mkdtemp(path.join(tmpdir(), 'mcp-test-'));
   
   try {
-    const { stdout } = await exec('pwd', { cwd: tempDir });
+    const dirCommand = process.platform === 'win32' ? 'cd' : 'pwd';
+    const { stdout } = await exec(dirCommand, { cwd: tempDir });
     // Just verify it runs in the specified directory (path may vary by platform)
-    assert(stdout.trim().includes('mcp-test-'));
+    assert(stdout.trim().toLowerCase().includes('mcp-test-'));
   } finally {
     await rm(tempDir, { recursive: true, force: true });
   }

package/tests/release-wrapper.test.js

@@ -3,10 +3,14 @@ import assert from "node:assert/strict";
 import { mkdtemp, rm, writeFile, readFile, mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 
-const PROJECT_ROOT = path.resolve(new URL("..", import.meta.url).pathname);
-const RELEASE_WRAPPER = path.join(PROJECT_ROOT, "release-wrapper.js");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const releaseWrapperUrl = new URL("../release-wrapper.js", import.meta.url);
+const RELEASE_WRAPPER = fileURLToPath(releaseWrapperUrl);
+const PROJECT_ROOT = path.dirname(RELEASE_WRAPPER);
 
 async function runWrapper({ state, args = ["patch"], env = {} }) {
   const dir = await mkdtemp(path.join(tmpdir(), "release-wrapper-test-"));
@@ -22,14 +26,18 @@ async function runWrapper({ state, args = ["patch"], env = {} }) {
     ...env,
   };
 
+  const nodeBinary = process.platform === "win32" ? "node" : process.execPath || "node";
+  const spawnShell = process.platform === "win32";
+
   return await new Promise((resolve) => {
     const child = spawn(
-      process.execPath,
+      nodeBinary,
       [RELEASE_WRAPPER, ...args],
       {
         cwd: PROJECT_ROOT,
         env: childEnv,
         stdio: ["ignore", "pipe", "pipe"],
+        shell: spawnShell,
       }
     );
 

package/tests/workflowState.test.js

@@ -36,6 +36,58 @@ async function withWorkflowState(callback) {
   }
 }
 
+test("resolveStateFile prefers current working directory when multiple project markers exist", async () => {
+  const tempRoot = await mkdtemp(path.join(tmpdir(), "workflow-prefers-cwd-"));
+  const moduleDir = path.join(tempRoot, "module");
+  const projectA = path.join(tempRoot, "project-a");
+  const projectB = path.join(tempRoot, "project-b");
+  const projectBNested = path.join(projectB, "sub", "app");
+
+  await mkdir(moduleDir, { recursive: true });
+  await mkdir(projectA, { recursive: true });
+  await mkdir(projectBNested, { recursive: true });
+
+  const sourceModulePath = fileURLToPath(new URL("../workflow-state.js", import.meta.url));
+  await copyFile(sourceModulePath, path.join(moduleDir, "workflow-state.js"));
+
+  await writeFile(path.join(moduleDir, "package.json"), JSON.stringify({ name: "module" }));
+  await writeFile(path.join(projectA, "package.json"), JSON.stringify({ name: "project-a" }));
+  await writeFile(path.join(projectB, "package.json"), JSON.stringify({ name: "project-b" }));
+
+  const moduleUrl = pathToFileURL(path.join(moduleDir, "workflow-state.js"));
+  const { WorkflowState: TempWorkflowState } = await import(`${moduleUrl.href}?preferCwd=${Date.now()}`);
+
+  const originalCwd = process.cwd();
+  const initWasSet = Object.prototype.hasOwnProperty.call(process.env, "INIT_CWD");
+  const originalInitCwd = process.env.INIT_CWD;
+
+  try {
+    process.chdir(projectBNested);
+    process.env.INIT_CWD = projectA;
+
+    const state = new TempWorkflowState();
+    const resolvedStateFile = state.stateFile;
+
+    assert.ok(
+      resolvedStateFile.startsWith(path.join(projectB, ".state", "users")),
+      "State file should resolve under the current working directory's project"
+    );
+
+    assert.ok(
+      !resolvedStateFile.startsWith(path.join(projectA, ".state")),
+      "State file should not use INIT_CWD project when cwd has its own markers"
+    );
+  } finally {
+    process.chdir(originalCwd);
+    if (initWasSet) {
+      process.env.INIT_CWD = originalInitCwd;
+    } else {
+      delete process.env.INIT_CWD;
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test("WorkflowState mirrors state file to compatibility locations", async () => {
   const tempRoot = await mkdtemp(path.join(tmpdir(), "workflow-compat-"));
   const moduleDir = path.join(tempRoot, "module");
@@ -94,8 +146,8 @@ test("WorkflowState avoids filesystem root when no project markers found", async
     const resolvedTempRoot = await realpath(tempRoot);
 
     assert.ok(
-      state.stateFile.startsWith(path.join(resolvedTempRoot, ".state")),
-      "state file should resolve under temp root when no project markers exist"
+      state.stateFile.startsWith(resolvedTempRoot),
+      "state file should remain inside the temporary root when no project markers exist"
     );
     assert.ok(
       !state.stateFile.startsWith(path.join(path.sep, ".state")),