@projitive/mcp 1.0.1 → 1.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.1**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.2**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 

package/output/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/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/helpers/artifacts/index.js

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

package/output/helpers/index.js

@@ -1,3 +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/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/helpers/linter/index.js

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

package/output/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/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/helpers/response/index.js

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

package/output/helpers/response/response.js

@@ -0,0 +1,73 @@
+export function asText(markdown) {
+    return {
+        content: [{ type: "text", text: markdown }],
+    };
+}
+function withFallback(lines) {
+    return lines.length > 0 ? lines : ["- (none)"];
+}
+function shouldKeepRawLine(trimmed) {
+    if (trimmed.length === 0) {
+        return true;
+    }
+    if (trimmed.startsWith("#") || trimmed.startsWith(">") || trimmed.startsWith("```")) {
+        return true;
+    }
+    if (/^[-*+]\s/.test(trimmed)) {
+        return true;
+    }
+    if (/^\d+\.\s/.test(trimmed)) {
+        return true;
+    }
+    return false;
+}
+function normalizeLine(line) {
+    const trimmed = line.trim();
+    if (shouldKeepRawLine(trimmed)) {
+        return line;
+    }
+    return `- ${trimmed}`;
+}
+function normalizeLines(lines) {
+    return lines.map((line) => normalizeLine(line));
+}
+export function section(title, lines) {
+    return { title, lines: normalizeLines(lines) };
+}
+export function summarySection(lines) {
+    return section("Summary", lines);
+}
+export function evidenceSection(lines) {
+    return section("Evidence", lines);
+}
+export function guidanceSection(lines) {
+    return section("Agent Guidance", lines);
+}
+export function lintSection(lines) {
+    return section("Lint Suggestions", lines);
+}
+export function nextCallSection(nextCall) {
+    return section("Next Call", nextCall ? [nextCall] : []);
+}
+export function renderToolResponseMarkdown(payload) {
+    const body = payload.sections.flatMap((section) => [
+        `## ${section.title}`,
+        ...withFallback(section.lines),
+        "",
+    ]);
+    return [
+        `# ${payload.toolName}`,
+        "",
+        ...body,
+    ].join("\n").trimEnd();
+}
+export function renderErrorMarkdown(toolName, cause, nextSteps, retryExample) {
+    return renderToolResponseMarkdown({
+        toolName,
+        sections: [
+            section("Error", [`cause: ${cause}`]),
+            section("Next Step", nextSteps),
+            section("Retry Example", [retryExample ?? "(none)"]),
+        ],
+    });
+}

package/output/helpers/response/response.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { asText, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./response.js";
+describe("response helpers", () => {
+    it("wraps markdown text as MCP text content", () => {
+        const result = asText("# hello");
+        expect(result.content).toEqual([{ type: "text", text: "# hello" }]);
+    });
+    it("renders error markdown sections", () => {
+        const markdown = renderErrorMarkdown("taskContext", "bad id", ["retry"], "taskContext(...)");
+        expect(markdown).toContain("# taskContext");
+        expect(markdown).toContain("## Error");
+        expect(markdown).toContain("- cause: bad id");
+        expect(markdown).toContain("- retry");
+        expect(markdown).toContain("## Retry Example");
+    });
+    it("renders standard tool response sections with fallback", () => {
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                { title: "Summary", lines: ["- governanceDir: /tmp/.projitive"] },
+                { title: "Evidence", lines: [] },
+            ],
+        });
+        expect(markdown).toContain("# taskList");
+        expect(markdown).toContain("## Summary");
+        expect(markdown).toContain("## Evidence");
+        expect(markdown).toContain("- (none)");
+    });
+    it("auto-prefixes plain lines in section helpers", () => {
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                summarySection(["governanceDir: /tmp/.projitive"]),
+            ],
+        });
+        expect(markdown).toContain("- governanceDir: /tmp/.projitive");
+    });
+    it("nextCallSection accepts optional call and falls back when missing", () => {
+        const withCall = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [nextCallSection("taskContext(projectPath=\"/tmp\", taskId=\"TASK-0001\")")],
+        });
+        expect(withCall).toContain("- taskContext(projectPath=\"/tmp\", taskId=\"TASK-0001\")");
+        const withoutCall = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [nextCallSection(undefined)],
+        });
+        expect(withoutCall).toContain("- (none)");
+    });
+});

