@projitive/mcp 1.0.2 → 1.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.2**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.3**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -50,6 +50,17 @@ taskNext
   -> taskNext (next cycle)
 ```
 
+When no actionable task exists (`actionableTasks: 0`), use bootstrap path:
+
+```text
+taskNext
+  -> projectContext
+  -> create 1-3 TODO tasks in tasks.md marker block (from roadmap/readme/report gaps)
+  -> taskNext
+```
+
+Optional customization: add `hooks/task_no_actionable.md` in governance root to override the default no-task discovery checklist.
+
 When the agent starts inside a project:
 
 ```text
@@ -58,17 +69,43 @@ projectLocate -> projectContext -> taskList -> taskContext
 
 ## Quick Start
 
+Use npm package directly in MCP client configuration:
+
 ```bash
-cd packages/mcp
-npm ci
-npm run build
-npm run test
+npx -y @projitive/mcp
+```
+
+MCP client config example (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "projitive": {
+      "command": "npx",
+      "args": ["-y", "@projitive/mcp"],
+      "env": {
+        "PROJITIVE_SCAN_ROOT_PATH": "/absolute/path/to/your/workspace",
+        "PROJITIVE_SCAN_MAX_DEPTH": "3"
+      }
+    }
+  }
+}
 ```
 
-Then configure your MCP client to run:
+Environment variables:
+
+- `PROJITIVE_SCAN_ROOT_PATH`: fallback scan root for discovery methods when `rootPath` is omitted.
+- `PROJITIVE_SCAN_MAX_DEPTH`: fallback scan depth when `maxDepth` is omitted (`0-8`, default `3`).
+
+Local path startup is not the recommended usage mode in this README.
+
+For maintainers/contributors only:
 
 ```bash
-node /absolute/path/to/packages/mcp/output/index.js
+cd packages/mcp
+npm ci
+npm run build
+npm run test
 ```
 
 ## Spec Version
@@ -332,17 +369,9 @@ node /absolute/path/to/packages/mcp/output/index.js
 
 - **Purpose**: return task detail + related evidence locations in one call (replacing `trace.references`).
 - **Input**: `projectPath`, `taskId`
-- **HOOK Injection**:
-  - If `hooks/task_get_head.md` exists, its content is prepended to result.
-  - If `hooks/task_get_footer.md` exists, its content is appended to result.
-  - Used for project-level custom guidance without changing core `taskContext` shape.
 - **Output Example (Markdown)**:
 
 ```markdown
-[hooks/task_get_head.md content (if present)]
-
----
-
 # taskContext
 
 ## Summary
@@ -354,7 +383,6 @@ node /absolute/path/to/packages/mcp/output/index.js
 - updatedAt: 2026-02-17T12:00:00.000Z
 - roadmapRefs: ROADMAP-0001
 - taskLocation: /workspace/proj-a/tasks.md#L42
-- hookStatus: head=loaded, footer=missing
 
 ## Evidence
 ### Related Artifacts
@@ -379,10 +407,6 @@ node /absolute/path/to/packages/mcp/output/index.js
 
 ## Next Call
 - taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
