feat: add path length validation for Windows MAX_PATH and capability portability

Dual check: warn when full path exceeds 260 chars (Windows MAX_PATH)
or when capability path exceeds 160 chars (portability risk).

Author: lsmonki

src/utils/spec-discovery.ts

@@ -333,6 +333,27 @@ export function validateSpecStructure(
     }
   }
 
+  // Check path length (Windows MAX_PATH compatibility)
+  if (validatePaths) {
+    const WINDOWS_MAX_PATH = 260;
+    const MAX_CAPABILITY_LENGTH = 160; // Leaves ~100 chars for project root + openspec/specs/ + /spec.md
+    for (const spec of specs) {
+      if (spec.path.length > WINDOWS_MAX_PATH) {
+        issues.push({
+          level: 'WARNING',
+          message: `Spec "${spec.capability}" has a full path of ${spec.path.length} characters, exceeding Windows MAX_PATH (${WINDOWS_MAX_PATH}). This will cause issues on Windows.`,
+          capability: spec.capability,
+        });
+      } else if (spec.capability.length > MAX_CAPABILITY_LENGTH) {
+        issues.push({
+          level: 'WARNING',
+          message: `Spec "${spec.capability}" has a capability path of ${spec.capability.length} characters (max recommended: ${MAX_CAPABILITY_LENGTH}). Long paths may cause issues on Windows depending on project location.`,
+          capability: spec.capability,
+        });
+      }
+    }
+  }
+
   // Check naming conventions (if enabled)
   if (validatePaths) {
     const VALID_NAME_PATTERN = /^[a-z0-9-_]+$/;

test/utils/spec-discovery.test.ts

@@ -630,6 +630,80 @@ describe('spec-discovery', () => {
     });
   });
 
+  describe('validateSpecStructure() - path length validation', () => {
+    it('should warn when full path exceeds Windows MAX_PATH (260)', () => {
+      // Build a path that exceeds 260 chars total
+      const prefix = '/a-long-project-root-directory/with/many/levels/openspec/specs/';
+      const longSegments = Array.from({ length: 8 }, (_, i) => `segment-${String(i).padStart(2, '0')}-with-extra-padding`);
+      const capability = longSegments.join(path.sep);
+      const fullPath = prefix + longSegments.join('/') + '/spec.md';
+
+      expect(fullPath.length).toBeGreaterThan(260);
+
+      const specs: DiscoveredSpec[] = [
+        { capability, path: fullPath, depth: 8 },
+      ];
+
+      const issues = validateSpecStructure(specs, { validatePaths: true, maxDepth: 10 });
+      const lengthIssues = issues.filter(i => i.message.includes('characters'));
+
+      expect(lengthIssues).toHaveLength(1);
+      expect(lengthIssues[0].level).toBe('WARNING');
+      expect(lengthIssues[0].message).toContain('Windows MAX_PATH');
+    });
+
+    it('should not warn for paths under 260 characters', () => {
+      const specs: DiscoveredSpec[] = [
+        { capability: path.join('platform', 'services', 'api'), path: '/specs/platform/services/api/spec.md', depth: 3 },
+      ];
+
+      const issues = validateSpecStructure(specs, { validatePaths: true, maxDepth: 4 });
+      const lengthIssues = issues.filter(i => i.message.includes('characters'));
+
+      expect(lengthIssues).toHaveLength(0);
+    });
+
+    it('should warn when capability path exceeds 160 characters (even if full path under 260)', () => {
+      // Build a capability that exceeds 160 chars but keep full path under 260
+      const longSegments = Array.from({ length: 6 }, (_, i) => `long-segment-name-${String(i).padStart(2, '0')}-padding`);
+      const capability = longSegments.join(path.sep);
+
+      expect(capability.length).toBeGreaterThan(160);
+
+      // Short prefix keeps full path under 260
+      const fullPath = '/specs/' + longSegments.join('/') + '/spec.md';
+      expect(fullPath.length).toBeLessThan(260);
+
+      const specs: DiscoveredSpec[] = [
+        { capability, path: fullPath, depth: 6 },
+      ];
+
+      const issues = validateSpecStructure(specs, { validatePaths: true, maxDepth: 10 });
+      const lengthIssues = issues.filter(i => i.message.includes('characters'));
+
+      expect(lengthIssues).toHaveLength(1);
+      expect(lengthIssues[0].level).toBe('WARNING');
+      expect(lengthIssues[0].message).toContain('capability path');
+      expect(lengthIssues[0].message).toContain('160');
+    });
+
+    it('should skip path length check when validatePaths is false', () => {
+      const prefix = '/a-long-project-root-directory/with/many/levels/openspec/specs/';
+      const longSegments = Array.from({ length: 8 }, (_, i) => `segment-${String(i).padStart(2, '0')}-with-extra-padding`);
+      const capability = longSegments.join(path.sep);
+      const fullPath = prefix + longSegments.join('/') + '/spec.md';
+
+      const specs: DiscoveredSpec[] = [
+        { capability, path: fullPath, depth: 8 },
+      ];
+
+      const issues = validateSpecStructure(specs, { validatePaths: false, maxDepth: 10 });
+      const lengthIssues = issues.filter(i => i.message.includes('characters'));
+
+      expect(lengthIssues).toHaveLength(0);
+    });
+  });
+
   describe('validateSpecStructure() - reserved names validation', () => {
     it('should reject reserved directory names', () => {
       const reservedNames = [