@projitive/mcp 2.1.1 → 2.1.3

package/output/source/tools/project.js

@@ -1,14 +1,16 @@
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { z } from 'zod';
-import { discoverGovernanceArtifacts, catchIt, PROJECT_LINT_CODES, renderLintSuggestions, ensureStore, replaceRoadmapsInStore, replaceTasksInStore, loadTaskStatusStatsFromStore, createGovernedTool, getDefaultToolTemplateMarkdown, } from '../common/index.js';
-import { collectTaskLintSuggestions, loadTasksDocument, loadTasksDocumentWithOptions, renderTasksMarkdown } from './task.js';
+import { candidateFilesFromArtifacts, discoverGovernanceArtifacts, catchIt, PROJECT_LINT_CODES, renderLintSuggestions, ensureStore, loadRoadmapsFromStore, loadTasksFromStore, replaceRoadmapsInStore, replaceTasksInStore, loadTaskStatusStatsFromStore, upsertRoadmapInStore, upsertTaskInStore, createGovernedTool, getDefaultToolTemplateMarkdown, } from '../common/index.js';
+import { collectProjectContextDocsLintSuggestions, collectTaskLintSuggestions, CORE_ARCHITECTURE_DOC_FILE, CORE_CODE_STYLE_DOC_FILE, CORE_UI_STYLE_DOC_FILE, inspectProjectContextDocsFromArtifacts, loadTasksDocument, loadTasksDocumentWithOptions, renderTasksMarkdown, } from './task.js';
 import { loadRoadmapDocumentWithOptions, renderRoadmapMarkdown } from './roadmap.js';
 export const PROJECT_MARKER = '.projitive';
 const DEFAULT_GOVERNANCE_DIR = '.projitive';
 const ignoreNames = new Set(['node_modules', '.git', '.next', 'dist', 'build']);
 const MAX_SCAN_DEPTH = 8;
+const DEFAULT_SCAN_DEPTH = 3;
 function normalizePath(inputPath) {
     return inputPath ? path.resolve(inputPath) : process.cwd();
 }
@@ -32,13 +34,6 @@ function parseDepthFromEnv(rawDepth) {
     }
     return Math.min(MAX_SCAN_DEPTH, Math.max(0, parsed));
 }
