feat: add stale spec warnings to MCP board tool

- Add getStaleSpecs helper to detect specs in-progress for > 7 days
- Add updated_at to SpecData type for staleness calculation
- Board tool now returns warnings array with stale spec alerts
- Helps enforce SDD workflow compliance

Part of spec 121: MCP-First Agent Experience

Author: tikazyq

AGENTS.md

@@ -188,6 +188,7 @@ Hard dependency - spec cannot start until dependencies complete.
   - Never leave specs with stale status
 - **Always validate before completing work:**
   - Run `node bin/lean-spec.js validate` to check spec structure and frontmatter (use local build, not `npx`)
+  - Run `node bin/lean-spec.js validate --check-deps` to verify content/frontmatter dependency alignment
   - Run `cd docs-site && npm run build` to ensure documentation site builds successfully
   - Update spec status to `complete` with `lean-spec update <spec> --status complete`
   - Fix any validation errors or build failures before marking work complete

packages/cli/src/commands/validate.ts

@@ -21,6 +21,7 @@ import { StructureValidator } from '../validators/structure.js';
 import { CorruptionValidator } from '../validators/corruption.js';
 import { SubSpecValidator } from '../validators/sub-spec.js';
 import { ComplexityValidator } from '../validators/complexity.js';
+import { DependencyAlignmentValidator } from '../validators/dependency-alignment.js';
 import type { ValidationRule, ValidationResult } from '../utils/validation-framework.js';
 import { formatValidationResults, type FormatOptions } from '../utils/validate-formatter.js';
 
