@projitive/mcp 2.1.1 → 2.1.3

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "2.1.1",
+    "version": "2.1.3",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",
@@ -12,6 +12,10 @@
     "publishConfig": {
         "access": "public"
     },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/yinxulai/projitive"
+    },
     "scripts": {
         "test": "vitest run",
         "test:coverage": "vitest run --coverage",

package/output/source/common/linter.js

@@ -13,10 +13,7 @@ export const TASK_LINT_CODES = {
     ROADMAP_REFS_EMPTY: 'TASK_ROADMAP_REFS_EMPTY',
     OUTSIDE_MARKER: 'TASK_OUTSIDE_MARKER',
     LINK_PATH_FORMAT_INVALID: 'TASK_LINK_PATH_FORMAT_INVALID',
-    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',
     // Spec v1.1.0 - Blocker Categorization
     BLOCKED_WITHOUT_BLOCKER: 'TASK_BLOCKED_WITHOUT_BLOCKER',
     BLOCKER_TYPE_INVALID: 'TASK_BLOCKER_TYPE_INVALID',
@@ -37,5 +34,6 @@ export const ROADMAP_LINT_CODES = {
 export const PROJECT_LINT_CODES = {
     TASKS_FILE_MISSING: 'PROJECT_TASKS_FILE_MISSING',
     ARCHITECTURE_DOC_MISSING: 'PROJECT_ARCHITECTURE_DOC_MISSING',
-    STYLE_DOC_MISSING: 'PROJECT_STYLE_DOC_MISSING',
+    CODE_STYLE_DOC_MISSING: 'PROJECT_CODE_STYLE_DOC_MISSING',
+    UI_STYLE_DOC_MISSING: 'PROJECT_UI_STYLE_DOC_MISSING',
 };

package/output/source/common/response.js

@@ -32,7 +32,8 @@ export function getDefaultToolTemplateMarkdown(toolName) {
             '- Check lint gaps and create executable fix tasks.',
             '- Check test quality gaps (missing tests, flaky tests, low-value coverage).',
             '- Learn current project architecture and consolidate/update design docs in designs/.',
-            '- Review and update architecture docs under designs/core/ (architecture.md, style-guide.md) if missing or outdated.',
+            '- Review and update core governance docs under designs/core/ (architecture.md, code-style.md, ui-style.md) if missing or outdated.',
+            '- When finishing a task, re-check whether architecture boundaries, code conventions, or UI patterns changed and update the matching core docs.',
             '- Re-run {{tool_name}} after creating 1-3 focused TODO tasks.',
         ].join('\n');
     }
@@ -49,10 +50,34 @@ export function getDefaultToolTemplateMarkdown(toolName) {
             '- ./.cursor/rules/*',
         ].join('\n');
     }
-    if (toolName === 'taskUpdate' || toolName === 'roadmapUpdate') {
+    if (toolName === 'taskUpdate') {
         return [
             base,
             '',
+            '## Governance Write Rule',
+            '- MUST use governance tools for task/roadmap state updates.',
+            '- NEVER edit tasks.md/roadmap.md directly; they are generated views.',
+            '',
+            '## Core Docs Review Checklist (Required When Marking DONE)',
+            '- [ ] architecture.md reviewed (designs/core/architecture.md)',
+            '- [ ] code-style.md reviewed (designs/core/code-style.md)',
+            '- [ ] ui-style.md reviewed (designs/core/ui-style.md)',
+            '',
+            '## Commit Reminder',
+            '- After this update, create a commit to keep progress auditable.',
+            '- Recommended format: type(scope): summary',
+            '- Example: feat(task): complete TASK-0007 validation flow',
+            '- Footer suggestion: Refs: TASK-0007, ROADMAP-0002',
+        ].join('\n');
+    }
+    if (toolName === 'roadmapUpdate') {
+        return [
+            base,
+            '',
+            '## Governance Write Rule',
+            '- MUST use governance tools for task/roadmap state updates.',
+            '- NEVER edit tasks.md/roadmap.md directly; they are generated views.',
+            '',
             '## Commit Reminder',
             '- After this update, create a commit to keep progress auditable.',
             '- Recommended format: type(scope): summary',

package/output/source/common/response.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { asText, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from './response.js';
+import { asText, getDefaultToolTemplateMarkdown, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from './response.js';
 describe('response helpers', () => {
     it('wraps markdown text as MCP text content', () => {
         const result = asText('# hello');
@@ -47,4 +47,16 @@ describe('response helpers', () => {
         });
         expect(withoutCall).toContain('- (none)');
     });
+    it('taskUpdate default template includes core docs review checklist', () => {
+        const markdown = getDefaultToolTemplateMarkdown('taskUpdate');
+        expect(markdown).toContain('Core Docs Review Checklist (Required When Marking DONE)');
+        expect(markdown).toContain('- [ ] architecture.md reviewed (designs/core/architecture.md)');
+        expect(markdown).toContain('- [ ] code-style.md reviewed (designs/core/code-style.md)');
+        expect(markdown).toContain('- [ ] ui-style.md reviewed (designs/core/ui-style.md)');
+    });
+    it('roadmapUpdate default template keeps governance write rule without task checklist', () => {
+        const markdown = getDefaultToolTemplateMarkdown('roadmapUpdate');
+        expect(markdown).toContain('Governance Write Rule');
+        expect(markdown).not.toContain('Core Docs Review Checklist (Required When Marking DONE)');
+    });
 });

package/output/source/prompts/quickStart.js

@@ -69,6 +69,7 @@ export function registerQuickStartPrompt(server) {
             '2. Understand task requirements and acceptance criteria',
             '3. Write governance source via tools (`taskCreate` / `taskUpdate` / `roadmapCreate` / `roadmapUpdate`) instead of editing tasks.md/roadmap.md directly',
             '4. Update docs (`designs/` / `reports/`) as required by evidence',
+            '4.5. Before closing the task, check whether `designs/core/architecture.md`, `designs/core/code-style.md`, or `designs/core/ui-style.md` need updates',
             '5. taskCreate/taskUpdate/roadmapCreate/roadmapUpdate will auto-sync corresponding markdown views',
             '6. Update task status:',
             '   - TODO → IN_PROGRESS (when starting execution)',
@@ -104,11 +105,12 @@ export function registerQuickStartPrompt(server) {
             '**Stop Reason 3: No actionable tasks (all TODO blocked or no tasks exist)**',
             '- Means: all unblocked work is complete, only blocked tasks remain OR no tasks at all',
             '- **What to do next:** Analyze blockers and roadmap, create 1-3 new TODO tasks via `taskCreate()`',
+            '- Prefer creating or refreshing core-doc tasks first when `designs/core/architecture.md`, `designs/core/code-style.md`, or `designs/core/ui-style.md` are missing or stale',
             '',
             '## Special Cases',
             '',
-            '### Case 1: No .projitive directory',
-            'Call `projectInit(projectPath="<project-dir>")` to initialize governance structure.',
+            '### Case 1: No .projitive directory or required governance artifacts are missing',
+            'Call `projectInit(projectPath="<project-dir>")` to initialize or repair governance structure.',
             '',
             '### Case 2: No actionable tasks (all TODO/IN_PROGRESS are blocked OR task count is zero)',
             '',
@@ -135,6 +137,7 @@ export function registerQuickStartPrompt(server) {
             '   - **Minimal dependencies**: avoid complex task chains at start',
             '4. Call `taskCreate()` for each task with complete metadata',
             '5. Re-run `taskNext()` to start executing the new tasks',
+            '6. Ensure bootstrap projects include TODO tasks for project architecture, code style, and UI style docs',
             '',
             '**If roadmap is also empty:**',
             '1. Read design documents under `projitive://designs/`',
@@ -147,9 +150,11 @@ export function registerQuickStartPrompt(server) {
             '- **NEVER modify TASK/ROADMAP IDs** - Keep them immutable once assigned',
             '- **Every status transition must have report evidence** - Create execution reports in reports/ directory',
             '- **.projitive governance store is source of truth** - tasks.md/roadmap.md are generated views and may be overwritten',
-            '- **Prefer tool writes over manual table/view edits** - Use taskCreate/taskUpdate/roadmapCreate/roadmapUpdate',
+            '- **MUST use tools for task/roadmap changes** - Use taskCreate/taskUpdate/roadmapCreate/roadmapUpdate',
+            '- **NEVER edit tasks.md or roadmap.md directly** - They are generated views, not writable source-of-truth',
             '- **Always verify after updates** - Re-run taskContext() to confirm reference consistency',
             '- **BLOCKED tasks require full blocker metadata** - type, description required; blockingEntity, unblockCondition, escalationPath as needed',
+            '- **Every completed task should re-check core docs** - architecture.md for system changes, code-style.md for engineering conventions, ui-style.md for UI/pattern changes',
         ].join('\n');
         return asUserPrompt(text);
     });

package/output/source/prompts/taskDiscovery.js

@@ -155,6 +155,12 @@ export function registerTaskDiscoveryPrompt(server) {
             '',
             '3. **Execute task content**',
             '   - Update governance store via MCP tools; edit designs/*.md and reports/*.md as needed',
+            '   - NEVER edit tasks.md/roadmap.md directly; use taskCreate/taskUpdate/roadmapCreate/roadmapUpdate',
+            '   - Core docs review checklist (required before DONE):',
+            '     - [ ] architecture.md reviewed (`designs/core/architecture.md`)',
+            '     - [ ] code-style.md reviewed (`designs/core/code-style.md`)',
+            '     - [ ] ui-style.md reviewed (`designs/core/ui-style.md`)',
+            '   - Before closing a task, re-check designs/core/architecture.md, designs/core/code-style.md, and designs/core/ui-style.md and update any stale guidance',
             '   - If immediate markdown snapshots are required by another agent/session, call syncViews(force=true)',
             '   - Create execution report (reports/ directory)',
             '   - Update task status to DONE',
@@ -171,6 +177,7 @@ export function registerTaskDiscoveryPrompt(server) {
             'If taskNext() returns empty:',
             '1. Check if .projitive exists',
             '2. Analyze active roadmap milestones and derive 1-3 executable TODO tasks',
+            '2.5. If core docs are missing or clearly stale, create TODO tasks to initialize or refresh project architecture, code style, and UI style docs first',
             '3. Prioritize milestone slices that unblock multiple downstream tasks',
             '3.5 If roadmap milestone is missing, create it first via `roadmapCreate()`',
             '4. Create tasks via `taskCreate(projectPath="...", taskId="TASK-xxxx", title="...", roadmapRefs=["ROADMAP-xxxx"], summary="...")`',
@@ -193,8 +200,8 @@ export function registerTaskDiscoveryPrompt(server) {
             '',
             '### Case 3: Missing required governance files',
             '',
-            'If .projitive does not exist:',
-            '1. Call `projectInit(projectPath="...")` to initialize governance structure',
+            'If .projitive does not exist or required governance artifacts are missing:',
+            '1. Call `projectInit(projectPath="...")` to initialize or repair governance structure',
             '2. Then restart discovery flow',
             '',
             '## Quick Reference',
@@ -211,6 +218,14 @@ export function registerTaskDiscoveryPrompt(server) {
             '| `taskUpdate()` | Update task status |',
             '| `roadmapCreate()` | Create a new roadmap milestone |',
             '| `syncViews()` | Force materialize tasks.md/roadmap.md from governance store |',
+            '',
+            '## Core Doc Maintenance Rule',
+            '- When a task changes architecture, engineering conventions, or UI patterns, update the matching core doc before marking the task DONE.',
+            '- Core docs live under `designs/core/`: `architecture.md`, `code-style.md`, `ui-style.md`.',
+            '',
+            '## Governance Write Rule',
+            '- MUST use governance tools (`taskCreate`, `taskUpdate`, `roadmapCreate`, `roadmapUpdate`) for state changes.',
+            '- NEVER edit `tasks.md` or `roadmap.md` directly; those files are generated views.',
         ].join('\n');
         return asUserPrompt(text);
     });

package/output/source/prompts/taskDiscovery.test.js

@@ -11,6 +11,10 @@ describe('taskDiscovery prompt', () => {
         expect(text).toContain('Known project path: "/workspace/app"');
         expect(text).toContain('Method A: Auto-select with taskNext()');
         expect(text).toContain('roadmapCreate');
+        expect(text).toContain('Core docs review checklist (required before DONE):');
+        expect(text).toContain('- [ ] architecture.md reviewed (`designs/core/architecture.md`)');
+        expect(text).toContain('- [ ] code-style.md reviewed (`designs/core/code-style.md`)');
+        expect(text).toContain('- [ ] ui-style.md reviewed (`designs/core/ui-style.md`)');
     });
     it('renders unknown-project discovery steps', async () => {
         const server = { registerPrompt: vi.fn() };

package/output/source/prompts/taskExecution.js

@@ -47,7 +47,8 @@ export function registerTaskExecutionPrompt(server) {
             '- If status is MISSING/INCOMPLETE, complete it before any implementation',
             '',
             '### Pre-Execution Research Brief (Mandatory Gate)',
-            '- Fixed file name: `designs/research/<TASK-ID>.implementation-research.md`',
+            '- Fixed file name (relative to governanceDir): `designs/research/<TASK-ID>.implementation-research.md`',
+            '- Absolute location: `<governanceDir>/designs/research/<TASK-ID>.implementation-research.md`',
             '- Required sections:',
             '  - `## Design Guidelines and Specs`',
             '  - `## Code Architecture and Implementation Findings`',
@@ -85,7 +86,9 @@ export function registerTaskExecutionPrompt(server) {
             '2. **Execute task content**',
             '   - Prefer MCP tool writes for governance store (`taskUpdate` / `roadmapUpdate`)',
             '   - .projitive (task table) - Update task status and metadata',
+            '   - NEVER edit tasks.md/roadmap.md directly; always write via tools and let views sync automatically',
             '   - designs/*.md - Add or update design documents',
+            '   - Before marking DONE, check whether `designs/core/architecture.md`, `designs/core/code-style.md`, or `designs/core/ui-style.md` need maintenance',
             '   - reports/*.md - Create execution reports',
             '   - .projitive (roadmap table) - Update roadmap (if needed)',
             '   - taskCreate/taskUpdate/roadmapCreate/roadmapUpdate auto-sync corresponding markdown views',
@@ -98,6 +101,11 @@ export function registerTaskExecutionPrompt(server) {
             '',
             '4. **Complete task (if status is IN_PROGRESS)',
             '   - Confirm all acceptance criteria are met',
+            '   - Core docs review checklist (required):',
+            '     - [ ] architecture.md reviewed (`designs/core/architecture.md`)',
+            '     - [ ] code-style.md reviewed (`designs/core/code-style.md`)',
+            '     - [ ] ui-style.md reviewed (`designs/core/ui-style.md`)',
+            '   - Confirm project architecture, code style, and UI style docs are still accurate after the change',
             '   - Call `taskUpdate()` to change status to DONE',
             '   - Update updatedAt timestamp',
             '',
@@ -194,8 +202,8 @@ export function registerTaskExecutionPrompt(server) {
             '',
             '### Case 3: Need to initialize governance',
             '',
-            'If .projitive directory does not exist:',
-            '1. Call `projectInit(projectPath="<project-dir>")`',
+            'If .projitive directory does not exist or required governance artifacts are missing:',
+            '1. Call `projectInit(projectPath="<project-dir>")` to initialize or repair governance structure',
             '2. Then restart',
             '',
             '## Hard Rules (NEVER violate)',
@@ -211,7 +219,8 @@ export function registerTaskExecutionPrompt(server) {
             '',
             '3. **Governance-store-first writes only**',
             '   - tasks.md/roadmap.md are generated views, not authoritative source',
-            '   - Use taskUpdate/roadmapUpdate as primary write path',
+            '   - MUST use taskCreate/taskUpdate/roadmapCreate/roadmapUpdate for governance state changes',
+            '   - NEVER directly edit tasks.md/roadmap.md',
             '',
             '4. **Always verify after updates**',
             '   - After every taskUpdate() call',
@@ -224,7 +233,12 @@ export function registerTaskExecutionPrompt(server) {
             '',
             '6. **Pre-execution research brief is mandatory**',
             '   - `TODO -> IN_PROGRESS` is not allowed until research brief is READY',
-            '   - Always read `designs/research/<TASK-ID>.implementation-research.md` before implementation',
+            '   - Always read `<governanceDir>/designs/research/<TASK-ID>.implementation-research.md` before implementation',
+            '',
+            '7. **Core docs are a completion checkpoint**',
+            '   - Re-check `designs/core/architecture.md` when system boundaries or flows change',
+            '   - Re-check `designs/core/code-style.md` when coding conventions or reusable engineering patterns change',
+            '   - Re-check `designs/core/ui-style.md` when UI behavior, tokens, or interaction patterns change',
         ].join('\n');
         return asUserPrompt(text);
     });

package/output/source/prompts/taskExecution.test.js

@@ -11,7 +11,12 @@ describe('taskExecution prompt', () => {
         expect(text).toContain('1) Run taskContext(projectPath="/workspace/app", taskId="TASK-0007").');
         expect(text).toContain('Every status transition must have report evidence');
         expect(text).toContain('Pre-Execution Research Brief (Mandatory Gate)');
-        expect(text).toContain('designs/research/<TASK-ID>.implementation-research.md');
+        expect(text).toContain('Fixed file name (relative to governanceDir): `designs/research/<TASK-ID>.implementation-research.md`');
+        expect(text).toContain('Always read `<governanceDir>/designs/research/<TASK-ID>.implementation-research.md` before implementation');
+        expect(text).toContain('Core docs review checklist (required):');
+        expect(text).toContain('- [ ] architecture.md reviewed (`designs/core/architecture.md`)');
+        expect(text).toContain('- [ ] code-style.md reviewed (`designs/core/code-style.md`)');
+        expect(text).toContain('- [ ] ui-style.md reviewed (`designs/core/ui-style.md`)');
     });
     it('falls back to taskNext when task is not provided', async () => {
         const server = { registerPrompt: vi.fn() };