@schnick371/devsteps-shared 0.0.1 → 0.5.0

package/src/core/validation.ts

@@ -0,0 +1,252 @@
+import type { ItemType, Methodology } from '../schemas/index.js';
+import { isFlexibleRelation, isHierarchyRelation } from '../schemas/relationships.js';
+
+/**
+ * Validation result with detailed error messaging
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  suggestion?: string;
+}
+
+/**
+ * Minimal work item info needed for validation
+ */
+export interface WorkItem {
+  id: string;
+  type: ItemType;
+}
+
+/**
+ * Validate relationship between two items based on methodology
+ * Only validates "implements" relationships - all other relations are flexible
+ *
+ * @param source - Item creating the relationship (child in hierarchy)
+ * @param target - Item being referenced (parent in hierarchy)
+ * @param relationType - Type of relationship
+ * @param methodology - Project methodology (scrum, waterfall, hybrid)
+ * @returns ValidationResult with valid flag and optional error/suggestion
+ */
+export function validateRelationship(
+  source: WorkItem,
+  target: WorkItem,
+  relationType: string,
+  methodology: Methodology
+): ValidationResult {
+  // Flexible relationships always allowed
+  if (isFlexibleRelation(relationType)) {
+    return { valid: true };
+  }
+
+  // Only validate hierarchy relationships
+  if (!isHierarchyRelation(relationType)) {
+    return { valid: false, error: `Unknown relationship type: ${relationType}` };
+  }
+
+  // Only validate "implements" direction (implemented-by is automatic reverse)
+  if (relationType === 'implemented-by') {
+    return { valid: true }; // Reverse relationships auto-created, no validation needed
+  }
+
+  // Validate based on methodology
+  if (methodology === 'scrum') {
+    return validateScrumHierarchy(source, target);
+  }
+
+  if (methodology === 'waterfall') {
+    return validateWaterfallHierarchy(source, target);
+  }
+
+  if (methodology === 'hybrid') {
+    // Try Scrum rules first
+    const scrumResult = validateScrumHierarchy(source, target);
+    if (scrumResult.valid) {
+      return scrumResult;
+    }
+
+    // Try Waterfall rules
+    const waterfallResult = validateWaterfallHierarchy(source, target);
+    if (waterfallResult.valid) {
+      return waterfallResult;
+    }
+
+    // Neither worked - return Scrum error (more common)
+    return scrumResult;
+  }
+
+  return {
+    valid: false,
+    error: `Unknown methodology: ${methodology}`,
+  };
+}
+
+/**
+ * Validate Scrum hierarchy rules
+ * Epic → Story|Spike → Task
+ * Bug/Test can implement Epic or Story
+ */
+function validateScrumHierarchy(source: WorkItem, target: WorkItem): ValidationResult {
+  const { type: sourceType } = source;
+  const { type: targetType } = target;
+
+  // Task → Story or Spike
+  if (sourceType === 'task') {
+    if (targetType === 'story' || targetType === 'spike') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Tasks can only implement Stories or Spikes in Scrum',
+      suggestion: `Change ${target.id} to a Story or create a Story first, then link Task → Story`,
+    };
+  }
+
+  // Story → Epic
+  if (sourceType === 'story') {
+    if (targetType === 'epic') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Stories can only implement Epics in Scrum',
+      suggestion: `Change ${target.id} to an Epic or create an Epic first, then link Story → Epic`,
+    };
+  }
+
+  // Spike → Epic
+  if (sourceType === 'spike') {
+    if (targetType === 'epic') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Spikes can only implement Epics in Scrum',
+      suggestion: `Change ${target.id} to an Epic or create an Epic first, then link Spike → Epic`,
+    };
+  }
+
+  // Bug → Epic or Story (flexible)
+  if (sourceType === 'bug') {
+    if (targetType === 'epic' || targetType === 'story') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Bugs can only implement Epics or Stories in Scrum',
+      suggestion: `Use "relates-to" for Bug → ${targetType} relationships, or create Epic/Story first`,
+    };
+  }
+
+  // Test → Epic or Story (flexible)
+  if (sourceType === 'test') {
+    if (targetType === 'epic' || targetType === 'story') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Tests can only implement Epics or Stories in Scrum',
+      suggestion: `Use "tested-by" relationship or create Epic/Story first`,
+    };
+  }
+
+  // Epic cannot implement anything (top-level)
+  if (sourceType === 'epic') {
+    return {
+      valid: false,
+      error: 'Epics are top-level items and cannot implement other items',
+      suggestion: 'Consider using "relates-to" to link Epics together',
+    };
+  }
+
+  return {
+    valid: false,
+    error: `Invalid Scrum relationship: ${sourceType} → ${targetType}`,
+    suggestion: 'Check Scrum hierarchy: Epic → Story|Spike → Task',
+  };
+}
+
+/**
+ * Validate Waterfall hierarchy rules
+ * Requirement → Feature|Spike → Task
+ * Bug/Test can implement Requirement or Feature
+ */
+function validateWaterfallHierarchy(source: WorkItem, target: WorkItem): ValidationResult {
+  const { type: sourceType } = source;
+  const { type: targetType } = target;
+
+  // Task → Feature or Spike
+  if (sourceType === 'task') {
+    if (targetType === 'feature' || targetType === 'spike') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Tasks can only implement Features or Spikes in Waterfall',
+      suggestion: `Change ${target.id} to a Feature or create a Feature first, then link Task → Feature`,
+    };
+  }
+
+  // Feature → Requirement
+  if (sourceType === 'feature') {
+    if (targetType === 'requirement') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Features can only implement Requirements in Waterfall',
+      suggestion: `Change ${target.id} to a Requirement or create a Requirement first, then link Feature → Requirement`,
+    };
+  }
+
+  // Spike → Requirement
+  if (sourceType === 'spike') {
+    if (targetType === 'requirement') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Spikes can only implement Requirements in Waterfall',
+      suggestion: `Change ${target.id} to a Requirement or create a Requirement first, then link Spike → Requirement`,
+    };
+  }
+
+  // Bug → Requirement or Feature (flexible)
+  if (sourceType === 'bug') {
+    if (targetType === 'requirement' || targetType === 'feature') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Bugs can only implement Requirements or Features in Waterfall',
+      suggestion: `Use "relates-to" for Bug → ${targetType} relationships, or create Requirement/Feature first`,
+    };
+  }
+
+  // Test → Requirement or Feature (flexible)
+  if (sourceType === 'test') {
+    if (targetType === 'requirement' || targetType === 'feature') {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: 'Tests can only implement Requirements or Features in Waterfall',
+      suggestion: `Use "tested-by" relationship or create Requirement/Feature first`,
+    };
+  }
+
+  // Requirement cannot implement anything (top-level)
+  if (sourceType === 'requirement') {
+    return {
+      valid: false,
+      error: 'Requirements are top-level items and cannot implement other items',
+      suggestion: 'Consider using "relates-to" to link Requirements together',
+    };
+  }
+
+  return {
+    valid: false,
+    error: `Invalid Waterfall relationship: ${sourceType} → ${targetType}`,
+    suggestion: 'Check Waterfall hierarchy: Requirement → Feature|Spike → Task',
+  };
+}