@@ -33,6 +34,7 @@ export interface ValidateOptions {
   json?: boolean;     // Shorthand for --format json
   rule?: string;      // Filter by specific rule name
   warningsOnly?: boolean; // Treat all issues as warnings, never fail (useful for CI)
+  checkDeps?: boolean; // Include dependency alignment check
 }
 
 interface ValidationResultWithSpec {
@@ -56,6 +58,7 @@ export function validateCommand(): Command {
     .option('--json', 'Output as JSON (shorthand for --format json)')
     .option('--rule <rule>', 'Filter by specific rule name (e.g., max-lines, frontmatter)')
     .option('--warnings-only', 'Treat all issues as warnings, never fail (useful for CI pre-release checks)')
+    .option('--check-deps', 'Check for content/frontmatter dependency alignment')
     .action(async (specs: string[] | undefined, options: ValidateOptions) => {
       const passed = await validateSpecs({
         maxLines: options.maxLines,
@@ -65,6 +68,7 @@ export function validateCommand(): Command {
         format: options.json ? 'json' : options.format,
         rule: options.rule,
         warningsOnly: options.warningsOnly,
+        checkDeps: options.checkDeps,
       });
       process.exit(passed ? 0 : 1);
     });
@@ -116,6 +120,20 @@ export async function validateSpecs(options: ValidateOptions = {}): Promise<bool
     new SubSpecValidator({ maxLines: options.maxLines }),
   ];
 
+  // Add dependency alignment validator if requested
+  if (options.checkDeps) {
+    // Collect existing spec numbers for validation (only active specs, not archived)
+    const activeSpecs = await loadAllSpecs({ includeArchived: false });
+    const existingSpecNumbers = new Set<string>();
+    for (const s of activeSpecs) {
+      const match = s.name.match(/^(\d{3})/);
+      if (match) {
+        existingSpecNumbers.add(match[1]);
+      }
+    }
+    validators.push(new DependencyAlignmentValidator({ existingSpecNumbers }));
+  }
+
   // Run validation
   const results: ValidationResultWithSpec[] = [];
 

packages/cli/src/mcp/helpers.ts

@@ -5,7 +5,7 @@
 import * as fs from 'node:fs/promises';
 import { countTokens } from '@leanspec/core';
 import { loadSubFiles } from '../spec-loader.js';
-import type { SpecData, SubSpecReference } from './types.js';
+import type { SpecData, SubSpecReference, BoardData } from './types.js';
 
 /**
  * Format error messages for MCP responses
@@ -15,6 +15,45 @@ export function formatErrorMessage(prefix: string, error: unknown): string {
   return `${prefix}: ${errorMsg}`;
 }
 
+/**
+ * Stale spec information
+ */
+export interface StaleSpec {
+  name: string;
+  daysStale: number;
+}
+
+/**
+ * Get specs that have been in-progress for too long
+ * Default threshold: 7 days
+ */
+export function getStaleSpecs(board: BoardData, thresholdDays = 7): StaleSpec[] {
+  const now = new Date();
+  const staleSpecs: StaleSpec[] = [];
+  
+  for (const spec of board.columns['in-progress']) {
+    // Check updated_at first, then fall back to created date
+    const lastActivity = spec.updated_at || spec.created;
+    if (!lastActivity) continue;
+    
+    try {
+      const activityDate = new Date(lastActivity);
+      const daysSinceActivity = Math.floor((now.getTime() - activityDate.getTime()) / (1000 * 60 * 60 * 24));
+      
+      if (daysSinceActivity >= thresholdDays) {
+        staleSpecs.push({
+          name: spec.name,
+          daysStale: daysSinceActivity,
+        });
+      }
+    } catch {
+      // Invalid date format, skip
+    }
+  }
+  
+  return staleSpecs;
+}
+
 /**
  * Convert spec info to serializable SpecData format
  */
@@ -30,6 +69,7 @@ export function specToData(spec: any): SpecData {
     assignee: spec.frontmatter.assignee,
     description: spec.frontmatter.description,
     customFields: spec.frontmatter.custom,
+    updated_at: spec.frontmatter.updated_at,
   };
 }
 

packages/cli/src/mcp/prompts/registry.ts

@@ -6,6 +6,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { planProjectRoadmapPrompt } from './plan-project-roadmap.js';
 import { projectProgressOverviewPrompt } from './project-progress-overview.js';
 import { sddCheckpointPrompt } from './sdd-checkpoint.js';
+import { specCreationWorkflowPrompt } from './spec-creation-workflow.js';
 import { updateSpecStatusPrompt } from './update-spec-status.js';
 
 /**
@@ -15,5 +16,6 @@ export function registerPrompts(server: McpServer): void {
   server.registerPrompt(...projectProgressOverviewPrompt());
   server.registerPrompt(...planProjectRoadmapPrompt());
   server.registerPrompt(...sddCheckpointPrompt());
+  server.registerPrompt(...specCreationWorkflowPrompt());
   server.registerPrompt(...updateSpecStatusPrompt());
 }

packages/cli/src/mcp/prompts/spec-creation-workflow.ts

@@ -0,0 +1,79 @@
+/**
+ * Spec Creation Workflow prompt - Guide complete spec creation with dependency linking
+ */
+
+/**
+ * Spec Creation Workflow prompt definition
+ * Use this when creating new specs to ensure proper dependency linking
+ */
+export function specCreationWorkflowPrompt() {
+  return [
+    'create-spec',
+    {
+      title: 'Create Spec with Dependencies',
+      description: 'Complete workflow for creating a new spec including proper dependency linking. Prevents the common issue of content referencing specs without frontmatter links.',
+    },
+    () => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `## Create Spec Workflow 📝
+
+Follow these steps to create a well-linked spec:
+
+### Step 1: Pre-Creation Research
+Before creating, use \`search\` to find related specs:
+- Search for similar features or components
+- Identify potential dependencies
+- Note specs to reference
+
+### Step 2: Create the Spec
+Use \`create\` with the spec details:
+\`\`\`
+create {
+  "name": "your-spec-name",
+  "title": "Human Readable Title",
+  "description": "Initial overview content...",
+  "priority": "medium",
+  "tags": ["relevant", "tags"]
+}
+\`\`\`
+
+### Step 3: Link Dependencies (CRITICAL)
+After creating, **immediately** link any referenced specs:
+
+For each spec mentioned in content:
+- "Depends on spec 045" → \`link { "spec": "your-spec", "dependsOn": ["045"] }\`
+- "Related to spec 072" → \`link { "spec": "your-spec", "related": ["072"] }\`
+- "See spec 110" → \`link { "spec": "your-spec", "related": ["110"] }\`
+
+### Step 4: Verify
+Use \`deps\` to verify all links are in place:
+\`\`\`
+deps { "spec": "your-spec" }
+\`\`\`
+
+### Step 5: Validate
+Run dependency alignment check:
+\`\`\`
+validate { "specs": ["your-spec"], "checkDeps": true }
+\`\`\`
+
+### Common Patterns to Link
+
+| Content Pattern | Link Type |
+|----------------|-----------|
+| "depends on", "blocked by", "requires" | dependsOn |
+| "related to", "see also", "similar to" | related |
+| "builds on" | dependsOn (if blocking) or related |
+| "## Related Specs" section | related (link each one) |
+
+**Remember:** Content and frontmatter must stay aligned!`,
+          },
+        },
+      ],
+    })
+  ] as const;
+}