package/output/projitive.js

@@ -4,17 +4,14 @@ import process from "node:process";
 import { z } from "zod";
 import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
 import { catchIt } from "./helpers/catch/index.js";
-import { loadTasks } from "./tasks.js";
+import { PROJECT_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
+import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
+import { collectTaskLintSuggestions, loadTasksDocument } from "./tasks.js";
 export const PROJECT_MARKER = ".projitive";
 const DEFAULT_GOVERNANCE_DIR = ".projitive";
 const ignoreNames = new Set(["node_modules", ".git", ".next", "dist", "build"]);
 const DEFAULT_SCAN_DEPTH = 3;
 const MAX_SCAN_DEPTH = 8;
-function asText(markdown) {
-    return {
-        content: [{ type: "text", text: markdown }],
-    };
-}
 function normalizePath(inputPath) {
     return inputPath ? path.resolve(inputPath) : process.cwd();
 }
@@ -71,11 +68,22 @@ async function readTasksSnapshot(governanceDir) {
     const tasksPath = path.join(governanceDir, "tasks.md");
     const markdown = await fs.readFile(tasksPath, "utf-8").catch(() => undefined);
     if (typeof markdown !== "string") {
-        return { tasksPath, exists: false, tasks: [] };
+        return {
+            tasksPath,
+            exists: false,
+            tasks: [],
+            lintSuggestions: renderLintSuggestions([
+                {
+                    code: PROJECT_LINT_CODES.TASKS_FILE_MISSING,
+                    message: "tasks.md is missing.",
+                    fixHint: "Initialize governance tasks structure first.",
+                },
+            ]),
+        };
     }
     const { parseTasksBlock } = await import("./tasks.js");
     const tasks = await parseTasksBlock(markdown);
-    return { tasksPath, exists: true, tasks };
+    return { tasksPath, exists: true, tasks, lintSuggestions: collectTaskLintSuggestions(tasks, markdown) };
 }
 function latestTaskUpdatedAt(tasks) {
     const timestamps = tasks
@@ -248,31 +256,35 @@ export function registerProjectTools(server) {
             updated: initialized.files.filter((item) => item.action === "updated"),
             skipped: initialized.files.filter((item) => item.action === "skipped"),
         };
-        const markdown = [
-            "# projectInit",
-            "",
-            "## Summary",
-            `- rootPath: ${initialized.rootPath}`,
-            `- governanceDir: ${initialized.governanceDir}`,
-            `- markerPath: ${initialized.markerPath}`,
-            `- force: ${force === true ? "true" : "false"}`,
-            "",
-            "## Evidence",
-            `- createdFiles: ${filesByAction.created.length}`,
-            `- updatedFiles: ${filesByAction.updated.length}`,
-            `- skippedFiles: ${filesByAction.skipped.length}`,
-            "- directories:",
-            ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
-            "- files:",
-            ...initialized.files.map((item) => `  - ${item.action}: ${item.path}`),
-            "",
-            "## Agent Guidance",
-            "- If files were skipped and you want to overwrite templates, rerun with force=true.",
-            "- Continue with projectContext and taskList for execution.",
-            "",
-            "## Next Call",
-            `- projectContext(projectPath=\"${initialized.governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectInit",
+            sections: [
+                summarySection([
+                    `- rootPath: ${initialized.rootPath}`,
+                    `- governanceDir: ${initialized.governanceDir}`,
+                    `- markerPath: ${initialized.markerPath}`,
+                    `- force: ${force === true ? "true" : "false"}`,
+                ]),
+                evidenceSection([
+                    `- createdFiles: ${filesByAction.created.length}`,
+                    `- updatedFiles: ${filesByAction.updated.length}`,
+                    `- skippedFiles: ${filesByAction.skipped.length}`,
+                    "- directories:",
+                    ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
+                    "- files:",
+                    ...initialized.files.map((item) => `  - ${item.action}: ${item.path}`),
+                ]),
+                guidanceSection([
+                    "- If files were skipped and you want to overwrite templates, rerun with force=true.",
+                    "- Continue with projectContext and taskList for execution.",
+                ]),
+                lintSection([
+                    "- 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}\")`),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectScan", {
@@ -286,27 +298,30 @@ export function registerProjectTools(server) {
         const root = resolveScanRoot(rootPath);
         const depth = resolveScanDepth(maxDepth);
         const projects = await discoverProjects(root, depth);
-        const markdown = [
-            "# projectScan",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- discoveredCount: ${projects.length}`,
-            "",
-            "## Evidence",
-            "- projects:",
-            ...(projects.length > 0 ? projects.map((project, index) => `${index + 1}. ${project}`) : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Use one discovered project path and call `projectLocate` to lock governance root.",
-            "- Then call `projectContext` to inspect current governance state.",
-            "",
-            "## Next Call",
-            ...(projects.length > 0
-                ? [`- projectLocate(inputPath=\"${projects[0]}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectScan",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- maxDepth: ${depth}`,
+                    `- discoveredCount: ${projects.length}`,
+                ]),
+                evidenceSection([
+                    "- projects:",
+                    ...projects.map((project, index) => `${index + 1}. ${project}`),
+                ]),
+                guidanceSection([
+                    "- Use one discovered project path and call `projectLocate` to lock governance root.",
+                    "- Then call `projectContext` to inspect current governance state.",
+                ]),
+                lintSection(projects.length === 0
+                    ? ["- No governance root discovered. Add `.projitive` marker and baseline artifacts before execution."]
+                    : ["- Run `projectContext` on a discovered project to receive module-level lint suggestions."]),
+                nextCallSection(projects[0]
+                    ? `projectLocate(inputPath=\"${projects[0]}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectNext", {
@@ -332,7 +347,7 @@ export function registerProjectTools(server) {
                 governanceDir,
                 tasksPath: snapshot.tasksPath,
                 tasksExists: snapshot.exists,
-                total: snapshot.tasks.length,
+                lintSuggestions: snapshot.lintSuggestions,
                 inProgress,
                 todo,
                 blocked,
@@ -351,32 +366,31 @@ export function registerProjectTools(server) {
             return b.latestUpdatedAt.localeCompare(a.latestUpdatedAt);
         })
             .slice(0, limit ?? 10);
-        const markdown = [
-            "# projectNext",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- matchedProjects: ${projects.length}`,
-            `- actionableProjects: ${ranked.length}`,
-            `- limit: ${limit ?? 10}`,
-            "",
-            "## Evidence",
-            "- rankedProjects:",
-            ...(ranked.length > 0
-                ? 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)"}`)
-                : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Pick top 1 project and call `projectContext` with its governanceDir.",
-            "- Then call `taskList` and `taskContext` to continue execution.",
-            "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
-            "",
-            "## Next Call",
-            ...(ranked.length > 0
-                ? [`- projectContext(projectPath=\"${ranked[0].governanceDir}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectNext",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- maxDepth: ${depth}`,
+                    `- matchedProjects: ${projects.length}`,
+                    `- actionableProjects: ${ranked.length}`,
+                    `- limit: ${limit ?? 10}`,
+                ]),
+                evidenceSection([
+                    "- rankedProjects:",
+                    ...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.",
+                    "- 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}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectLocate", {
@@ -389,20 +403,19 @@ export function registerProjectTools(server) {
         const resolvedFrom = normalizePath(inputPath);
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
         const markerPath = path.join(governanceDir, ".projitive");
-        const markdown = [
-            "# projectLocate",
-            "",
-            "## Summary",
-            `- resolvedFrom: ${resolvedFrom}`,
-            `- governanceDir: ${governanceDir}`,
-            `- markerPath: ${markerPath}`,
-            "",
-            "## Agent Guidance",
-            "- Call `projectContext` with this governanceDir to get task and roadmap summaries.",
-            "",
-            "## Next Call",
-            `- projectContext(projectPath=\"${governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectLocate",
+            sections: [
+                summarySection([
+                    `- resolvedFrom: ${resolvedFrom}`,
+                    `- governanceDir: ${governanceDir}`,
+                    `- markerPath: ${markerPath}`,
+                ]),
+                guidanceSection(["- Call `projectContext` with this governanceDir to get task and roadmap summaries."]),
+                lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
+                nextCallSection(`projectContext(projectPath=\"${governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectContext", {
@@ -414,8 +427,9 @@ export function registerProjectTools(server) {
     }, async ({ projectPath }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
-        const { tasksPath, tasks } = await loadTasks(governanceDir);
+        const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
         const roadmapIds = await readRoadmapIds(governanceDir);
+        const lintSuggestions = collectTaskLintSuggestions(tasks, tasksMarkdown);
         const taskSummary = {
             total: tasks.length,
             TODO: tasks.filter((task) => task.status === "TODO").length,
@@ -423,32 +437,33 @@ export function registerProjectTools(server) {
             BLOCKED: tasks.filter((task) => task.status === "BLOCKED").length,
             DONE: tasks.filter((task) => task.status === "DONE").length,
         };
-        const markdown = [
-            "# projectContext",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- tasksFile: ${tasksPath}`,
-            `- roadmapIds: ${roadmapIds.length}`,
-            "",
-            "## Evidence",
-            "### Task Summary",
-            `- total: ${taskSummary.total}`,
-            `- TODO: ${taskSummary.TODO}`,
-            `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
-            `- BLOCKED: ${taskSummary.BLOCKED}`,
-            `- DONE: ${taskSummary.DONE}`,
-            "",
-            "### Artifacts",
-            renderArtifactsMarkdown(artifacts),
-            "",
-            "## Agent Guidance",
-            "- Start from `taskList` to choose a target task.",
-            "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
-            "",
-            "## Next Call",
-            `- taskList(projectPath=\"${governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectContext",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- tasksFile: ${tasksPath}`,
+                    `- roadmapIds: ${roadmapIds.length}`,
+                ]),
+                evidenceSection([
+                    "### Task Summary",
+                    `- total: ${taskSummary.total}`,
+                    `- TODO: ${taskSummary.TODO}`,
+                    `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
+                    `- BLOCKED: ${taskSummary.BLOCKED}`,
+                    `- DONE: ${taskSummary.DONE}`,
+                    "",
+                    "### Artifacts",
+                    renderArtifactsMarkdown(artifacts),
+                ]),
+                guidanceSection([
+                    "- Start from `taskList` to choose a target task.",
+                    "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
+                ]),
+                lintSection(lintSuggestions),
+                nextCallSection(`taskList(projectPath=\"${governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
 }

package/output/rendering-input-guard.test.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+const MODULE_FILES = [
+    "tasks.ts",
+    "roadmap.ts",
+    "projitive.ts",
+];
+const INVALID_LITERAL_PATTERN = /["'`]\s*-\s+(#{1,6}\s|>\s*|```)/g;
+describe("rendering input guard", () => {
+    it("does not contain accidental bullet-prefixed markdown literals in module outputs", async () => {
+        const sourceDir = path.resolve(import.meta.dirname);
+        for (const file of MODULE_FILES) {
+            const filePath = path.join(sourceDir, file);
+            const content = await fs.readFile(filePath, "utf-8");
+            const matches = content.match(INVALID_LITERAL_PATTERN) ?? [];
+            expect(matches, `invalid literals in ${filePath}`).toHaveLength(0);
+        }
+    });
+});