package/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/index.js"), exports);
+__exportStar(require("./schemas/index.js"), exports);
+__exportStar(require("./utils/index.js"), exports);
+__exportStar(require("./core/index.js"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC;AACjC,qDAAmC;AACnC,mDAAiC;AACjC,kDAAgC"}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types/index.js';
+export * from './schemas/index.js';
+export * from './utils/index.js';
+export * from './core/index.js';

package/src/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6BAAwB;AAExB,oCAAoC;AACpC,+CAA6B;AAE7B;;GAEG;AACU,QAAA,WAAW,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGpE;;;;;GAKG;AACU,QAAA,QAAQ,GAAG,OAAC,CAAC,IAAI,CAAC;IAC7B,MAAM;IACN,OAAO;IACP,MAAM;IACN,aAAa;IACb,SAAS;IACT,KAAK;IACL,OAAO;IACP,MAAM;CACP,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,UAAU,GAAG,OAAC,CAAC,IAAI,CAAC;IAC/B,OAAO;IACP,SAAS;IACT,aAAa;IACb,QAAQ;IACR,MAAM;IACN,UAAU;IACV,SAAS;IACT,WAAW;CACZ,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,QAAQ,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAGtE;;;;;;GAMG;AACU,QAAA,kBAAkB,GAAG,OAAC,CAAC,IAAI,CAAC;IACvC,kBAAkB,EAAE,eAAe;IACnC,sBAAsB,EAAE,eAAe;IACvC,sBAAsB,EAAE,eAAe;IACvC,0BAA0B,EAAE,gBAAgB;CAC7C,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,YAAY,GAAG,OAAC,CAAC,IAAI,CAAC;IACjC,YAAY;IACZ,gBAAgB;IAChB,WAAW;IACX,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,eAAe;CAChB,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,WAAW,GAAG,OAAC;KACzB,MAAM,CAAC;IACN,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,gBAAgB,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IACrC,WAAW,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAChC,KAAK,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAC3B,YAAY,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IACjC,YAAY,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IACjC,YAAY,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IACjC,aAAa,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAClC,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,eAAe,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;CACrC,CAAC;KACD,OAAO,CAAC;IACP,UAAU,EAAE,EAAE;IACd,gBAAgB,EAAE,EAAE;IACpB,WAAW,EAAE,EAAE;IACf,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE;IACV,YAAY,EAAE,EAAE;IAChB,YAAY,EAAE,EAAE;IAChB,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,EAAE;IACjB,UAAU,EAAE,EAAE;IACd,eAAe,EAAE,EAAE;CACpB,CAAC,CAAC;AAGL;;GAEG;AACU,QAAA,SAAS,GAAG,OAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oDAAoD,CAAC;IAC1E,IAAI,EAAE,gBAAQ;IACd,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACvC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACjC,MAAM,EAAE,kBAAU,CAAC,OAAO,CAAC,OAAO,CAAC;IACnC,QAAQ,EAAE,gBAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC;IACpC,UAAU,EAAE,0BAAkB,CAAC,QAAQ,EAAE;IACzC,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE;IACvC,cAAc,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC/C,YAAY,EAAE,mBAAW;IACzB,IAAI,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACvC,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,iBAAS,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACvC,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACxD,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;IACpC,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE;IACxB,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,QAAQ,EAAE,OAAC;SACR,MAAM,CAAC;QACN,WAAW,EAAE,mBAAW,CAAC,OAAO,CAAC,OAAO,CAAC;QACzC,cAAc,EAAE,OAAC,CAAC,OAAO,EAAE;QAC3B,eAAe,EAAE,OAAC,CAAC,OAAO,EAAE;QAC5B,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE;QAC7C,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,gBAAQ,CAAC;QAC7B,aAAa,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC;KAChD,CAAC;SACD,OAAO,CAAC;QACP,WAAW,EAAE,OAAO;QACpB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,IAAI;QACrB,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC;QAC7D,aAAa,EAAE;YACb,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,MAAM;YACZ,GAAG,EAAE,KAAK;YACV,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,MAAM;SACb;KACF,CAAC;CACL,CAAC,CAAC;AAGH;;GAEG;AACU,QAAA,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,OAAC,CAAC,KAAK,CACZ,OAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;QACd,IAAI,EAAE,gBAAQ;QACd,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,kBAAU;QAClB,QAAQ,EAAE,gBAAQ;QAClB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC,CACH;IACD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACtD,cAAc,EAAE,OAAC;SACd,KAAK,CACJ,OAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;QACd,IAAI,EAAE,gBAAQ;QACd,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;QACjB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAClC,eAAe,EAAE,kBAAU;KAC5B,CAAC,CACH;SACA,OAAO,CAAC,EAAE,CAAC;IACd,KAAK,EAAE,OAAC;SACL,MAAM,CAAC;QACN,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;QACjB,OAAO,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC;QACzC,SAAS,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC;QAC3C,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAChC,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC"}

package/src/schemas/index.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod';
+
+// Re-export project context schemas
+export * from './project.js';
+export * from './relationships.js';
+
+/**
+ * Methodology types
+ */
+export const Methodology = z.enum(['scrum', 'waterfall', 'hybrid']);
+export type Methodology = z.infer<typeof Methodology>;
+
+/**
+ * Item types in devcrumbs system
+ * Scrum: epic, story, task, bug, spike, test
+ * Waterfall: requirement, feature, task, bug, test
+ * Hybrid: all of the above
+ */
+export const ItemType = z.enum([
+  'epic',
+  'story',
+  'task',
+  'requirement',
+  'feature',
+  'bug',
+  'spike',
+  'test',
+]);
+export type ItemType = z.infer<typeof ItemType>;
+
+/**
+ * Item status lifecycle
+ */
+export const ItemStatus = z.enum([
+  'draft',
+  'planned',
+  'in-progress',
+  'review',
+  'done',
+  'obsolete',
+  'blocked',
+  'cancelled',
+]);
+export type ItemStatus = z.infer<typeof ItemStatus>;
+
+/**
+ * Priority levels
+ */
+export const Priority = z.enum(['critical', 'high', 'medium', 'low']);
+export type Priority = z.infer<typeof Priority>;
+
+/**
+ * Eisenhower Matrix quadrants for prioritization
+ * Q1: Urgent + Important = Do First
+ * Q2: Not Urgent + Important = Schedule/Plan
+ * Q3: Urgent + Not Important = Delegate
+ * Q4: Not Urgent + Not Important = Eliminate/Later
+ */
+export const EisenhowerQuadrant = z.enum([
+  'urgent-important', // Q1: Do First
+  'not-urgent-important', // Q2: Schedule
+  'urgent-not-important', // Q3: Delegate
+  'not-urgent-not-important', // Q4: Eliminate
+]);
+export type EisenhowerQuadrant = z.infer<typeof EisenhowerQuadrant>;
+
+/**
+ * Relationship types between items
+ */
+export const RelationType = z.enum([
+  'implements',
+  'implemented-by',
+  'tested-by',
+  'tests',
+  'blocks',
+  'blocked-by',
+  'relates-to',
+  'depends-on',
+  'required-by',
+  'supersedes',
+  'superseded-by',
+]);
+export type RelationType = z.infer<typeof RelationType>;
+
+/**
+ * Linked items structure
+ */
+export const LinkedItems = z
+  .object({
+    implements: z.array(z.string()),
+    'implemented-by': z.array(z.string()),
+    'tested-by': z.array(z.string()),
+    tests: z.array(z.string()),
+    blocks: z.array(z.string()),
+    'blocked-by': z.array(z.string()),
+    'relates-to': z.array(z.string()),
+    'depends-on': z.array(z.string()),
+    'required-by': z.array(z.string()),
+    supersedes: z.array(z.string()),
+    'superseded-by': z.array(z.string()),
+  })
+  .default({
+    implements: [],
+    'implemented-by': [],
+    'tested-by': [],
+    tests: [],
+    blocks: [],
+    'blocked-by': [],
+    'relates-to': [],
+    'depends-on': [],
+    'required-by': [],
+    supersedes: [],
+    'superseded-by': [],
+  });
+export type LinkedItems = z.infer<typeof LinkedItems>;
+
+/**
+ * Git commit reference
+ */
+export const GitCommit = z.object({
+  hash: z.string(),
+  message: z.string(),
+  author: z.string(),
+  timestamp: z.string(),
+  branch: z.string().optional(),
+});
+export type GitCommit = z.infer<typeof GitCommit>;
+
+/**
+ * Core item schema - metadata stored as JSON
+ */
+export const ItemMetadata = z.object({
+  id: z.string().regex(/^(EPIC|STORY|TASK|REQ|FEAT|BUG|SPIKE|TEST)-\d{3,}$/),
+  type: ItemType,
+  category: z.string().default('general'),
+  title: z.string().min(1).max(200),
+  status: ItemStatus.default('draft'),
+  priority: Priority.default('medium'),
+  eisenhower: EisenhowerQuadrant.optional(),
+  superseded_by: z.string().optional(),
+  created: z.string().datetime(),
+  updated: z.string().datetime(),
+  author: z.string().email().optional(),
+  assignee: z.string().email().optional(),
+  affected_paths: z.array(z.string()).default([]),
+  linked_items: LinkedItems,
+  tags: z.array(z.string()).default([]),
+  estimated_effort: z.string().optional(),
+  actual_effort: z.string().optional(),
+  commits: z.array(GitCommit).default([]),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type ItemMetadata = z.infer<typeof ItemMetadata>;
+
+/**
+ * Configuration schema for .devcrumbs/config.json
+ */
+export const DevCrumbsConfig = z.object({
+  version: z.string().default('0.1.0'),
+  project_name: z.string(),
+  project_id: z.string(),
+  created: z.string().datetime(),
+  updated: z.string().datetime(),
+  settings: z
+    .object({
+      methodology: Methodology.default('scrum'),
+      auto_increment: z.boolean(),
+      git_integration: z.boolean(),
+      default_author: z.string().email().optional(),
+      item_types: z.array(ItemType),
+      item_prefixes: z.record(z.string(), z.string()),
+    })
+    .default({
+      methodology: 'scrum',
+      auto_increment: true,
+      git_integration: true,
+      item_types: ['epic', 'story', 'task', 'bug', 'spike', 'test'],
+      item_prefixes: {
+        epic: 'EPIC',
+        story: 'STORY',
+        task: 'TASK',
+        bug: 'BUG',
+        spike: 'SPIKE',
+        test: 'TEST',
+      },
+    }),
+});
+export type DevCrumbsConfig = z.infer<typeof DevCrumbsConfig>;
+
+/**
+ * Index schema for .devcrumbs/index.json
+ */
+export const DevCrumbsIndex = z.object({
+  items: z.array(
+    z.object({
+      id: z.string(),
+      type: ItemType,
+      title: z.string(),
+      status: ItemStatus,
+      priority: Priority,
+      updated: z.string().datetime(),
+    })
+  ),
+  last_updated: z.string().datetime(),
+  counters: z.record(z.string(), z.number()).default({}),
+  archived_items: z
+    .array(
+      z.object({
+        id: z.string(),
+        type: ItemType,
+        title: z.string(),
+        archived_at: z.string().datetime(),
+        original_status: ItemStatus,
+      })
+    )
+    .default([]),
+  stats: z
+    .object({
+      total: z.number(),
+      by_type: z.record(z.string(), z.number()),
+      by_status: z.record(z.string(), z.number()),
+      archived: z.number().optional(),
+    })
+    .optional(),
+});
+export type DevCrumbsIndex = z.infer<typeof DevCrumbsIndex>;

package/src/schemas/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["project.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB;;GAEG;AACU,QAAA,qBAAqB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IACzC,UAAU,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC;IAC5C,QAAQ,EAAE,OAAC,CAAC,KAAK,CACf,OAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;QAChB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;QACnB,YAAY,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;KAC7C,CAAC,CACH;IACD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE;CACzB,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,qBAAqB,GAAG,0BAAkB,CAAC,MAAM,CAAC;IAC7D,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE;IACxB,gBAAgB,EAAE,OAAC,CAAC,KAAK,CACvB,OAAC,CAAC,MAAM,CAAC;QACP,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;QACjB,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;QACpB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACjC,CAAC,CACH;IACD,uBAAuB,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC;CAC1D,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,iBAAiB,GAAG,6BAAqB,CAAC,MAAM,CAAC;IAC5D,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC5B,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC5B,YAAY,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC5C,cAAc,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C,QAAQ,EAAE,6BAAqB;IAC/B,KAAK,EAAE,0BAAkB;IACzB,QAAQ,EAAE,6BAAqB,CAAC,QAAQ,EAAE;IAC1C,IAAI,EAAE,yBAAiB,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC"}

package/src/schemas/project.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+
+/**
+ * Schema for PROJECT.md metadata section
+ */
+export const ProjectMetadataSchema = z.object({
+  name: z.string(),
+  created: z.string().datetime(),
+  last_updated: z.string().datetime(),
+  version: z.string(),
+});
+
+/**
+ * Schema for Quick Context (< 5K tokens target)
+ */
+export const QuickContextSchema = z.object({
+  tech_stack: z.record(z.string(), z.string()),
+  packages: z.array(
+    z.object({
+      name: z.string(),
+      purpose: z.string(),
+      dependencies: z.array(z.string()).optional(),
+    })
+  ),
+  project_type: z.string(),
+});
+
+/**
+ * Schema for Standard Context (< 20K tokens target)
+ */
+export const StandardContextSchema = QuickContextSchema.extend({
+  architecture: z.string(),
+  design_decisions: z.array(
+    z.object({
+      title: z.string(),
+      decision: z.string(),
+      rationale: z.string(),
+      tradeoffs: z.string().optional(),
+    })
+  ),
+  module_responsibilities: z.record(z.string(), z.string()),
+});
+
+/**
+ * Schema for Deep Context (< 50K tokens target)
+ */
+export const DeepContextSchema = StandardContextSchema.extend({
+  coding_standards: z.string(),
+  testing_strategy: z.string(),
+  known_issues: z.array(z.string()).optional(),
+  technical_debt: z.array(z.string()).optional(),
+});
+
+/**
+ * Complete PROJECT.md structure
+ */
+export const ProjectContextSchema = z.object({
+  metadata: ProjectMetadataSchema,
+  quick: QuickContextSchema,
+  standard: StandardContextSchema.optional(),
+  deep: DeepContextSchema.optional(),
+});
+
+export type ProjectMetadata = z.infer<typeof ProjectMetadataSchema>;
+export type QuickContext = z.infer<typeof QuickContextSchema>;
+export type StandardContext = z.infer<typeof StandardContextSchema>;
+export type DeepContext = z.infer<typeof DeepContextSchema>;
+export type ProjectContext = z.infer<typeof ProjectContextSchema>;
+
+/**
+ * Context level type
+ */
+export type ContextLevel = 'quick' | 'standard' | 'deep';

package/src/schemas/relationships.ts

@@ -0,0 +1,48 @@
+/**
+ * Relationship type definitions
+ * Separates hierarchy relationships (strict validation) from flexible relationships (no validation)
+ */
+
+/**
+ * Hierarchy relationships enforce parent-child rules
+ * - implements/implemented-by: Epic → Story → Task structure
+ */
+export const HIERARCHY_RELATIONSHIPS = ['implements', 'implemented-by'] as const;
+
+/**
+ * Flexible relationships allow connections between any item types
+ * - relates-to: Generic association
+ * - blocks/blocked-by: Blocking dependencies
+ * - depends-on/required-by: Technical dependencies
+ * - tested-by/tests: Testing relationships
+ * - supersedes/superseded-by: Version/replacement tracking
+ */
+export const FLEXIBLE_RELATIONSHIPS = [
+  'relates-to',
+  'blocks',
+  'blocked-by',
+  'depends-on',
+  'required-by',
+  'tested-by',
+  'tests',
+  'supersedes',
+  'superseded-by',
+] as const;
+
+export type HierarchyRelation = (typeof HIERARCHY_RELATIONSHIPS)[number];
+export type FlexibleRelation = (typeof FLEXIBLE_RELATIONSHIPS)[number];
+export type RelationType = HierarchyRelation | FlexibleRelation;
+
+/**
+ * Check if a relation type requires hierarchy validation
+ */
+export function isHierarchyRelation(relationType: string): relationType is HierarchyRelation {
+  return HIERARCHY_RELATIONSHIPS.includes(relationType as HierarchyRelation);
+}
+
+/**
+ * Check if a relation type is flexible (no validation)
+ */
+export function isFlexibleRelation(relationType: string): relationType is FlexibleRelation {
+  return FLEXIBLE_RELATIONSHIPS.includes(relationType as FlexibleRelation);
+}

package/src/types/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["commands.ts"],"names":[],"mappings":";;;AAEA;;GAEG;AACU,QAAA,cAAc,GAA6B;IACtD,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,aAAa;IAClB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACJ,CAAC"}