packages/cli/src/mcp/tools/board.ts

@@ -4,7 +4,7 @@
 
 import { z } from 'zod';
 import { loadAllSpecs } from '../../spec-loader.js';
-import { formatErrorMessage, specToData } from '../helpers.js';
+import { formatErrorMessage, specToData, getStaleSpecs } from '../helpers.js';
 import type { ToolDefinition, BoardData } from '../types.js';
 
 /**
@@ -41,12 +41,28 @@ export function boardTool(): ToolDefinition {
       inputSchema: {},
       outputSchema: {
         board: z.any(),
+        warnings: z.array(z.string()).optional(),
       },
     },
     async (_input, _extra) => {
       try {
         const board = await getBoardData();
-        const output = { board };
+        
+        // Check for stale specs (in-progress for > 7 days)
+        const staleSpecs = getStaleSpecs(board);
+        const warnings: string[] = [];
+        
+        if (staleSpecs.length > 0) {
+          for (const spec of staleSpecs) {
+            warnings.push(`⚠️ Spec "${spec.name}" has been in-progress for ${spec.daysStale} days. Consider updating status.`);
+          }
+        }
+        
+        const output = { 
+          board,
+          ...(warnings.length > 0 ? { warnings } : {}),
+        };
+        
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(output, null, 2) }],
           structuredContent: output,

packages/cli/src/mcp/tools/validate.ts

@@ -15,10 +15,11 @@ export function validateTool(): ToolDefinition {
     'validate',
     {
       title: 'Validate Specs',
-      description: 'Validate specifications for quality issues like excessive length, missing sections, or complexity problems. Use this before committing changes or for project health checks.',
+      description: 'Validate specifications for quality issues like excessive length, missing sections, or complexity problems. Use this before committing changes or for project health checks. Use checkDeps to detect content/frontmatter dependency misalignment.',
       inputSchema: {
         specs: z.array(z.string()).optional().describe('Specific specs to validate. If omitted, validates all specs in the project.'),
         maxLines: z.number().optional().describe('Custom line limit for complexity checks (default: 400 lines).'),
+        checkDeps: z.boolean().optional().describe('Check for content/frontmatter dependency alignment. Detects when spec content references other specs but those references are not in frontmatter depends_on/related fields.'),
       },
       outputSchema: {
         passed: z.boolean(),
@@ -41,6 +42,7 @@ export function validateTool(): ToolDefinition {
         const passed = await validateSpecs({
           maxLines: input.maxLines,
           specs: input.specs,
+          checkDeps: input.checkDeps,
         });
 
         const output = {

packages/cli/src/mcp/types.ts

@@ -32,6 +32,7 @@ export type SpecData = {
   description?: string;
   customFields?: Record<string, unknown>;
   subSpecs?: SubSpecReference[];  // Only when viewing main spec
+  updated_at?: string;  // ISO timestamp for stale detection
 };
 
 /**