-
----
-
-[hooks/task_get_footer.md content (if present)]
 ```
 
 ### Roadmap Layer

package/output/hooks.js

@@ -30,20 +30,7 @@ async function readHookFile(filePath) {
     }
     return { ok: true, content };
 }
-export async function resolveHookForEvent(governanceDir, task, event) {
-    const taskHookPath = task.hooks[event];
-    if (taskHookPath) {
-        const resolvedTaskPath = path.resolve(governanceDir, taskHookPath);
-        const taskFile = await readHookFile(resolvedTaskPath);
-        if (taskFile.ok) {
-            return {
-                event,
-                source: "task",
-                path: resolvedTaskPath,
-                content: taskFile.content,
-            };
-        }
-    }
+export async function resolveHookForEvent(governanceDir, event) {
     const globalPath = path.join(governanceDir, "hooks", GLOBAL_EVENT_FILES[event]);
     const globalFile = await readHookFile(globalPath);
     if (globalFile.ok) {

package/output/hooks.test.js

@@ -3,7 +3,6 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { detectHookEvent, resolveHookForEvent } from "./hooks.js";
-import { normalizeTask } from "./tasks.js";
 const tempPaths = [];
 async function createTempDir() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));
@@ -22,30 +21,20 @@ describe("hooks module", () => {
         expect(detectHookEvent("IN_PROGRESS", "BLOCKED")).toBe("onBlocked");
         expect(detectHookEvent("BLOCKED", "TODO")).toBe(null);
     });
-    it("prefers task-level hook over global hook", async () => {
+    it("loads global hook when global file exists", async () => {
         const root = await createTempDir();
         const governanceDir = path.join(root, "gov");
         await fs.mkdir(path.join(governanceDir, "hooks"), { recursive: true });
         await fs.writeFile(path.join(governanceDir, "hooks", "on_task_assigned.md"), "global assigned", "utf-8");
-        await fs.writeFile(path.join(governanceDir, "hooks", "custom-assigned.md"), "task assigned", "utf-8");
-        const task = normalizeTask({
-            id: "TASK-0001",
-            title: "Task",
-            status: "TODO",
-            hooks: { onAssigned: "./hooks/custom-assigned.md" },
-        });
-        const hook = await resolveHookForEvent(governanceDir, task, "onAssigned");
-        expect(hook.source).toBe("task");
-        expect(hook.content).toContain("task assigned");
+        const hook = await resolveHookForEvent(governanceDir, "onAssigned");
+        expect(hook.source).toBe("global");
+        expect(hook.content).toContain("global assigned");
     });
-    it("falls back to global hook when task-level hook is missing", async () => {
+    it("returns none when global hook is missing", async () => {
         const root = await createTempDir();
         const governanceDir = path.join(root, "gov");
         await fs.mkdir(path.join(governanceDir, "hooks"), { recursive: true });
-        await fs.writeFile(path.join(governanceDir, "hooks", "on_task_completed.md"), "global completed", "utf-8");
-        const task = normalizeTask({ id: "TASK-0001", title: "Task", status: "IN_PROGRESS" });
-        const hook = await resolveHookForEvent(governanceDir, task, "onCompleted");
-        expect(hook.source).toBe("global");
-        expect(hook.content).toContain("global completed");
+        const hook = await resolveHookForEvent(governanceDir, "onCompleted");
+        expect(hook.source).toBe("none");
     });
 });

package/output/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -10,14 +11,29 @@ import { registerProjectTools } from "./projitive.js";
 import { registerTaskTools } from "./tasks.js";
 import { registerRoadmapTools } from "./roadmap.js";
 const PROJITIVE_SPEC_VERSION = "1.0.0";
+const currentFilePath = fileURLToPath(import.meta.url);
+const sourceDir = path.dirname(currentFilePath);
+const repoRoot = path.resolve(sourceDir, "..", "..", "..");
+function resolveRuntimeVersion() {
+    const packageJsonPath = path.resolve(sourceDir, "..", "package.json");
+    try {
+        const raw = readFileSync(packageJsonPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // fallback handled below
+    }
+    return PROJITIVE_SPEC_VERSION;
+}
+const MCP_RUNTIME_VERSION = resolveRuntimeVersion();
 const server = new McpServer({
     name: "projitive",
-    version: PROJITIVE_SPEC_VERSION,
+    version: MCP_RUNTIME_VERSION,
     description: "Semantic Projitive MCP for project/task discovery and agent guidance with markdown-first outputs",
 });
-const currentFilePath = fileURLToPath(import.meta.url);
-const sourceDir = path.dirname(currentFilePath);
-const repoRoot = path.resolve(sourceDir, "..", "..", "..");
 function resolveRepoFile(relativePath) {
     return path.join(repoRoot, relativePath);
 }
@@ -170,7 +186,7 @@ function registerGovernancePrompts() {
             "Checklist:",
             "- Transition is valid per status machine.",
             "- links/roadmapRefs remain parseable and consistent.",
-            "- Hook paths (if any) still resolve.",
+            "- Only `hooks/task_no_actionable.md` is used as global background hook for no-task discovery.",
         ].join("\n");
         return asUserPrompt(text);
     });
@@ -200,6 +216,8 @@ registerRoadmapTools(server);
 registerGovernanceResources();
 registerGovernancePrompts();
 async function main() {
+    console.error(`[projitive-mcp] starting server`);
+    console.error(`[projitive-mcp] version=${MCP_RUNTIME_VERSION} spec=${PROJITIVE_SPEC_VERSION} transport=stdio pid=${process.pid}`);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/output/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@projitive/mcp",
+    "version": "1.0.3",
+    "description": "Projitive MCP Server for project and task discovery/update",
+    "license": "ISC",
+    "author": "",
+    "type": "module",
+    "bin": {
+        "mcp": "output/index.js"
+    },
+    "main": "./output/index.js",
+    "types": "./output/index.d.ts",
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "lint": "tsc -p tsconfig.json --noEmit",
+        "build": "tsc -p tsconfig.json",
+        "prepublishOnly": "npm run build",
+        "dev": "tsc -p tsconfig.json --watch"
+    },
+    "files": [
+        "output"
+    ],
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.17.5",
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@types/node": "^24.3.0",
+        "tsx": "^4.20.5",
+        "typescript": "^5.9.2",
+        "vitest": "^3.2.4"
+    }
+}

package/output/projitive.js

@@ -201,12 +201,30 @@ function defaultTasksMarkdown() {
         "- owner: unassigned",
         "- summary: Create initial governance artifacts and confirm task execution loop.",
         `- updatedAt: ${updatedAt}`,
-        "- links:",
         "- roadmapRefs: ROADMAP-0001",
-        "- hooks:",
+        "- links:",
+        "  - (none)",
         "<!-- PROJITIVE:TASKS:END -->",
     ].join("\n");
 }
+function defaultNoTaskDiscoveryHookMarkdown() {
+    return [
+        "Objective:",
+        "- When no actionable task exists, proactively discover meaningful work and convert it into TODO tasks.",
+        "",
+        "Checklist:",
+        "- Check whether code violates project guides/specs; create tasks for each actionable gap.",
+        "- Check test coverage improvement opportunities; create tasks for high-value missing tests.",
+        "- Check development/testing workflow bottlenecks; create tasks for reliability and speed improvements.",
+        "- Check TODO/FIXME/HACK comments; turn feasible items into governed tasks.",
+        "- Check dependency/security hygiene and stale tooling; create tasks where upgrades are justified.",
+        "",
+        "Output Format:",
+        "- Candidate findings (3-10)",
+        "- Proposed tasks (TASK-xxxx style)",
+        "- Priority rationale",
+    ].join("\n");
+}
 export async function initializeProjectStructure(inputPath, governanceDir, force = false) {
     const rootPath = normalizePath(inputPath);
     const governanceDirName = normalizeGovernanceDirName(governanceDir);
@@ -231,6 +249,7 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
         writeTextFile(path.join(governancePath, "README.md"), defaultReadmeMarkdown(governanceDirName), force),
         writeTextFile(path.join(governancePath, "roadmap.md"), defaultRoadmapMarkdown(), force),
         writeTextFile(path.join(governancePath, "tasks.md"), defaultTasksMarkdown(), force),
+        writeTextFile(path.join(governancePath, "hooks", "task_no_actionable.md"), defaultNoTaskDiscoveryHookMarkdown(), force),
     ]);
     return {
         rootPath,

package/output/projitive.test.js

@@ -52,6 +52,7 @@ describe("projitive module", () => {
             path.join(root, ".projitive", "README.md"),
             path.join(root, ".projitive", "roadmap.md"),
             path.join(root, ".projitive", "tasks.md"),
+            path.join(root, ".projitive", "hooks", "task_no_actionable.md"),
             path.join(root, ".projitive", "designs"),
             path.join(root, ".projitive", "reports"),
             path.join(root, ".projitive", "hooks"),

package/output/source/designs.js

@@ -0,0 +1,38 @@
+import { isValidRoadmapId } from "./roadmap.js";
+import { isValidTaskId } from "./tasks.js";
+export function parseDesignMetadata(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const metadata = {};
+    for (const line of lines) {
+        const [rawKey, ...rawValue] = line.split(":");
+        if (!rawKey || rawValue.length === 0) {
+            continue;
+        }
+        const key = rawKey.trim().toLowerCase();
+        const value = rawValue.join(":").trim();
+        if (key === "task")
+            metadata.task = value;
+        if (key === "roadmap")
+            metadata.roadmap = value;
+        if (key === "owner")
+            metadata.owner = value;
+        if (key === "status")
+            metadata.status = value;
+        if (key === "last updated")
+            metadata.lastUpdated = value;
+    }
+    return metadata;
+}
+export function validateDesignMetadata(metadata) {
+    const errors = [];
+    if (!metadata.task) {
+        errors.push("Missing Task metadata");
+    }
+    else if (!isValidTaskId(metadata.task)) {
+        errors.push(`Invalid Task metadata format: ${metadata.task}`);
+    }
+    if (metadata.roadmap && !isValidRoadmapId(metadata.roadmap)) {
+        errors.push(`Invalid Roadmap metadata format: ${metadata.roadmap}`);
+    }
+    return { ok: errors.length === 0, errors };
+}

package/output/source/helpers/artifacts/artifacts.js

@@ -0,0 +1,10 @@
+export function candidateFilesFromArtifacts(artifacts) {
+    return artifacts
+        .filter((item) => item.exists)
+        .flatMap((item) => {
+        if (item.kind === "file") {
+            return [item.path];
+        }
+        return (item.markdownFiles ?? []).map((entry) => entry.path);
+    });
+}

package/output/source/helpers/artifacts/artifacts.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { candidateFilesFromArtifacts } from "./artifacts.js";
+describe("candidateFilesFromArtifacts", () => {
+    it("collects existing file artifacts and markdown files from existing directories", () => {
+        const candidates = candidateFilesFromArtifacts([
+            { name: "README.md", kind: "file", path: "/a/README.md", exists: true, lineCount: 3 },
+            { name: "tasks.md", kind: "file", path: "/a/tasks.md", exists: false },
+            {
+                name: "designs",
+                kind: "directory",
+                path: "/a/designs",
+                exists: true,
+                markdownFiles: [{ path: "/a/designs/d1.md", lineCount: 10 }],
+            },
+        ]);
+        expect(candidates).toEqual(["/a/README.md", "/a/designs/d1.md"]);
+    });
+});

package/output/source/helpers/artifacts/index.js

@@ -0,0 +1 @@
+export * from "./artifacts.js";

package/output/source/helpers/catch/catch.js

@@ -0,0 +1,48 @@
+// 辅助函数：检查是否为 PromiseLike
+function isPromiseLike(value) {
+    return value != null && typeof value === 'object' && 'then' in value && typeof value.then === 'function';
+}
+/**
+ * 构造成功结果对象
+ * isError 始终返回 false
+ */
+function createSuccess(value) {
+    return {
+        value,
+        error: undefined,
+        isError() { return false; }
+    };
+}
+/**
+ * 构造失败结果对象
+ * isError 始终返回 true
+ */
+function createFailure(error) {
+    return {
+        error,
+        value: undefined,
+        isError() { return true; }
+    };
+}
+export async function catchIt(input) {
+    try {
+        if (isPromiseLike(input)) {
+            const result = await Promise.resolve(input);
+            return createSuccess(result);
+        }
+        else if (typeof input === 'function') {
+            const result = input();
+            if (isPromiseLike(result)) {
+                return catchIt(result);
+            }
+            else {
+                return createSuccess(result);
+            }
+        }
+    }
+    catch (error) {
+        return createFailure(error);
+    }
+    // 理论上不会到达这里，兜底类型安全
+    return createFailure(new Error('Unexpected input type'));
+}

package/output/source/helpers/catch/catch.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { catchIt } from './catch.js';
+describe('catchIt', () => {
+    it('同步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+        const result = await catchIt(() => 123);
+        expect(result.value).toBe(123);
+        expect(result.error).toBeUndefined();
+        expect(result.isError()).toBe(false);
+    });
+    it('异步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+        const result = await catchIt(async () => 456);
+        expect(result.value).toBe(456);
+        expect(result.error).toBeUndefined();
+        expect(result.isError()).toBe(false);
+    });
+    it('同步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+        const error = new Error('fail');
+        const result = await catchIt(() => { throw error; });
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
+    });
+    it('异步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+        const error = new Error('fail-async');
+        const result = await catchIt(() => Promise.reject(error));
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
+    });
+    it('PromiseLike resolve 时应返回 value，error 为 undefined，isError 为 false', async () => {
+        const result = await catchIt(Promise.resolve('ok'));
+        expect(result.value).toBe('ok');
+        expect(result.error).toBeUndefined();
+        expect(result.isError()).toBe(false);
+    });
+    it('PromiseLike reject 时应返回 error，value 为 undefined，isError 为 true', async () => {
+        const error = new Error('promise-fail');
+        const result = await catchIt(Promise.reject(error));
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
+    });
+});

package/output/source/helpers/catch/index.js

@@ -0,0 +1 @@
+export * from './catch.js';

package/output/source/helpers/files/files.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { catchIt } from "../catch/index.js";
+const FILE_ARTIFACTS = ["README.md", "roadmap.md", "tasks.md"];
+const DIRECTORY_ARTIFACTS = ["designs", "reports", "hooks"];
+async function fileLineCount(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    if (!content) {
+        return 0;
+    }
+    return content.split(/\r?\n/).length;
+}
+async function listMarkdownFiles(dirPath) {
+    const entriesResult = await catchIt(fs.readdir(dirPath, { withFileTypes: true }));
+    if (entriesResult.isError()) {
+        return [];
+    }
+    const entries = entriesResult.value;
+    const files = entries.filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"));
+    const result = [];
+    for (const file of files) {
+        const fullPath = path.join(dirPath, file.name);
+        result.push({ path: fullPath, lineCount: await fileLineCount(fullPath) });
+    }
+    return result.sort((a, b) => a.path.localeCompare(b.path));
+}
+export async function discoverGovernanceArtifacts(governanceDir) {
+    const result = [];
+    for (const artifact of FILE_ARTIFACTS) {
+        const artifactPath = path.join(governanceDir, artifact);
+        const accessResult = await catchIt(fs.access(artifactPath));
+        if (!accessResult.isError()) {
+            result.push({
+                name: artifact,
+                kind: "file",
+                path: artifactPath,
+                exists: true,
+                lineCount: await fileLineCount(artifactPath),
+            });
+        }
+        else {
+            result.push({ name: artifact, kind: "file", path: artifactPath, exists: false });
+        }
+    }
+    for (const artifact of DIRECTORY_ARTIFACTS) {
+        const artifactPath = path.join(governanceDir, artifact);
+        const accessResult = await catchIt(fs.access(artifactPath));
+        if (!accessResult.isError()) {
+            result.push({
+                name: artifact,
+                kind: "directory",
+                path: artifactPath,
+                exists: true,
+                markdownFiles: await listMarkdownFiles(artifactPath),
+            });
+        }
+        else {
+            result.push({ name: artifact, kind: "directory", path: artifactPath, exists: false, markdownFiles: [] });
+        }
+    }
+    return result;
+}

package/output/source/helpers/files/files.test.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { discoverGovernanceArtifacts } from "./files.js";
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map(async (dir) => {
+        await fs.rm(dir, { recursive: true, force: true });
+    }));
+});
+describe("files module", () => {
+    it("discovers governance artifacts with paths and line counts", async () => {
+        const root = await createTempDir();
+        await fs.writeFile(path.join(root, "README.md"), "# Readme\n", "utf-8");
+        await fs.writeFile(path.join(root, "tasks.md"), "# Tasks\n## TODO\n", "utf-8");
+        await fs.mkdir(path.join(root, "designs"), { recursive: true });
+        await fs.writeFile(path.join(root, "designs", "feature-design.md"), "# Design\n", "utf-8");
+        const artifacts = await discoverGovernanceArtifacts(root);
+        const readme = artifacts.find((item) => item.name === "README.md");
+        const designs = artifacts.find((item) => item.name === "designs");
+        expect(readme?.exists).toBe(true);
+        expect(readme?.lineCount).toBe(2);
+        expect(designs?.exists).toBe(true);
+        expect(designs?.markdownFiles?.[0].path.endsWith("feature-design.md")).toBe(true);
+    });
+});

package/output/source/helpers/files/index.js

@@ -0,0 +1 @@
+export * from './files.js';

package/output/source/helpers/index.js

@@ -0,0 +1,6 @@
+export * from './artifacts/index.js';
+export * from './catch/index.js';
+export * from './files/index.js';
+export * from './linter/index.js';
+export * from './markdown/index.js';
+export * from './response/index.js';

package/output/source/helpers/linter/codes.js

@@ -0,0 +1,25 @@
+export const TASK_LINT_CODES = {
+    DUPLICATE_ID: "TASK_DUPLICATE_ID",
+    IN_PROGRESS_OWNER_EMPTY: "TASK_IN_PROGRESS_OWNER_EMPTY",
+    DONE_LINKS_MISSING: "TASK_DONE_LINKS_MISSING",
+    BLOCKED_SUMMARY_EMPTY: "TASK_BLOCKED_SUMMARY_EMPTY",
+    UPDATED_AT_INVALID: "TASK_UPDATED_AT_INVALID",
+    ROADMAP_REFS_EMPTY: "TASK_ROADMAP_REFS_EMPTY",
+    OUTSIDE_MARKER: "TASK_OUTSIDE_MARKER",
+    LINK_TARGET_MISSING: "TASK_LINK_TARGET_MISSING",
+    HOOK_FILE_MISSING: "TASK_HOOK_FILE_MISSING",
+    FILTER_EMPTY: "TASK_FILTER_EMPTY",
+    CONTEXT_HOOK_HEAD_MISSING: "TASK_CONTEXT_HOOK_HEAD_MISSING",
+    CONTEXT_HOOK_FOOTER_MISSING: "TASK_CONTEXT_HOOK_FOOTER_MISSING",
+};
+export const ROADMAP_LINT_CODES = {
+    IDS_EMPTY: "ROADMAP_IDS_EMPTY",
+    TASKS_EMPTY: "ROADMAP_TASKS_EMPTY",
+    TASK_REFS_EMPTY: "ROADMAP_TASK_REFS_EMPTY",
+    UNKNOWN_REFS: "ROADMAP_UNKNOWN_REFS",
+    ZERO_LINKED_TASKS: "ROADMAP_ZERO_LINKED_TASKS",
+    CONTEXT_RELATED_TASKS_EMPTY: "ROADMAP_CONTEXT_RELATED_TASKS_EMPTY",
+};
+export const PROJECT_LINT_CODES = {
+    TASKS_FILE_MISSING: "PROJECT_TASKS_FILE_MISSING",
+};

package/output/source/helpers/linter/index.js

@@ -0,0 +1,2 @@
+export * from './linter.js';
+export * from './codes.js';

package/output/source/helpers/linter/linter.js

@@ -0,0 +1,6 @@
+export function renderLintSuggestions(suggestions) {
+    return suggestions.map((item) => {
+        const suffix = item.fixHint ? ` ${item.fixHint}` : "";
+        return `- [${item.code}] ${item.message}${suffix}`;
+    });
+}

package/output/source/helpers/linter/linter.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { renderLintSuggestions } from "./linter.js";
+describe("renderLintSuggestions", () => {
+    it("renders lint lines with code and message", () => {
+        const lines = renderLintSuggestions([
+            { code: "TASK_001", message: "Example lint" },
+        ]);
+        expect(lines).toEqual(["- [TASK_001] Example lint"]);
+    });
+    it("appends fixHint when provided", () => {
+        const lines = renderLintSuggestions([
+            { code: "TASK_002", message: "Missing field.", fixHint: "Set owner." },
+        ]);
+        expect(lines).toEqual(["- [TASK_002] Missing field. Set owner."]);
+    });
+});

package/output/source/helpers/markdown/index.js

@@ -0,0 +1 @@
+export * from './markdown.js';