@projitive/mcp 1.0.5 → 1.0.7

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.5**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.7**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -149,7 +149,7 @@ npm run test
 #### `projectInit`
 
 - **Purpose**: manually initialize governance directory structure for a project (default `.projitive`).
-- **Input**: `projectPath?`, `governanceDir?`, `force?`
+- **Input**: `projectPath`, `governanceDir?`, `force?`
 - **Output Example (Markdown)**:
 
 ```markdown
@@ -177,7 +177,7 @@ npm run test
 #### `projectNext`
 
 - **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).
-- **Input**: `rootPath?`, `maxDepth?`, `limit?`
+- **Input**: `maxDepth?`, `limit?`
 - **Output Example (Markdown)**:
 
 ```markdown
@@ -294,7 +294,7 @@ npm run test
 #### `taskNext`
 
 - **Purpose**: one-step workflow for project discovery + best task selection + evidence/read-order output.
-- **Input**: `rootPath?`, `maxDepth?`, `topCandidates?`
+- **Input**: `maxDepth?`, `topCandidates?`
 - **Output Example (Markdown)**:
 
 ```markdown

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "1.0.5",
+    "version": "1.0.7",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",

package/output/source/design-context.js

@@ -84,8 +84,11 @@ export function registerDesignContextPrompts(server) {
                     text: [
                         "Execute Projitive task with minimal calls:",
                         "",
+                        "Prerequisite:",
+                        "- If target project has no `.projitive`, run: projectInit(projectPath=<project-dir>)",
+                        "",
                         "STEP 1: Get task (1 call)",
-                        "- Run: taskNext(rootPath=workspace)",
+                        "- Run: taskNext()",
                         "- Result: selectedTaskId, suggestedReadOrder",
                         "",
                         "STEP 2: Load context (1-2 calls)",

package/output/source/index.js

@@ -47,7 +47,7 @@ function renderMethodCatalogMarkdown() {
         "## Start Here",
         "- Unknown project path: `projectScan` -> `projectLocate` -> `projectContext` -> `taskNext`.",
         "- Known project path: `projectContext` -> `taskNext` (or `taskList`) -> `taskContext`.",
-        "- Need to bootstrap governance: call `projectInit` only when `.projitive` is missing.",
+        "- Need to bootstrap governance: call `projectInit(projectPath=\"<project-dir>\")` only when `.projitive` is missing.",
         "",
         "## Methods",
         "| Order | Group | Method | Agent Use |",
@@ -61,7 +61,7 @@ function renderMethodCatalogMarkdown() {
         "| 7 | Roadmap | roadmapList | inspect roadmap-task linkage |",
         "| 8 | Roadmap | roadmapContext | inspect one roadmap with references |",
         "| 9 | Project | projectNext | rank actionable projects across workspace |",
-        "| 10 | Project | projectInit | bootstrap governance files if missing |",
+        "| 10 | Project | projectInit | bootstrap governance files if missing |"
     ].join("\n");
 }
 function registerGovernanceResources() {
@@ -132,14 +132,13 @@ function registerGovernancePrompts() {
         title: "Execute Task Workflow",
         description: "Primary execution prompt: select one task, execute, and verify evidence consistency",
         argsSchema: {
-            rootPath: z.string().optional(),
             projectPath: z.string().optional(),
             taskId: z.string().optional(),
         },
-    }, async ({ rootPath, projectPath, taskId }) => {
+    }, async ({ projectPath, taskId }) => {
         const taskEntry = taskId && projectPath
             ? `1) Run taskContext(projectPath=\"${projectPath}\", taskId=\"${taskId}\").`
-            : `1) Run taskNext(${rootPath ? `rootPath=\"${rootPath}\"` : ""}).`;
+            : "1) Run taskNext().";
         const text = [
             "You are executing Projitive governance workflow in agent-first mode.",
             "",
@@ -150,6 +149,7 @@ function registerGovernancePrompts() {
             "4) Re-run taskContext for the selected task and verify references.",
             "",
             "Fallbacks:",
+            "- If `.projitive` is missing for a known project, run `projectInit(projectPath=\"<project-dir>\")` first.",
             "- If taskNext returns no actionable task, follow its no-task checklist and create 1-3 TODO tasks.",
             "- If project is unknown, run projectScan -> projectLocate -> projectContext before task tools.",
             "",
@@ -189,17 +189,16 @@ function registerGovernancePrompts() {
     server.registerPrompt("triageProjectGovernance", {
         title: "Triage Project Governance",
         description: "Discovery-first triage prompt to pick project and next executable task",
-        argsSchema: {
-            rootPath: z.string().optional(),
-        },
-    }, async ({ rootPath }) => {
+        argsSchema: {},
+    }, async () => {
         const text = [
             "Triage governance and pick one execution target quickly.",
             "",
+            "0) If known project has no `.projitive`, run projectInit(projectPath=<project-dir>) first.",
             "1) If project path is unknown, run projectScan() and pick one discovered project.",
-            `2) Run projectNext(${rootPath ? `rootPath=\"${rootPath}\"` : ""}) to rank projects.`,
+            "2) Run projectNext() to rank projects.",
             "3) Run projectContext(projectPath=<selectedProject>).",
-            "4) Run taskNext(rootPath=<workspaceRootIfNeeded>) for best actionable task.",
+            "4) Run taskNext() for best actionable task.",
             "5) If manual filtering is needed, run taskList(projectPath=<selectedProject>, status=IN_PROGRESS).",
             "6) Continue with taskContext(projectPath=<selectedProject>, taskId=<selectedTaskId>).",
         ].join("\n");

package/output/source/projitive.js

@@ -133,6 +133,41 @@ function parentDir(dirPath) {
     const parent = path.dirname(dirPath);
     return parent === dirPath ? null : parent;
 }
+export function toProjectPath(governanceDir) {
+    return path.dirname(governanceDir);
+}
+async function listChildGovernanceDirs(parentPath) {
+    const entriesResult = await catchIt(fs.readdir(parentPath, { withFileTypes: true }));
+    if (entriesResult.isError()) {
+        return [];
+    }
+    const folders = entriesResult.value
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(parentPath, entry.name));
+    const markerChecks = await Promise.all(folders.map(async (folderPath) => ({
+        folderPath,
+        hasMarker: await hasProjectMarker(folderPath),
+    })));
+    const candidates = markerChecks
+        .filter((item) => item.hasMarker)
+        .map((item) => item.folderPath)
+        .sort((a, b) => a.localeCompare(b));
+    return candidates;
+}
+async function resolveChildGovernanceDir(parentPath) {
+    const candidates = await listChildGovernanceDirs(parentPath);
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const defaultCandidate = path.join(parentPath, DEFAULT_GOVERNANCE_DIR);
+    if (candidates.includes(defaultCandidate)) {
+        return defaultCandidate;
+    }
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    throw new Error(`Multiple governance roots found under path: ${parentPath}. Use projectPath/governanceDir explicitly.`);
+}
 export async function resolveGovernanceDir(inputPath) {
     const absolutePath = path.resolve(inputPath);
     const statResult = await catchIt(fs.stat(absolutePath));
@@ -145,6 +180,10 @@ export async function resolveGovernanceDir(inputPath) {
         if (await hasProjectMarker(cursor)) {
             return cursor;
         }
+        const childGovernanceDir = await resolveChildGovernanceDir(cursor);
+        if (childGovernanceDir) {
+            return childGovernanceDir;
+        }
         cursor = parentDir(cursor);
     }
     throw new Error(`No ${PROJECT_MARKER} marker found from path: ${absolutePath}`);
@@ -158,6 +197,8 @@ export async function discoverProjects(rootPath, maxDepth) {
         if (await hasProjectMarker(currentPath)) {
             results.push(currentPath);
         }
+        const childGovernanceDirs = await listChildGovernanceDirs(currentPath);
+        results.push(...childGovernanceDirs);
         const entriesResult = await catchIt(fs.readdir(currentPath, { withFileTypes: true }));
         if (entriesResult.isError()) {
             return;
@@ -274,9 +315,9 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
 export function registerProjectTools(server) {
     server.registerTool("projectInit", {
         title: "Project Init",
-        description: "Bootstrap governance files when a project has no .projitive yet",
+        description: "Bootstrap governance files when a project has no .projitive yet (requires projectPath)",
         inputSchema: {
-            projectPath: z.string().optional(),
+            projectPath: z.string(),
             governanceDir: z.string().optional(),
             force: z.boolean().optional(),
         },
@@ -313,7 +354,7 @@ export function registerProjectTools(server) {
                     "- After init, fill owner/roadmapRefs/links in tasks.md before marking DONE.",
                     "- Keep task source-of-truth inside marker block only.",
                 ]),
-                nextCallSection(`projectContext(projectPath=\"${initialized.governanceDir}\")`),
+                nextCallSection(`projectContext(projectPath=\"${initialized.projectPath}\")`),
             ],
         });
         return asText(markdown);
@@ -356,12 +397,11 @@ export function registerProjectTools(server) {
         title: "Project Next",
         description: "Rank actionable projects and return the best execution target",
         inputSchema: {
-            rootPath: z.string().optional(),
             maxDepth: z.number().int().min(0).max(8).optional(),
             limit: z.number().int().min(1).max(50).optional(),
         },
-    }, async ({ rootPath, maxDepth, limit }) => {
-        const root = resolveScanRoot(rootPath);
+    }, async ({ maxDepth, limit }) => {
+        const root = resolveScanRoot();
         const depth = resolveScanDepth(maxDepth);
         const projects = await discoverProjects(root, depth);
         const snapshots = await Promise.all(projects.map(async (governanceDir) => {
@@ -409,13 +449,13 @@ export function registerProjectTools(server) {
                     ...ranked.map((item, index) => `${index + 1}. ${item.governanceDir} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt} | tasksPath=${item.tasksPath}${item.tasksExists ? "" : " (missing)"}`),
                 ]),
                 guidanceSection([
-                    "- Pick top 1 project and call `projectContext` with its governanceDir.",
+                    "- Pick top 1 project and call `projectContext` with its projectPath.",
                     "- Then call `taskList` and `taskContext` to continue execution.",
                     "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
                 ]),
                 lintSection(ranked[0]?.lintSuggestions ?? []),
                 nextCallSection(ranked[0]
-                    ? `projectContext(projectPath=\"${ranked[0].governanceDir}\")`
+                    ? `projectContext(projectPath=\"${toProjectPath(ranked[0].governanceDir)}\")`
                     : undefined),
             ],
         });
@@ -430,18 +470,20 @@ export function registerProjectTools(server) {
     }, async ({ inputPath }) => {
         const resolvedFrom = normalizePath(inputPath);
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
+        const projectPath = toProjectPath(governanceDir);
         const markerPath = path.join(governanceDir, ".projitive");
         const markdown = renderToolResponseMarkdown({
             toolName: "projectLocate",
             sections: [
                 summarySection([
                     `- resolvedFrom: ${resolvedFrom}`,
+                    `- projectPath: ${projectPath}`,
                     `- governanceDir: ${governanceDir}`,
                     `- markerPath: ${markerPath}`,
                 ]),
-                guidanceSection(["- Call `projectContext` with this governanceDir to get task and roadmap summaries."]),
+                guidanceSection(["- Call `projectContext` with this projectPath to get task and roadmap summaries."]),
                 lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
-                nextCallSection(`projectContext(projectPath=\"${governanceDir}\")`),
+                nextCallSection(`projectContext(projectPath=\"${projectPath}\")`),
             ],
         });
         return asText(markdown);
@@ -454,6 +496,7 @@ export function registerProjectTools(server) {
         },
     }, async ({ projectPath }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
+        const normalizedProjectPath = toProjectPath(governanceDir);
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
         const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
         const roadmapIds = await readRoadmapIds(governanceDir);
@@ -469,6 +512,7 @@ export function registerProjectTools(server) {
             toolName: "projectContext",
             sections: [
                 summarySection([
+                    `- projectPath: ${normalizedProjectPath}`,
                     `- governanceDir: ${governanceDir}`,
                     `- tasksFile: ${tasksPath}`,
                     `- roadmapIds: ${roadmapIds.length}`,
@@ -489,7 +533,7 @@ export function registerProjectTools(server) {
                     "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskList(projectPath=\"${governanceDir}\")`),
+                nextCallSection(`taskList(projectPath=\"${normalizedProjectPath}\")`),
             ],
         });
         return asText(markdown);

package/output/source/projitive.test.js

@@ -31,6 +31,24 @@ describe("projitive module", () => {
         const resolved = await resolveGovernanceDir(deepDir);
         expect(resolved).toBe(governanceDir);
     });
+    it("resolves nested default governance dir when input path is project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "repo");
+        const governanceDir = path.join(projectRoot, ".projitive");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const resolved = await resolveGovernanceDir(projectRoot);
+        expect(resolved).toBe(governanceDir);
+    });
+    it("resolves nested custom governance dir when input path is project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "repo");
+        const governanceDir = path.join(projectRoot, "governance");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const resolved = await resolveGovernanceDir(projectRoot);
+        expect(resolved).toBe(governanceDir);
+    });
     it("discovers projects by marker file", async () => {
         const root = await createTempDir();
         const p1 = path.join(root, "a");
@@ -43,6 +61,24 @@ describe("projitive module", () => {
         expect(projects).toContain(p1);
         expect(projects).toContain(p2);
     });
+    it("discovers nested default governance directory under project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "app");
+        const governanceDir = path.join(projectRoot, ".projitive");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const projects = await discoverProjects(root, 3);
+        expect(projects).toContain(governanceDir);
+    });
+    it("discovers nested custom governance directory under project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "app");
+        const governanceDir = path.join(projectRoot, "governance");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const projects = await discoverProjects(root, 3);
+        expect(projects).toContain(governanceDir);
+    });
     it("initializes governance structure under default .projitive directory", async () => {
         const root = await createTempDir();
         const initialized = await initializeProjectStructure(root);

package/output/source/roadmap.js

@@ -6,7 +6,7 @@ import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
 import { ROADMAP_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
 import { findTextReferences } from "./helpers/markdown/index.js";
 import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
-import { resolveGovernanceDir } from "./projitive.js";
+import { resolveGovernanceDir, toProjectPath } from "./projitive.js";
 import { loadTasks } from "./tasks.js";
 export const ROADMAP_ID_REGEX = /^ROADMAP-\d{4}$/;
 function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
@@ -99,7 +99,7 @@ export function registerRoadmapTools(server) {
                 guidanceSection(["- Pick one roadmap ID and call `roadmapContext`."]),
                 lintSection(lintSuggestions),
                 nextCallSection(roadmapIds[0]
-                    ? `roadmapContext(projectPath=\"${governanceDir}\", roadmapId=\"${roadmapIds[0]}\")`
+                    ? `roadmapContext(projectPath=\"${toProjectPath(governanceDir)}\", roadmapId=\"${roadmapIds[0]}\")`
                     : undefined),
             ],
         });
@@ -157,7 +157,7 @@ export function registerRoadmapTools(server) {
                     "- Re-run `roadmapContext` after edits to confirm references remain consistent.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`roadmapContext(projectPath=\"${governanceDir}\", roadmapId=\"${roadmapId}\")`),
+                nextCallSection(`roadmapContext(projectPath=\"${toProjectPath(governanceDir)}\", roadmapId=\"${roadmapId}\")`),
             ],
         });
         return asText(markdown);

package/output/source/tasks.js

@@ -7,7 +7,7 @@ import { findTextReferences } from "./helpers/markdown/index.js";
 import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
 import { catchIt } from "./helpers/catch/index.js";
 import { TASK_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
-import { resolveGovernanceDir, resolveScanDepth, resolveScanRoot, discoverProjects } from "./projitive.js";
+import { resolveGovernanceDir, resolveScanDepth, resolveScanRoot, discoverProjects, toProjectPath } from "./projitive.js";
 import { isValidRoadmapId } from "./roadmap.js";
 export const TASKS_START = "<!-- PROJITIVE:TASKS:START -->";
 export const TASKS_END = "<!-- PROJITIVE:TASKS:END -->";
@@ -535,7 +535,7 @@ export function registerTaskTools(server) {
                 guidanceSection(["- Pick one task ID and call `taskContext`."]),
                 lintSection(lintSuggestions),
                 nextCallSection(nextTaskId
-                    ? `taskContext(projectPath=\"${governanceDir}\", taskId=\"${nextTaskId}\")`
+                    ? `taskContext(projectPath=\"${toProjectPath(governanceDir)}\", taskId=\"${nextTaskId}\")`
                     : undefined),
             ],
         });
@@ -545,12 +545,11 @@ export function registerTaskTools(server) {
         title: "Task Next",
         description: "Start here to auto-select the highest-priority actionable task",
         inputSchema: {
-            rootPath: z.string().optional(),
             maxDepth: z.number().int().min(0).max(8).optional(),
             topCandidates: z.number().int().min(1).max(20).optional(),
         },
-    }, async ({ rootPath, maxDepth, topCandidates }) => {
-        const root = resolveScanRoot(rootPath);
+    }, async ({ maxDepth, topCandidates }) => {
+        const root = resolveScanRoot();
         const depth = resolveScanDepth(maxDepth);
         const projects = await discoverProjects(root, depth);
         const rankedCandidates = rankActionableTaskCandidates(await readActionableTaskCandidates(projects));
@@ -610,7 +609,7 @@ export function registerTaskTools(server) {
                         "- Ensure each new task has stable TASK-xxxx ID and at least one roadmapRefs item.",
                     ]),
                     nextCallSection(preferredProject
-                        ? `projectContext(projectPath=\"${preferredProject.governanceDir}\")`
+                        ? `projectContext(projectPath=\"${toProjectPath(preferredProject.governanceDir)}\")`
                         : "projectScan()"),
                 ],
             });
@@ -673,7 +672,7 @@ export function registerTaskTools(server) {
                     "- Re-run `taskContext` for the selectedTaskId after edits to verify evidence consistency.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskContext(projectPath=\"${selected.governanceDir}\", taskId=\"${selected.task.id}\")`),
+                nextCallSection(`taskContext(projectPath=\"${toProjectPath(selected.governanceDir)}\", taskId=\"${selected.task.id}\")`),
             ],
         });
         return asText(markdown);
@@ -697,7 +696,7 @@ export function registerTaskTools(server) {
         const task = tasks.find((item) => item.id === taskId);
         if (!task) {
             return {
-                ...asText(renderErrorMarkdown("taskContext", `Task not found: ${taskId}`, ["run `taskList` to discover available IDs", "retry with an existing task ID"], `taskList(projectPath=\"${governanceDir}\")`)),
+                ...asText(renderErrorMarkdown("taskContext", `Task not found: ${taskId}`, ["run `taskList` to discover available IDs", "retry with an existing task ID"], `taskList(projectPath=\"${toProjectPath(governanceDir)}\")`)),
                 isError: true,
             };
         }
@@ -754,7 +753,7 @@ export function registerTaskTools(server) {
                     "- After editing, re-run `taskContext` to verify references and context consistency.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskContext(projectPath=\"${governanceDir}\", taskId=\"${task.id}\")`),
+                nextCallSection(`taskContext(projectPath=\"${toProjectPath(governanceDir)}\", taskId=\"${task.id}\")`),
             ],
         });
         return asText(coreMarkdown);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projitive/mcp",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Projitive MCP Server for project and task discovery/update",
   "license": "ISC",
   "author": "",