-function requireEnvVar(name) {
-    const value = process.env[name];
-    if (typeof value !== 'string' || value.trim().length === 0) {
-        throw new Error(`Missing required environment variable: ${name}`);
-    }
-    return value.trim();
-}
 function normalizeScanRoots(rootPaths) {
     const normalized = rootPaths
         .map((entry) => entry.trim())
@@ -72,21 +67,24 @@ export function resolveScanRoots(inputPaths) {
     if (rootsFromLegacyEnv.length > 0) {
         return rootsFromLegacyEnv;
     }
-    throw new Error('Missing required environment variable: PROJITIVE_SCAN_ROOT_PATHS (or legacy PROJITIVE_SCAN_ROOT_PATH)');
+    return [os.homedir()];
 }
 export function resolveScanRoot(inputPath) {
     return resolveScanRoots(inputPath ? [inputPath] : undefined)[0];
 }
 export function resolveScanDepth(inputDepth) {
-    const configuredDepthRaw = requireEnvVar('PROJITIVE_SCAN_MAX_DEPTH');
-    const configuredDepth = parseDepthFromEnv(configuredDepthRaw);
-    if (typeof configuredDepth !== 'number') {
-        throw new Error('Invalid PROJITIVE_SCAN_MAX_DEPTH: expected integer in range 0-8');
-    }
     if (typeof inputDepth === 'number') {
         return inputDepth;
     }
-    return configuredDepth;
+    const configuredDepthRaw = process.env.PROJITIVE_SCAN_MAX_DEPTH;
+    if (typeof configuredDepthRaw === 'string' && configuredDepthRaw.trim().length > 0) {
+        const configuredDepth = parseDepthFromEnv(configuredDepthRaw);
+        if (typeof configuredDepth !== 'number') {
+            throw new Error('Invalid PROJITIVE_SCAN_MAX_DEPTH: expected integer in range 0-8');
+        }
+        return configuredDepth;
+    }
+    return DEFAULT_SCAN_DEPTH;
 }
 function renderArtifactsMarkdown(artifacts) {
     const rows = artifacts.map((item) => {
@@ -272,34 +270,261 @@ function defaultReadmeMarkdown(governanceDirName) {
         '- Treat roadmap.md/tasks.md as generated views from governance store.',
         '- Keep IDs stable (TASK-xxxx / ROADMAP-xxxx).',
         '- Update report evidence before status transitions.',
+        '- Maintain core docs under designs/core/: architecture.md, code-style.md, ui-style.md.',
+        '- After each task completion, review whether architecture, code conventions, or UI rules changed and update the matching core docs.',
     ].join('\n');
 }
 function defaultRoadmapMarkdown(milestones = defaultRoadmapMilestones()) {
     return renderRoadmapMarkdown(milestones);
 }
 function defaultTasksMarkdown(updatedAt = new Date().toISOString()) {
-    return renderTasksMarkdown([
+    return renderTasksMarkdown(defaultBootstrapTasks(updatedAt));
+}
+function defaultBootstrapTaskBlueprints() {
+    return [
         {
-            id: 'TASK-0001',
-            title: 'Bootstrap governance workspace',
-            status: 'TODO',
-            owner: 'unassigned',
-            summary: 'Create initial governance artifacts and confirm task execution loop.',
-            updatedAt,
-            links: [],
-            roadmapRefs: ['ROADMAP-0001'],
+            title: 'Initialize project architecture document',
+            summary: `Establish system context, boundaries, modules, and integration flows in ${CORE_ARCHITECTURE_DOC_FILE}.`,
+            links: [CORE_ARCHITECTURE_DOC_FILE],
         },
-    ]);
+        {
+            title: 'Initialize code style document',
+            summary: `Capture naming, structure, testing, and review conventions in ${CORE_CODE_STYLE_DOC_FILE}.`,
+            links: [CORE_CODE_STYLE_DOC_FILE],
+        },
+        {
+            title: 'Initialize UI style document',
+            summary: `Capture visual language, tokens, accessibility, and interaction rules in ${CORE_UI_STYLE_DOC_FILE}.`,
+            links: [CORE_UI_STYLE_DOC_FILE],
+        },
+    ];
 }
 function defaultRoadmapMilestones() {
     return [{
             id: 'ROADMAP-0001',
-            title: 'Bootstrap governance baseline',
+            title: 'Bootstrap governance and core docs baseline',
             status: 'active',
             time: '2026-Q1',
             updatedAt: new Date().toISOString(),
         }];
 }
+function defaultBootstrapTasks(updatedAt = new Date().toISOString()) {
+    return defaultBootstrapTaskBlueprints().map((blueprint, index) => ({
+        id: `TASK-${String(index + 1).padStart(4, '0')}`,
+        title: blueprint.title,
+        status: 'TODO',
+        owner: 'unassigned',
+        summary: blueprint.summary,
+        updatedAt,
+        links: blueprint.links,
+        roadmapRefs: ['ROADMAP-0001'],
+    }));
+}
+function nextGeneratedTaskId(taskIds) {
+    const maxSuffix = taskIds
+        .map((taskId) => /^TASK-(\d+)$/.exec(taskId)?.[1])
+        .map((value) => Number.parseInt(value ?? '-1', 10))
+        .filter((value) => Number.isFinite(value) && value > 0)
+        .reduce((max, value) => Math.max(max, value), 0);
+    const next = maxSuffix + 1;
+    return `TASK-${String(next).padStart(Math.max(4, String(next).length), '0')}`;
+}
+function buildBackfillTask(blueprint, taskId, roadmapRef) {
+    return {
+        id: taskId,
+        title: blueprint.title,
+        status: 'TODO',
+        owner: 'unassigned',
+        summary: blueprint.summary,
+        updatedAt: new Date().toISOString(),
+        links: blueprint.links,
+        roadmapRefs: [roadmapRef],
+    };
+}
+async function inspectProjectInitMissingState(governancePath) {
+    const requiredDirectories = [
+        governancePath,
+        path.join(governancePath, 'designs'),
+        path.join(governancePath, 'designs', 'core'),
+        path.join(governancePath, 'designs', 'research'),
+        path.join(governancePath, 'reports'),
+        path.join(governancePath, 'templates'),
+        path.join(governancePath, 'templates', 'tools'),
+    ];
+    const requiredFiles = [
+        path.join(governancePath, 'README.md'),
+        path.join(governancePath, 'roadmap.md'),
+        path.join(governancePath, 'tasks.md'),
+        path.join(governancePath, CORE_ARCHITECTURE_DOC_FILE),
+        path.join(governancePath, CORE_CODE_STYLE_DOC_FILE),
+        path.join(governancePath, CORE_UI_STYLE_DOC_FILE),
+        path.join(governancePath, 'templates', 'README.md'),
+        ...DEFAULT_TOOL_TEMPLATE_NAMES.map((toolName) => path.join(governancePath, 'templates', 'tools', `${toolName}.md`)),
+    ];
+    const missingDirectories = (await Promise.all(requiredDirectories.map(async (dirPath) => (await pathExists(dirPath)) ? undefined : dirPath)))
+        .filter((item) => item != null);
+    const missingFiles = (await Promise.all(requiredFiles.map(async (filePath) => (await pathExists(filePath)) ? undefined : filePath)))
+        .filter((item) => item != null);
+    const markerPath = path.join(governancePath, PROJECT_MARKER);
+    const markerMissing = !(await pathExists(markerPath));
+    if (markerMissing) {
+        return {
+            markerMissing,
+            missingDirectories,
+            missingFiles,
+            missingBootstrapTaskTitles: defaultBootstrapTaskBlueprints().map((item) => item.title),
+            missingBootstrapRoadmap: true,
+        };
+    }
+    await ensureStore(markerPath);
+    const [tasks, roadmaps] = await Promise.all([
+        loadTasksFromStore(markerPath),
+        loadRoadmapsFromStore(markerPath),
+    ]);
+    const missingBootstrapTaskTitles = defaultBootstrapTaskBlueprints()
+        .filter((blueprint) => !tasks.some((task) => task.title === blueprint.title || blueprint.links.some((link) => task.links.includes(link))))
+        .map((item) => item.title);
+    return {
+        markerMissing,
+        missingDirectories,
+        missingFiles,
+        missingBootstrapTaskTitles,
+        missingBootstrapRoadmap: roadmaps.length === 0,
+    };
+}
+async function backfillBootstrapTasks(markerPath) {
+    await ensureStore(markerPath);
+    const [tasks, roadmaps] = await Promise.all([
+        loadTasksFromStore(markerPath),
+        loadRoadmapsFromStore(markerPath),
+    ]);
+    let createdBootstrapRoadmapId;
+    let roadmapRef = roadmaps[0]?.id;
+    if (!roadmapRef) {
+        const milestone = defaultRoadmapMilestones()[0];
+        await upsertRoadmapInStore(markerPath, milestone);
+        createdBootstrapRoadmapId = milestone.id;
+        roadmapRef = milestone.id;
+    }
+    const mutableTasks = [...tasks];
+    const createdBootstrapTaskIds = [];
+    for (const blueprint of defaultBootstrapTaskBlueprints()) {
+        const exists = mutableTasks.some((task) => task.title === blueprint.title || blueprint.links.some((link) => task.links.includes(link)));
+        if (exists) {
+            continue;
+        }
+        const nextTaskId = nextGeneratedTaskId(mutableTasks.map((task) => task.id));
+        const task = buildBackfillTask(blueprint, nextTaskId, roadmapRef);
+        await upsertTaskInStore(markerPath, task);
+        mutableTasks.push(task);
+        createdBootstrapTaskIds.push(nextTaskId);
+    }
+    return { createdBootstrapTaskIds, createdBootstrapRoadmapId };
+}
+function defaultProjectArchitectureMarkdown() {
+    return [
+        '# Project Architecture',
+        '',
+        '## Mission and Scope',
+        '- Describe the product or repository purpose.',
+        '- Define the operational boundary of this project.',
+        '',
+        '## System Boundaries',
+        '- List primary inputs, outputs, external integrations, and ownership boundaries.',
+        '',
+        '## Modules and Responsibilities',
+        '- Document the major modules, packages, or services and their responsibilities.',
+        '',
+        '## Key Flows',
+        '- Summarize the highest-value runtime and maintenance flows.',
+        '',
+        '## Change Triggers',
+        '- Update this document when tasks change architecture boundaries, data flow, or integration contracts.',
+    ].join('\n');
+}
+function defaultCodeStyleMarkdown() {
+    return [
+        '# Code Style',
+        '',
+        '## Core Principles',
+        '- Document the repository coding principles and non-negotiable constraints.',
+        '',
+        '## Naming and Structure',
+        '- Define naming rules, module boundaries, and file organization expectations.',
+        '',
+        '## Testing and Validation',
+        '- Record expectations for unit tests, integration tests, and verification commands.',
+        '',
+        '## Review Checklist',
+        '- List the code quality checks every completed task should re-evaluate.',
+        '',
+        '## Change Triggers',
+        '- Update this document when tasks establish or revise reusable engineering conventions.',
+    ].join('\n');
+}
+function defaultUiStyleMarkdown() {
+    return [
+        '# UI Style',
+        '',
+        '## Visual Language',
+        '- Describe the intended product tone, typography, spacing, and visual hierarchy.',
+        '',
+        '## Components and Patterns',
+        '- Record reusable UI patterns, interaction rules, and component expectations.',
+        '',
+        '## Accessibility and Quality',
+        '- Document accessibility expectations, responsiveness rules, and UX quality bars.',
+        '',
+        '## Design Tokens',
+        '- Capture colors, spacing, motion, and other token-level guidance if applicable.',
+        '',
+        '## Change Triggers',
+        '- Update this document when tasks change UI behavior, interaction rules, or visual consistency guidance.',
+    ].join('\n');
+}
+function toRelativeGovernancePath(governanceDir, targetPath) {
+    const relative = path.relative(governanceDir, targetPath).replace(/\\/g, '/');
+    return relative.length > 0 ? relative : '.';
+}
+function classifyProjectInitMissing(initialized) {
+    const coreDocFiles = new Set([
+        CORE_ARCHITECTURE_DOC_FILE,
+        CORE_CODE_STYLE_DOC_FILE,
+        CORE_UI_STYLE_DOC_FILE,
+    ]);
+    const relativeMissingFiles = initialized.missingBeforeInit.missingFiles
+        .map((item) => toRelativeGovernancePath(initialized.governanceDir, item));
+    const coreDocs = relativeMissingFiles.filter((item) => coreDocFiles.has(item));
+    const templates = relativeMissingFiles.filter((item) => item === 'templates/README.md' || item.startsWith('templates/tools/'));
+    const otherFiles = relativeMissingFiles.filter((item) => !coreDocFiles.has(item) && !(item === 'templates/README.md' || item.startsWith('templates/tools/')));
+    return {
+        coreDocs,
+        templates,
+        bootstrapTasks: initialized.missingBeforeInit.missingBootstrapTaskTitles,
+        otherFiles,
+    };
+}
+function renderProjectInitRepairSummary(initialized) {
+    const classified = classifyProjectInitMissing(initialized);
+    return [
+        '### Repair Summary (Missing Before Init)',
+        '- core docs:',
+        `  - count: ${classified.coreDocs.length}`,
+        ...(classified.coreDocs.length > 0 ? classified.coreDocs.map((item) => `  - ${item}`) : ['  - (none)']),
+        '- templates:',
+        `  - count: ${classified.templates.length}`,
+        ...(classified.templates.length > 0 ? classified.templates.map((item) => `  - ${item}`) : ['  - (none)']),
+        '- bootstrap tasks:',
+        `  - count: ${classified.bootstrapTasks.length}`,
+        ...(classified.bootstrapTasks.length > 0 ? classified.bootstrapTasks.map((item) => `  - ${item}`) : ['  - (none)']),
+        '- other required files:',
+        `  - count: ${classified.otherFiles.length}`,
+        ...(classified.otherFiles.length > 0 ? classified.otherFiles.map((item) => `  - ${item}`) : ['  - (none)']),
+        '- remediation actions:',
+        `  - created bootstrap tasks: ${initialized.remediation.createdBootstrapTaskIds.length}`,
+        `  - created bootstrap roadmap: ${initialized.remediation.createdBootstrapRoadmapId ?? '(none)'}`,
+    ];
+}
 function defaultTemplateReadmeMarkdown() {
     return [
         '# Template Guide',
@@ -335,10 +560,13 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
         throw new Error(`projectPath must be a directory: ${projectPath}`);
     }
     const governancePath = path.join(projectPath, governanceDirName);
+    const missingBeforeInit = await inspectProjectInitMissingState(governancePath);
     const directories = [];
     const requiredDirectories = [
         governancePath,
         path.join(governancePath, 'designs'),
+        path.join(governancePath, 'designs', 'core'),
+        path.join(governancePath, 'designs', 'research'),
         path.join(governancePath, 'reports'),
         path.join(governancePath, 'templates'),
         path.join(governancePath, 'templates', 'tools'),
@@ -353,25 +581,21 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
     const defaultTaskUpdatedAt = new Date().toISOString();
     const markerExists = await pathExists(markerPath);
     await ensureStore(markerPath);
+    let remediation = { createdBootstrapTaskIds: [] };
     if (force || !markerExists) {
         await replaceRoadmapsInStore(markerPath, defaultRoadmapData);
-        await replaceTasksInStore(markerPath, [
-            {
-                id: 'TASK-0001',
-                title: 'Bootstrap governance workspace',
-                status: 'TODO',
-                owner: 'unassigned',
-                summary: 'Create initial governance artifacts and confirm task execution loop.',
-                updatedAt: defaultTaskUpdatedAt,
-                links: [],
-                roadmapRefs: ['ROADMAP-0001'],
-            },
-        ]);
+        await replaceTasksInStore(markerPath, defaultBootstrapTasks(defaultTaskUpdatedAt));
+    }
+    else {
+        remediation = await backfillBootstrapTasks(markerPath);
     }
     const baseFiles = await Promise.all([
         writeTextFile(path.join(governancePath, 'README.md'), defaultReadmeMarkdown(governanceDirName), force),
         writeTextFile(path.join(governancePath, 'roadmap.md'), defaultRoadmapMarkdown(defaultRoadmapData), force),
         writeTextFile(path.join(governancePath, 'tasks.md'), defaultTasksMarkdown(defaultTaskUpdatedAt), force),
+        writeTextFile(path.join(governancePath, CORE_ARCHITECTURE_DOC_FILE), defaultProjectArchitectureMarkdown(), force),
+        writeTextFile(path.join(governancePath, CORE_CODE_STYLE_DOC_FILE), defaultCodeStyleMarkdown(), force),
+        writeTextFile(path.join(governancePath, CORE_UI_STYLE_DOC_FILE), defaultUiStyleMarkdown(), force),
         writeTextFile(path.join(governancePath, 'templates', 'README.md'), defaultTemplateReadmeMarkdown(), force),
     ]);
     const toolTemplateFiles = await Promise.all(DEFAULT_TOOL_TEMPLATE_NAMES.map((toolName) => writeTextFile(path.join(governancePath, 'templates', 'tools', `${toolName}.md`), getDefaultToolTemplateMarkdown(toolName), force)));
@@ -381,6 +605,8 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
         governanceDir: governancePath,
         directories,
         files,
+        missingBeforeInit,
+        remediation,
     };
 }
 export function registerProjectTools(server) {
@@ -411,17 +637,45 @@ export function registerProjectTools(server) {
             `- createdFiles: ${filesByAction.created.length}`,
             `- updatedFiles: ${filesByAction.updated.length}`,
             `- skippedFiles: ${filesByAction.skipped.length}`,
+            `- missingDirectoriesBeforeInit: ${initialized.missingBeforeInit.missingDirectories.length}`,
+            `- missingFilesBeforeInit: ${initialized.missingBeforeInit.missingFiles.length}`,
+            `- missingBootstrapTasksBeforeInit: ${initialized.missingBeforeInit.missingBootstrapTaskTitles.length}`,
+            `- missingBootstrapRoadmapBeforeInit: ${initialized.missingBeforeInit.missingBootstrapRoadmap ? 'true' : 'false'}`,
+            `- createdBootstrapTasks: ${initialized.remediation.createdBootstrapTaskIds.length}`,
+            `- createdBootstrapRoadmap: ${initialized.remediation.createdBootstrapRoadmapId ?? '(none)'}`,
             '- directories:',
             ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
             '- files:',
             ...initialized.files.map((item) => `  - ${item.action}: ${item.path}`),
+            ...(initialized.missingBeforeInit.missingDirectories.length > 0
+                ? ['- missingDirectoriesBeforeInit.list:', ...initialized.missingBeforeInit.missingDirectories.map((item) => `  - ${item}`)]
+                : []),
+            ...(initialized.missingBeforeInit.missingFiles.length > 0
+                ? ['- missingFilesBeforeInit.list:', ...initialized.missingBeforeInit.missingFiles.map((item) => `  - ${item}`)]
+                : []),
+            ...(initialized.missingBeforeInit.missingBootstrapTaskTitles.length > 0
+                ? ['- missingBootstrapTasksBeforeInit.list:', ...initialized.missingBeforeInit.missingBootstrapTaskTitles.map((item) => `  - ${item}`)]
+                : []),
+            ...(initialized.remediation.createdBootstrapTaskIds.length > 0
+                ? ['- createdBootstrapTaskIds.list:', ...initialized.remediation.createdBootstrapTaskIds.map((item) => `  - ${item}`)]
+                : []),
+            '',
+            ...renderProjectInitRepairSummary(initialized),
         ],
-        guidance: () => [
+        guidance: ({ initialized }) => [
+            ...(initialized.missingBeforeInit.markerMissing
+                ? ['- Governance root was missing before init. This call performed a full bootstrap.']
+                : ['- Governance root already existed. This call inspected the current initialization state and backfilled missing artifacts where possible.']),
+            ...(initialized.missingBeforeInit.missingFiles.length > 0 || initialized.missingBeforeInit.missingDirectories.length > 0 || initialized.missingBeforeInit.missingBootstrapTaskTitles.length > 0 || initialized.missingBeforeInit.missingBootstrapRoadmap
+                ? ['- This project was partially initialized. Review the created files and bootstrap tasks, then complete any placeholder content.']
+                : ['- No initialization gaps were detected. Use force=true only when you intentionally want to overwrite templates/files.']),
             '- If files were skipped and you want to overwrite templates, rerun with force=true.',
             '- Continue with projectContext and taskList for execution.',
+            '- Start with the three bootstrap TODO tasks for architecture, code style, and UI style docs.',
         ],
         suggestions: () => [
             '- After init, fill owner/roadmapRefs/links in .projitive task table before marking DONE.',
+            '- Keep designs/core/architecture.md, designs/core/code-style.md, and designs/core/ui-style.md in sync with completed work.',
             '- Keep task source-of-truth inside .projitive governance store.',
         ],
         nextCall: ({ initialized }) => `projectContext(projectPath="${initialized.projectPath}")`,
@@ -595,20 +849,24 @@ export function registerProjectTools(server) {
             const governanceDir = await resolveGovernanceDir(projectPath);
             const normalizedProjectPath = toProjectPath(governanceDir);
             const artifacts = await discoverGovernanceArtifacts(governanceDir);
+            const projectContextDocsState = inspectProjectContextDocsFromArtifacts(candidateFilesFromArtifacts(artifacts));
             const dbPath = path.join(governanceDir, PROJECT_MARKER);
             await ensureStore(dbPath);
             const taskStats = await loadTaskStatusStatsFromStore(dbPath);
             const { markdownPath: tasksMarkdownPath, tasks } = await loadTasksDocument(governanceDir);
             const { markdownPath: roadmapMarkdownPath, milestones } = await loadRoadmapDocumentWithOptions(governanceDir, false);
             const roadmapIds = milestones.map((item) => item.id);
-            return { normalizedProjectPath, governanceDir, tasksMarkdownPath, roadmapMarkdownPath, roadmapIds, taskStats, artifacts, tasks };
+            return { normalizedProjectPath, governanceDir, tasksMarkdownPath, roadmapMarkdownPath, roadmapIds, taskStats, artifacts, tasks, projectContextDocsState };
         },
-        summary: ({ normalizedProjectPath, governanceDir, tasksMarkdownPath, roadmapMarkdownPath, roadmapIds }) => [
+        summary: ({ normalizedProjectPath, governanceDir, tasksMarkdownPath, roadmapMarkdownPath, roadmapIds, projectContextDocsState }) => [
             `- projectPath: ${normalizedProjectPath}`,
             `- governanceDir: ${governanceDir}`,
             `- tasksView: ${tasksMarkdownPath}`,
             `- roadmapView: ${roadmapMarkdownPath}`,
             `- roadmapIds: ${roadmapIds.length}`,
+            `- projectArchitectureDocsStatus: ${projectContextDocsState.missingArchitectureDocs ? 'MISSING' : 'READY'}`,
+            `- codeStyleDocsStatus: ${projectContextDocsState.missingCodeStyleDocs ? 'MISSING' : 'READY'}`,
+            `- uiStyleDocsStatus: ${projectContextDocsState.missingUiStyleDocs ? 'MISSING' : 'READY'}`,
         ],
         evidence: ({ taskStats, artifacts }) => [
             '### Task Summary',
@@ -621,11 +879,24 @@ export function registerProjectTools(server) {
             '### Artifacts',
             renderArtifactsMarkdown(artifacts),
         ],
-        guidance: () => [
+        guidance: ({ normalizedProjectPath, projectContextDocsState }) => [
+            ...(!projectContextDocsState.ready
+                ? [
+                    '- Project-level governance gate is NOT satisfied because required core docs are missing.',
+                    `- Rerun projectInit to repair missing governance artifacts and bootstrap tasks: projectInit(projectPath="${normalizedProjectPath}")`,
+                    '- After projectInit backfills missing files/tasks, update any placeholder content in the created docs.',
+                ]
+                : []),
+            '- Governance state must be changed via tools; do not directly edit tasks.md/roadmap.md generated views.',
             '- Start from `taskList` to choose a target task.',
             '- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.',
         ],
-        suggestions: ({ tasks }) => collectTaskLintSuggestions(tasks),
-        nextCall: ({ normalizedProjectPath }) => `taskList(projectPath="${normalizedProjectPath}")`,
+        suggestions: ({ tasks, projectContextDocsState }) => [
+            ...collectTaskLintSuggestions(tasks),
+            ...renderLintSuggestions(collectProjectContextDocsLintSuggestions(projectContextDocsState)),
+        ],
+        nextCall: ({ normalizedProjectPath, projectContextDocsState }) => projectContextDocsState.ready
+            ? `taskList(projectPath="${normalizedProjectPath}")`
+            : `projectInit(projectPath="${normalizedProjectPath}")`,
     }));
 }

package/output/source/tools/project.test.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs/promises';
-import os from 'node:os';
+import os, { homedir } from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { discoverProjects, discoverProjectsAcrossRoots, hasProjectMarker, initializeProjectStructure, resolveGovernanceDir, resolveScanRoots, resolveScanRoot, resolveScanDepth, toProjectPath, registerProjectTools } from './project.js';
+import { loadTasksFromStore, replaceTasksInStore } from '../common/store.js';
 const tempPaths = [];
 async function createTempDir() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'projitive-mcp-test-'));
@@ -222,10 +223,15 @@ 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', 'designs', 'core', 'architecture.md'),
+                path.join(root, '.projitive', 'designs', 'core', 'code-style.md'),
+                path.join(root, '.projitive', 'designs', 'core', 'ui-style.md'),
                 path.join(root, '.projitive', 'templates', 'README.md'),
                 path.join(root, '.projitive', 'templates', 'tools', 'taskNext.md'),
                 path.join(root, '.projitive', 'templates', 'tools', 'taskUpdate.md'),
                 path.join(root, '.projitive', 'designs'),
+                path.join(root, '.projitive', 'designs', 'core'),
+                path.join(root, '.projitive', 'designs', 'research'),
                 path.join(root, '.projitive', 'reports'),
                 path.join(root, '.projitive', 'templates'),
                 path.join(root, '.projitive', 'templates', 'tools'),
@@ -278,6 +284,25 @@ describe('projitive module', () => {
             expect(readmeContent).toBe('custom-content');
             expect(initialized.files.find((item) => item.path === readmePath)?.action).toBe('skipped');
         });
+        it('backfills missing core docs and bootstrap tasks when rerunning projectInit on partial governance', async () => {
+            const root = await createTempDir();
+            const governanceDir = path.join(root, '.projitive');
+            await initializeProjectStructure(root);
+            await fs.rm(path.join(governanceDir, 'designs', 'core', 'ui-style.md'));
+            const dbPath = path.join(governanceDir, '.projitive');
+            const existingTasks = await loadTasksFromStore(dbPath);
+            const uiTask = existingTasks.find((task) => task.title === 'Initialize UI style document');
+            expect(uiTask).toBeTruthy();
+            const filteredTasks = existingTasks.filter((task) => task.title !== 'Initialize UI style document');
+            await replaceTasksInStore(dbPath, filteredTasks);
+            const initialized = await initializeProjectStructure(root);
+            expect(await fs.access(path.join(governanceDir, 'designs', 'core', 'ui-style.md')).then(() => true).catch(() => false)).toBe(true);
+            expect(initialized.missingBeforeInit.missingFiles.some((item) => item.endsWith('designs/core/ui-style.md'))).toBe(true);
+            expect(initialized.missingBeforeInit.missingBootstrapTaskTitles).toContain('Initialize UI style document');
+            expect(initialized.remediation.createdBootstrapTaskIds).toHaveLength(1);
+            const reloadedTasks = await loadTasksFromStore(dbPath);
+            expect(reloadedTasks.some((task) => task.title === 'Initialize UI style document')).toBe(true);
+        });
         it('creates all required subdirectories', async () => {
             const root = await createTempDir();
             const initialized = await initializeProjectStructure(root);
@@ -327,9 +352,9 @@ describe('projitive module', () => {
                 expect(resolveScanRoots()).toHaveLength(1);
                 vi.unstubAllEnvs();
             });
-            it('throws error when no root environment variables are configured', () => {
+            it('falls back to home directory when no env vars configured', () => {
                 vi.unstubAllEnvs();
-                expect(() => resolveScanRoots()).toThrow('Missing required environment variable: PROJITIVE_SCAN_ROOT_PATHS');
+                expect(resolveScanRoots()).toEqual([homedir()]);
             });
         });
         describe('resolveScanDepth', () => {
@@ -357,9 +382,9 @@ describe('projitive module', () => {
                 expect(() => resolveScanDepth()).toThrow('Invalid PROJITIVE_SCAN_MAX_DEPTH');
                 vi.unstubAllEnvs();
             });
-            it('throws when PROJITIVE_SCAN_MAX_DEPTH env var is missing', () => {
+            it('falls back to default depth 3 when env var is missing', () => {
                 vi.unstubAllEnvs();
-                expect(() => resolveScanDepth()).toThrow('Missing required environment variable: PROJITIVE_SCAN_MAX_DEPTH');
+                expect(resolveScanDepth()).toBe(3);
             });
         });
         describe('resolveScanRoot', () => {
@@ -443,6 +468,13 @@ describe('projitive module', () => {
             expect(result.isError).toBeUndefined();
             expect(result.content[0].text).toContain('governanceDir:');
             expect(result.content[0].text).toContain('createdFiles:');
+            expect(result.content[0].text).toContain('designs/core/architecture.md');
+            expect(result.content[0].text).toContain('designs/core/code-style.md');
+            expect(result.content[0].text).toContain('designs/core/ui-style.md');
+            expect(result.content[0].text).toContain('Repair Summary (Missing Before Init)');
+            expect(result.content[0].text).toContain('- core docs:');
+            expect(result.content[0].text).toContain('- templates:');
+            expect(result.content[0].text).toContain('- bootstrap tasks:');
         });
         it('projectLocate resolves governance dir from any inner path', async () => {
             const root = await createTempDir();
@@ -484,6 +516,19 @@ describe('projitive module', () => {
             expect(result.content[0].text).toContain('Task Summary');
             expect(result.content[0].text).toContain('Artifacts');
         });
+        it('projectContext suggests rerunning projectInit when required core docs are missing', async () => {
+            const root = await createTempDir();
+            await initializeProjectStructure(root);
+            await fs.rm(path.join(root, '.projitive', 'designs', 'core', 'code-style.md'));
+            const mockServer = { registerTool: vi.fn() };
+            registerProjectTools(mockServer);
+            const projectContext = getProjectToolHandler(mockServer, 'projectContext');
+            const result = await projectContext({ projectPath: root });
+            expect(result.isError).toBeUndefined();
+            expect(result.content[0].text).toContain('codeStyleDocsStatus: MISSING');
+            expect(result.content[0].text).toContain('projectInit(projectPath="');
+            expect(result.content[0].text).toContain('PROJECT_CODE_STYLE_DOC_MISSING');
+        });
         it('syncViews materializes both tasks and roadmap markdown views', async () => {
             const root = await createTempDir();
             await initializeProjectStructure(root);