@specforge/cli 0.1.0

package/dist/patterns/inheritance.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Pattern Inheritance Resolver
+ *
+ * Resolves the complete pattern inheritance chain for tickets:
+ * Specification → Epic → Ticket
+ *
+ * Later values override earlier ones. Arrays are concatenated.
+ *
+ * @see MCI-030-05-pattern-inheritance-resolver
+ */
+import type { SpecificationCodeStandards, ReturnTypes, NamingConventions, EpicSharedPatterns, EpicCommonFiles } from '../types/index.js';
+/**
+ * Fully resolved patterns for a ticket
+ *
+ * Combines patterns from specification, epic, and ticket levels
+ * with proper override semantics.
+ */
+export interface ResolvedPatterns {
+    /** All imports (spec.commonImports + epic.additionalImports) */
+    imports: string[];
+    /** Merged patterns (spec → epic → ticket, later wins) */
+    patterns: Record<string, string>;
+    /** Return types from specification */
+    returnTypes: ReturnTypes;
+    /** Common files from epic */
+    commonFiles: EpicCommonFiles;
+    /** Naming conventions from specification */
+    naming: NamingConventions;
+    /** Source information for debugging */
+    sources: {
+        specificationId: string;
+        epicId: string;
+        ticketId: string;
+    };
+}
+/**
+ * Override information for a single pattern key
+ */
+export interface PatternOverride {
+    /** Pattern key */
+    key: string;
+    /** Value from specification (if defined) */
+    specValue?: string;
+    /** Value from epic (if defined) */
+    epicValue?: string;
+    /** Value from ticket (if defined) */
+    ticketValue?: string;
+    /** Which level the final value came from */
+    resolvedFrom: 'specification' | 'epic' | 'ticket';
+}
+/**
+ * Detailed override report for debugging
+ */
+export interface PatternOverrideReport {
+    /** Final merged patterns */
+    final: Record<string, string>;
+    /** Details about each override */
+    overrides: PatternOverride[];
+}
+/**
+ * Input data for pattern resolution
+ */
+export interface PatternResolutionInput {
+    /** Ticket ID */
+    ticketId: string;
+    /** Specification data */
+    specification: {
+        id: string;
+        codeStandards?: SpecificationCodeStandards | null;
+        commonImports?: string[] | null;
+        returnTypes?: ReturnTypes | null;
+    };
+    /** Epic data */
+    epic: {
+        id: string;
+        sharedPatterns?: EpicSharedPatterns | null;
+        additionalImports?: string[] | null;
+        commonFiles?: EpicCommonFiles | null;
+    };
+    /** Ticket data (optional, for override information) */
+    ticket?: {
+        id: string;
+        technicalDetails?: {
+            patterns?: Record<string, string>;
+        } | null;
+    };
+}
+/**
+ * Flatten SpecificationCodeStandards to a flat Record
+ *
+ * Extracts all pattern-related fields from code standards into a
+ * flat key-value structure for easy merging.
+ *
+ * @param standards - Specification code standards object
+ * @returns Flat record of pattern key-value pairs
+ */
+export declare function flattenCodeStandards(standards: SpecificationCodeStandards | null | undefined): Record<string, string>;
+/**
+ * Flatten EpicSharedPatterns to a flat Record
+ *
+ * Extracts all pattern fields from epic shared patterns into a
+ * flat key-value structure for merging.
+ *
+ * @param patterns - Epic shared patterns object
+ * @returns Flat record of pattern key-value pairs
+ */
+export declare function flattenSharedPatterns(patterns: EpicSharedPatterns | null | undefined): Record<string, string>;
+/**
+ * Resolve inherited patterns for a ticket
+ *
+ * Merges patterns from the specification → epic → ticket chain.
+ * Later values override earlier ones. Arrays are concatenated.
+ *
+ * @param input - Pattern resolution input with spec, epic, and ticket data
+ * @returns Fully resolved patterns
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolvePatterns({
+ *   ticketId: 'ticket-123',
+ *   specification: {
+ *     id: 'spec-1',
+ *     codeStandards: { errorHandling: 'Result<T>' },
+ *     commonImports: ['import { z } from "zod"']
+ *   },
+ *   epic: {
+ *     id: 'epic-1',
+ *     sharedPatterns: { errorHandling: 'AppError' },
+ *     additionalImports: ['import { api } from "@/lib/api"']
+ *   }
+ * });
+ *
+ * // resolved.patterns.errorHandling === 'AppError' (epic overrides spec)
+ * // resolved.imports contains both spec and epic imports
+ * ```
+ */
+export declare function resolvePatterns(input: PatternResolutionInput): ResolvedPatterns;
+/**
+ * Get detailed override information for debugging
+ *
+ * Shows where each pattern value came from in the inheritance chain.
+ * Useful for debugging and understanding pattern resolution.
+ *
+ * @param input - Pattern resolution input
+ * @returns Override report with final values and source information
+ *
+ * @example
+ * ```typescript
+ * const report = getPatternOverrides(input);
+ *
+ * for (const override of report.overrides) {
+ *   if (override.resolvedFrom === 'epic') {
+ *     console.log(`${override.key}: Epic overrides spec`);
+ *   }
+ * }
+ * ```
+ */
+export declare function getPatternOverrides(input: PatternResolutionInput): PatternOverrideReport;
+/**
+ * Resolve patterns with caching for performance
+ *
+ * Uses an in-memory cache to avoid repeated resolution for the same ticket.
+ * Cache entries expire after TTL (default 1 minute).
+ *
+ * @param input - Pattern resolution input
+ * @param ttl - Cache TTL in milliseconds (default: 60000)
+ * @returns Resolved patterns (may be cached)
+ */
+export declare function resolvePatternsWithCache(input: PatternResolutionInput, ttl?: number): ResolvedPatterns;
+/**
+ * Clear cache for a specific ticket
+ *
+ * Call this after updating a ticket's patterns.
+ *
+ * @param ticketId - Ticket ID to invalidate
+ */
+export declare function invalidatePatternCache(ticketId: string): void;
+/**
+ * Clear all pattern caches
+ *
+ * Call this after updating specification or epic patterns,
+ * as these changes affect multiple tickets.
+ */
+export declare function invalidateAllPatternCaches(): void;
+/**
+ * Get current cache size
+ *
+ * Useful for monitoring and debugging.
+ *
+ * @returns Number of cached entries
+ */
+export declare function getPatternCacheSize(): number;
+//# sourceMappingURL=inheritance.d.ts.map

package/dist/patterns/inheritance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inheritance.d.ts","sourceRoot":"","sources":["../../src/patterns/inheritance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,0BAA0B,EAC1B,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAM3B;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,sCAAsC;IACtC,WAAW,EAAE,WAAW,CAAC;IAEzB,6BAA6B;IAC7B,WAAW,EAAE,eAAe,CAAC;IAE7B,4CAA4C;IAC5C,MAAM,EAAE,iBAAiB,CAAC;IAE1B,uCAAuC;IACvC,OAAO,EAAE;QACP,eAAe,EAAE,MAAM,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,YAAY,EAAE,eAAe,GAAG,MAAM,GAAG,QAAQ,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,kCAAkC;IAClC,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,aAAa,EAAE;QACb,EAAE,EAAE,MAAM,CAAC;QACX,aAAa,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;QAClD,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAChC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;KAClC,CAAC;IACF,gBAAgB;IAChB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,cAAc,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;QAC3C,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACpC,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;KACtC,CAAC;IACF,uDAAuD;IACvD,MAAM,CAAC,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,gBAAgB,CAAC,EAAE;YACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SACnC,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACvD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAC9C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,gBAAgB,CAgC/E;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,sBAAsB,GAAG,qBAAqB,CA4CxF;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,sBAAsB,EAC7B,GAAG,GAAE,MAA0B,GAC9B,gBAAgB,CAgBlB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/patterns/inheritance.js

@@ -0,0 +1,125 @@
+function flattenCodeStandards(standards) {
+  if (!standards) return {};
+  const result = {};
+  if (standards.language) result.language = standards.language;
+  if (standards.asyncPattern) result.asyncPattern = standards.asyncPattern;
+  if (standards.errorHandling) result.errorHandling = standards.errorHandling;
+  if (standards.documentation) result.documentation = standards.documentation;
+  if (standards.testing) result.testing = standards.testing;
+  if (standards.stateManagement) result.stateManagement = standards.stateManagement;
+  if (standards.apiPattern) result.apiPattern = standards.apiPattern;
+  if (standards.logging) result.logging = standards.logging;
+  if (standards.validation) result.validation = standards.validation;
+  if (standards.custom) {
+    Object.assign(result, standards.custom);
+  }
+  return result;
+}
+function flattenSharedPatterns(patterns) {
+  if (!patterns) return {};
+  const result = {};
+  if (patterns.errorHandling) result.errorHandling = patterns.errorHandling;
+  if (patterns.returnType) result.returnType = patterns.returnType;
+  if (patterns.actionPrefix) result.actionPrefix = patterns.actionPrefix;
+  if (patterns.stateSlice) result.stateSlice = patterns.stateSlice;
+  if (patterns.apiBasePath) result.apiBasePath = patterns.apiBasePath;
+  if (patterns.componentFolder) result.componentFolder = patterns.componentFolder;
+  if (patterns.hookPattern) result.hookPattern = patterns.hookPattern;
+  if (patterns.custom) {
+    Object.assign(result, patterns.custom);
+  }
+  return result;
+}
+function resolvePatterns(input) {
+  const { ticketId, specification, epic, ticket } = input;
+  const specImports = specification.commonImports ?? [];
+  const epicImports = epic.additionalImports ?? [];
+  const imports = [.../* @__PURE__ */ new Set([...specImports, ...epicImports])];
+  const specPatterns = flattenCodeStandards(specification.codeStandards);
+  const epicPatterns = flattenSharedPatterns(epic.sharedPatterns);
+  const ticketPatterns = ticket?.technicalDetails?.patterns ?? {};
+  const patterns = {
+    ...specPatterns,
+    ...epicPatterns,
+    ...ticketPatterns
+  };
+  return {
+    imports,
+    patterns,
+    returnTypes: specification.returnTypes ?? {},
+    commonFiles: epic.commonFiles ?? {},
+    naming: specification.codeStandards?.naming ?? {},
+    sources: {
+      specificationId: specification.id,
+      epicId: epic.id,
+      ticketId: ticket?.id ?? ticketId
+    }
+  };
+}
+function getPatternOverrides(input) {
+  const { specification, epic, ticket } = input;
+  const specPatterns = flattenCodeStandards(specification.codeStandards);
+  const epicPatterns = flattenSharedPatterns(epic.sharedPatterns);
+  const ticketPatterns = ticket?.technicalDetails?.patterns ?? {};
+  const allKeys = /* @__PURE__ */ new Set([
+    ...Object.keys(specPatterns),
+    ...Object.keys(epicPatterns),
+    ...Object.keys(ticketPatterns)
+  ]);
+  const overrides = Array.from(allKeys).map((key) => {
+    const specValue = specPatterns[key];
+    const epicValue = epicPatterns[key];
+    const ticketValue = ticketPatterns[key];
+    let resolvedFrom;
+    if (ticketValue !== void 0) {
+      resolvedFrom = "ticket";
+    } else if (epicValue !== void 0) {
+      resolvedFrom = "epic";
+    } else {
+      resolvedFrom = "specification";
+    }
+    return { key, specValue, epicValue, ticketValue, resolvedFrom };
+  });
+  overrides.sort((a, b) => a.key.localeCompare(b.key));
+  const final = {
+    ...specPatterns,
+    ...epicPatterns,
+    ...ticketPatterns
+  };
+  return { final, overrides };
+}
+const patternCache = /* @__PURE__ */ new Map();
+const DEFAULT_CACHE_TTL = 6e4;
+function resolvePatternsWithCache(input, ttl = DEFAULT_CACHE_TTL) {
+  const cacheKey = input.ticketId;
+  const cached = patternCache.get(cacheKey);
+  if (cached && cached.expiry > Date.now()) {
+    return cached.patterns;
+  }
+  const patterns = resolvePatterns(input);
+  patternCache.set(cacheKey, {
+    patterns,
+    expiry: Date.now() + ttl
+  });
+  return patterns;
+}
+function invalidatePatternCache(ticketId) {
+  patternCache.delete(ticketId);
+}
+function invalidateAllPatternCaches() {
+  patternCache.clear();
+}
+function getPatternCacheSize() {
+  return patternCache.size;
+}
+export {
+  flattenCodeStandards,
+  flattenSharedPatterns,
+  getPatternCacheSize,
+  getPatternOverrides,
+  invalidateAllPatternCaches,
+  invalidatePatternCache,
+  resolvePatterns,
+  resolvePatternsWithCache
+};
+//# sourceMappingURL=inheritance.js.map

package/dist/patterns/inheritance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/patterns/inheritance.ts"],"sourcesContent":["/**\n * Pattern Inheritance Resolver\n *\n * Resolves the complete pattern inheritance chain for tickets:\n * Specification → Epic → Ticket\n *\n * Later values override earlier ones. Arrays are concatenated.\n *\n * @see MCI-030-05-pattern-inheritance-resolver\n */\n\nimport type {\n  SpecificationCodeStandards,\n  ReturnTypes,\n  NamingConventions,\n  EpicSharedPatterns,\n  EpicCommonFiles,\n} from '../types/index.js';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Fully resolved patterns for a ticket\n *\n * Combines patterns from specification, epic, and ticket levels\n * with proper override semantics.\n */\nexport interface ResolvedPatterns {\n  /** All imports (spec.commonImports + epic.additionalImports) */\n  imports: string[];\n\n  /** Merged patterns (spec → epic → ticket, later wins) */\n  patterns: Record<string, string>;\n\n  /** Return types from specification */\n  returnTypes: ReturnTypes;\n\n  /** Common files from epic */\n  commonFiles: EpicCommonFiles;\n\n  /** Naming conventions from specification */\n  naming: NamingConventions;\n\n  /** Source information for debugging */\n  sources: {\n    specificationId: string;\n    epicId: string;\n    ticketId: string;\n  };\n}\n\n/**\n * Override information for a single pattern key\n */\nexport interface PatternOverride {\n  /** Pattern key */\n  key: string;\n  /** Value from specification (if defined) */\n  specValue?: string;\n  /** Value from epic (if defined) */\n  epicValue?: string;\n  /** Value from ticket (if defined) */\n  ticketValue?: string;\n  /** Which level the final value came from */\n  resolvedFrom: 'specification' | 'epic' | 'ticket';\n}\n\n/**\n * Detailed override report for debugging\n */\nexport interface PatternOverrideReport {\n  /** Final merged patterns */\n  final: Record<string, string>;\n  /** Details about each override */\n  overrides: PatternOverride[];\n}\n\n/**\n * Input data for pattern resolution\n */\nexport interface PatternResolutionInput {\n  /** Ticket ID */\n  ticketId: string;\n  /** Specification data */\n  specification: {\n    id: string;\n    codeStandards?: SpecificationCodeStandards | null;\n    commonImports?: string[] | null;\n    returnTypes?: ReturnTypes | null;\n  };\n  /** Epic data */\n  epic: {\n    id: string;\n    sharedPatterns?: EpicSharedPatterns | null;\n    additionalImports?: string[] | null;\n    commonFiles?: EpicCommonFiles | null;\n  };\n  /** Ticket data (optional, for override information) */\n  ticket?: {\n    id: string;\n    technicalDetails?: {\n      patterns?: Record<string, string>;\n    } | null;\n  };\n}\n\n// =============================================================================\n// Pattern Flattening Helpers\n// =============================================================================\n\n/**\n * Flatten SpecificationCodeStandards to a flat Record\n *\n * Extracts all pattern-related fields from code standards into a\n * flat key-value structure for easy merging.\n *\n * @param standards - Specification code standards object\n * @returns Flat record of pattern key-value pairs\n */\nexport function flattenCodeStandards(\n  standards: SpecificationCodeStandards | null | undefined\n): Record<string, string> {\n  if (!standards) return {};\n\n  const result: Record<string, string> = {};\n\n  // Extract all standard fields\n  if (standards.language) result.language = standards.language;\n  if (standards.asyncPattern) result.asyncPattern = standards.asyncPattern;\n  if (standards.errorHandling) result.errorHandling = standards.errorHandling;\n  if (standards.documentation) result.documentation = standards.documentation;\n  if (standards.testing) result.testing = standards.testing;\n  if (standards.stateManagement) result.stateManagement = standards.stateManagement;\n  if (standards.apiPattern) result.apiPattern = standards.apiPattern;\n  if (standards.logging) result.logging = standards.logging;\n  if (standards.validation) result.validation = standards.validation;\n\n  // Include custom standards\n  if (standards.custom) {\n    Object.assign(result, standards.custom);\n  }\n\n  return result;\n}\n\n/**\n * Flatten EpicSharedPatterns to a flat Record\n *\n * Extracts all pattern fields from epic shared patterns into a\n * flat key-value structure for merging.\n *\n * @param patterns - Epic shared patterns object\n * @returns Flat record of pattern key-value pairs\n */\nexport function flattenSharedPatterns(\n  patterns: EpicSharedPatterns | null | undefined\n): Record<string, string> {\n  if (!patterns) return {};\n\n  const result: Record<string, string> = {};\n\n  // Extract all standard fields\n  if (patterns.errorHandling) result.errorHandling = patterns.errorHandling;\n  if (patterns.returnType) result.returnType = patterns.returnType;\n  if (patterns.actionPrefix) result.actionPrefix = patterns.actionPrefix;\n  if (patterns.stateSlice) result.stateSlice = patterns.stateSlice;\n  if (patterns.apiBasePath) result.apiBasePath = patterns.apiBasePath;\n  if (patterns.componentFolder) result.componentFolder = patterns.componentFolder;\n  if (patterns.hookPattern) result.hookPattern = patterns.hookPattern;\n\n  // Include custom patterns\n  if (patterns.custom) {\n    Object.assign(result, patterns.custom);\n  }\n\n  return result;\n}\n\n// =============================================================================\n// Main Resolution Function\n// =============================================================================\n\n/**\n * Resolve inherited patterns for a ticket\n *\n * Merges patterns from the specification → epic → ticket chain.\n * Later values override earlier ones. Arrays are concatenated.\n *\n * @param input - Pattern resolution input with spec, epic, and ticket data\n * @returns Fully resolved patterns\n *\n * @example\n * ```typescript\n * const resolved = resolvePatterns({\n *   ticketId: 'ticket-123',\n *   specification: {\n *     id: 'spec-1',\n *     codeStandards: { errorHandling: 'Result<T>' },\n *     commonImports: ['import { z } from \"zod\"']\n *   },\n *   epic: {\n *     id: 'epic-1',\n *     sharedPatterns: { errorHandling: 'AppError' },\n *     additionalImports: ['import { api } from \"@/lib/api\"']\n *   }\n * });\n *\n * // resolved.patterns.errorHandling === 'AppError' (epic overrides spec)\n * // resolved.imports contains both spec and epic imports\n * ```\n */\nexport function resolvePatterns(input: PatternResolutionInput): ResolvedPatterns {\n  const { ticketId, specification, epic, ticket } = input;\n\n  // Concatenate imports (spec + epic, deduplicated)\n  const specImports = specification.commonImports ?? [];\n  const epicImports = epic.additionalImports ?? [];\n  const imports = [...new Set([...specImports, ...epicImports])];\n\n  // Flatten patterns from each level\n  const specPatterns = flattenCodeStandards(specification.codeStandards);\n  const epicPatterns = flattenSharedPatterns(epic.sharedPatterns);\n  const ticketPatterns = ticket?.technicalDetails?.patterns ?? {};\n\n  // Merge patterns (later overrides earlier)\n  const patterns = {\n    ...specPatterns,\n    ...epicPatterns,\n    ...ticketPatterns,\n  };\n\n  return {\n    imports,\n    patterns,\n    returnTypes: specification.returnTypes ?? {},\n    commonFiles: epic.commonFiles ?? {},\n    naming: specification.codeStandards?.naming ?? {},\n    sources: {\n      specificationId: specification.id,\n      epicId: epic.id,\n      ticketId: ticket?.id ?? ticketId,\n    },\n  };\n}\n\n// =============================================================================\n// Override Tracking\n// =============================================================================\n\n/**\n * Get detailed override information for debugging\n *\n * Shows where each pattern value came from in the inheritance chain.\n * Useful for debugging and understanding pattern resolution.\n *\n * @param input - Pattern resolution input\n * @returns Override report with final values and source information\n *\n * @example\n * ```typescript\n * const report = getPatternOverrides(input);\n *\n * for (const override of report.overrides) {\n *   if (override.resolvedFrom === 'epic') {\n *     console.log(`${override.key}: Epic overrides spec`);\n *   }\n * }\n * ```\n */\nexport function getPatternOverrides(input: PatternResolutionInput): PatternOverrideReport {\n  const { specification, epic, ticket } = input;\n\n  const specPatterns = flattenCodeStandards(specification.codeStandards);\n  const epicPatterns = flattenSharedPatterns(epic.sharedPatterns);\n  const ticketPatterns = ticket?.technicalDetails?.patterns ?? {};\n\n  // Get all unique keys\n  const allKeys = new Set([\n    ...Object.keys(specPatterns),\n    ...Object.keys(epicPatterns),\n    ...Object.keys(ticketPatterns),\n  ]);\n\n  // Build override information for each key\n  const overrides: PatternOverride[] = Array.from(allKeys).map((key) => {\n    const specValue = specPatterns[key];\n    const epicValue = epicPatterns[key];\n    const ticketValue = ticketPatterns[key];\n\n    // Determine which level the value came from\n    let resolvedFrom: 'specification' | 'epic' | 'ticket';\n    if (ticketValue !== undefined) {\n      resolvedFrom = 'ticket';\n    } else if (epicValue !== undefined) {\n      resolvedFrom = 'epic';\n    } else {\n      resolvedFrom = 'specification';\n    }\n\n    return { key, specValue, epicValue, ticketValue, resolvedFrom };\n  });\n\n  // Sort by key for consistent output\n  overrides.sort((a, b) => a.key.localeCompare(b.key));\n\n  // Build final merged patterns\n  const final = {\n    ...specPatterns,\n    ...epicPatterns,\n    ...ticketPatterns,\n  };\n\n  return { final, overrides };\n}\n\n// =============================================================================\n// Caching\n// =============================================================================\n\n/** Cache entry with expiry */\ninterface CacheEntry {\n  patterns: ResolvedPatterns;\n  expiry: number;\n}\n\n/** Pattern resolution cache */\nconst patternCache = new Map<string, CacheEntry>();\n\n/** Default cache TTL (1 minute) */\nconst DEFAULT_CACHE_TTL = 60000;\n\n/**\n * Resolve patterns with caching for performance\n *\n * Uses an in-memory cache to avoid repeated resolution for the same ticket.\n * Cache entries expire after TTL (default 1 minute).\n *\n * @param input - Pattern resolution input\n * @param ttl - Cache TTL in milliseconds (default: 60000)\n * @returns Resolved patterns (may be cached)\n */\nexport function resolvePatternsWithCache(\n  input: PatternResolutionInput,\n  ttl: number = DEFAULT_CACHE_TTL\n): ResolvedPatterns {\n  const cacheKey = input.ticketId;\n  const cached = patternCache.get(cacheKey);\n\n  if (cached && cached.expiry > Date.now()) {\n    return cached.patterns;\n  }\n\n  const patterns = resolvePatterns(input);\n\n  patternCache.set(cacheKey, {\n    patterns,\n    expiry: Date.now() + ttl,\n  });\n\n  return patterns;\n}\n\n/**\n * Clear cache for a specific ticket\n *\n * Call this after updating a ticket's patterns.\n *\n * @param ticketId - Ticket ID to invalidate\n */\nexport function invalidatePatternCache(ticketId: string): void {\n  patternCache.delete(ticketId);\n}\n\n/**\n * Clear all pattern caches\n *\n * Call this after updating specification or epic patterns,\n * as these changes affect multiple tickets.\n */\nexport function invalidateAllPatternCaches(): void {\n  patternCache.clear();\n}\n\n/**\n * Get current cache size\n *\n * Useful for monitoring and debugging.\n *\n * @returns Number of cached entries\n */\nexport function getPatternCacheSize(): number {\n  return patternCache.size;\n}\n"],"mappings":"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","names":[]}

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SpecForge MCP Server
+ *
+ * MCP (Model Context Protocol) server implementation using stdio transport.
+ * Provides tools for AI agents to interact with SpecForge projects.
+ *
+ * M9: the boot-time `set_working_context` mechanism was removed — that backend
+ * op no longer exists. Project/spec/session identity is injected per-call from
+ * `.specforge/config.json` by the tool handlers (M9.6b), and the agent reads
+ * the M8 envelope (interpreted in `handleToolCall`), TOON-encoded on the wire.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ApiClient } from './client/api-client.js';
+import { McpConfig } from './config/index.js';
+import type { OutputFormat } from './cli/config/types.js';
+/**
+ * Dispatch a tool call and frame the result for the MCP wire.
+ *
+ * The wire encoding follows the resolved `mcpOutputFormat` (M9.6c) — TOON by
+ * default, JSON when the project/global/env config selects it — on both the
+ * success and error paths. Exposed for direct testing without spinning up the
+ * full MCP transport.
+ */
+export declare function dispatchToolCall(apiClient: ApiClient, toolName: string, args: Record<string, unknown>, debug: boolean, format?: OutputFormat): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+/**
+ * Create and configure the MCP server
+ *
+ * @param config - Configuration for the server
+ * @returns Configured MCP Server instance
+ */
+export declare function createServer(config: McpConfig): Promise<Server>;
+/**
+ * Start the MCP server with stdio transport
+ *
+ * @param server - The MCP server instance
+ */
+export declare function startServer(server: Server): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAMnE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAY1D;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,OAAO,EACd,MAAM,GAAE,YAAqB,GAC5B,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAgBhF;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CrE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B/D"}

package/dist/server.js

@@ -0,0 +1,91 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { ApiClient } from "./client/api-client.js";
+import { getTools, handleToolCall } from "./tools/index.js";
+import { formatToon } from "./lib/format.js";
+function encodeMcp(value, format) {
+  return format === "json" ? JSON.stringify(value, null, 2) : formatToon(value);
+}
+const VERSION = "1.0.0";
+async function dispatchToolCall(apiClient, toolName, args, debug, format = "toon") {
+  try {
+    const result = await handleToolCall(apiClient, toolName, args, debug);
+    return {
+      content: [{ type: "text", text: encodeMcp(result, format) }]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (debug) {
+      console.error(`[DEBUG] Tool ${toolName} failed:`, message);
+    }
+    return {
+      content: [{ type: "text", text: encodeMcp({ error: message }, format) }],
+      isError: true
+    };
+  }
+}
+async function createServer(config) {
+  const apiClient = new ApiClient(config);
+  const server = new Server(
+    {
+      name: "specforge",
+      version: VERSION
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    if (config.debug) {
+      console.error("[DEBUG] ListTools request received");
+    }
+    const tools = getTools();
+    if (config.debug) {
+      console.error(`[DEBUG] Returning ${tools.length} tools`);
+    }
+    return { tools };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const argsRecord = args || {};
+    if (config.debug) {
+      console.error("[DEBUG] CallTool request:", {
+        name,
+        args: JSON.stringify(args)
+      });
+    }
+    return dispatchToolCall(apiClient, name, argsRecord, config.debug, config.mcpOutputFormat ?? "toon");
+  });
+  return server;
+}
+async function startServer(server) {
+  const transport = new StdioServerTransport();
+  const shutdown = async () => {
+    console.error("[INFO] Shutting down MCP server...");
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  process.on("uncaughtException", (error) => {
+    console.error("[ERROR] Uncaught exception:", error);
+    process.exit(1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    console.error("[ERROR] Unhandled rejection:", reason);
+    process.exit(1);
+  });
+  await server.connect(transport);
+}
+export {
+  createServer,
+  dispatchToolCall,
+  startServer
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * SpecForge MCP Server\n *\n * MCP (Model Context Protocol) server implementation using stdio transport.\n * Provides tools for AI agents to interact with SpecForge projects.\n *\n * M9: the boot-time `set_working_context` mechanism was removed — that backend\n * op no longer exists. Project/spec/session identity is injected per-call from\n * `.specforge/config.json` by the tool handlers (M9.6b), and the agent reads\n * the M8 envelope (interpreted in `handleToolCall`), TOON-encoded on the wire.\n */\n\nimport { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport {\n  CallToolRequestSchema,\n  ListToolsRequestSchema,\n} from '@modelcontextprotocol/sdk/types.js';\nimport { ApiClient } from './client/api-client.js';\nimport { McpConfig } from './config/index.js';\nimport { getTools, handleToolCall } from './tools/index.js';\nimport { formatToon } from './lib/format.js';\nimport type { OutputFormat } from './cli/config/types.js';\n\n/** Encode an MCP result for the wire per the resolved `mcpOutputFormat`. */\nfunction encodeMcp(value: unknown, format: OutputFormat): string {\n  return format === 'json' ? JSON.stringify(value, null, 2) : formatToon(value);\n}\n\n/**\n * Package version - should match package.json\n */\nconst VERSION = '1.0.0';\n\n/**\n * Dispatch a tool call and frame the result for the MCP wire.\n *\n * The wire encoding follows the resolved `mcpOutputFormat` (M9.6c) — TOON by\n * default, JSON when the project/global/env config selects it — on both the\n * success and error paths. Exposed for direct testing without spinning up the\n * full MCP transport.\n */\nexport async function dispatchToolCall(\n  apiClient: ApiClient,\n  toolName: string,\n  args: Record<string, unknown>,\n  debug: boolean,\n  format: OutputFormat = 'toon'\n): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {\n  try {\n    const result = await handleToolCall(apiClient, toolName, args, debug);\n    return {\n      content: [{ type: 'text', text: encodeMcp(result, format) }],\n    };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    if (debug) {\n      console.error(`[DEBUG] Tool ${toolName} failed:`, message);\n    }\n    return {\n      content: [{ type: 'text', text: encodeMcp({ error: message }, format) }],\n      isError: true,\n    };\n  }\n}\n\n/**\n * Create and configure the MCP server\n *\n * @param config - Configuration for the server\n * @returns Configured MCP Server instance\n */\nexport async function createServer(config: McpConfig): Promise<Server> {\n  const apiClient = new ApiClient(config);\n\n  const server = new Server(\n    {\n      name: 'specforge',\n      version: VERSION,\n    },\n    {\n      capabilities: {\n        tools: {},\n      },\n    }\n  );\n\n  // Handle ListTools requests - return available tools\n  server.setRequestHandler(ListToolsRequestSchema, async () => {\n    if (config.debug) {\n      console.error('[DEBUG] ListTools request received');\n    }\n\n    const tools = getTools();\n\n    if (config.debug) {\n      console.error(`[DEBUG] Returning ${tools.length} tools`);\n    }\n\n    return { tools };\n  });\n\n  // Handle CallTool requests - execute the requested tool\n  server.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const { name, arguments: args } = request.params;\n    const argsRecord = (args || {}) as Record<string, unknown>;\n\n    if (config.debug) {\n      console.error('[DEBUG] CallTool request:', {\n        name,\n        args: JSON.stringify(args),\n      });\n    }\n\n    return dispatchToolCall(apiClient, name, argsRecord, config.debug, config.mcpOutputFormat ?? 'toon');\n  });\n\n  return server;\n}\n\n/**\n * Start the MCP server with stdio transport\n *\n * @param server - The MCP server instance\n */\nexport async function startServer(server: Server): Promise<void> {\n  const transport = new StdioServerTransport();\n\n  // Handle graceful shutdown\n  const shutdown = async () => {\n    console.error('[INFO] Shutting down MCP server...');\n    await server.close();\n    process.exit(0);\n  };\n\n  process.on('SIGINT', shutdown);\n  process.on('SIGTERM', shutdown);\n\n  // Handle uncaught errors\n  process.on('uncaughtException', (error) => {\n    console.error('[ERROR] Uncaught exception:', error);\n    process.exit(1);\n  });\n\n  process.on('unhandledRejection', (reason) => {\n    console.error('[ERROR] Unhandled rejection:', reason);\n    process.exit(1);\n  });\n\n  // Connect to transport\n  await server.connect(transport);\n}\n"],"mappings":"AAYA,SAAS,cAAc;AACvB,SAAS,4BAA4B;AACrC;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,iBAAiB;AAE1B,SAAS,UAAU,sBAAsB;AACzC,SAAS,kBAAkB;AAI3B,SAAS,UAAU,OAAgB,QAA8B;AAC/D,SAAO,WAAW,SAAS,KAAK,UAAU,OAAO,MAAM,CAAC,IAAI,WAAW,KAAK;AAC9E;AAKA,MAAM,UAAU;AAUhB,eAAsB,iBACpB,WACA,UACA,MACA,OACA,SAAuB,QACyD;AAChF,MAAI;AACF,UAAM,SAAS,MAAM,eAAe,WAAW,UAAU,MAAM,KAAK;AACpE,WAAO;AAAA,MACL,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,UAAU,QAAQ,MAAM,EAAE,CAAC;AAAA,IAC7D;AAAA,EACF,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,QAAI,OAAO;AACT,cAAQ,MAAM,gBAAgB,QAAQ,YAAY,OAAO;AAAA,IAC3D;AACA,WAAO;AAAA,MACL,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,UAAU,EAAE,OAAO,QAAQ,GAAG,MAAM,EAAE,CAAC;AAAA,MACvE,SAAS;AAAA,IACX;AAAA,EACF;AACF;AAQA,eAAsB,aAAa,QAAoC;AACrE,QAAM,YAAY,IAAI,UAAU,MAAM;AAEtC,QAAM,SAAS,IAAI;AAAA,IACjB;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,cAAc;AAAA,QACZ,OAAO,CAAC;AAAA,MACV;AAAA,IACF;AAAA,EACF;AAGA,SAAO,kBAAkB,wBAAwB,YAAY;AAC3D,QAAI,OAAO,OAAO;AAChB,cAAQ,MAAM,oCAAoC;AAAA,IACpD;AAEA,UAAM,QAAQ,SAAS;AAEvB,QAAI,OAAO,OAAO;AAChB,cAAQ,MAAM,qBAAqB,MAAM,MAAM,QAAQ;AAAA,IACzD;AAEA,WAAO,EAAE,MAAM;AAAA,EACjB,CAAC;AAGD,SAAO,kBAAkB,uBAAuB,OAAO,YAAY;AACjE,UAAM,EAAE,MAAM,WAAW,KAAK,IAAI,QAAQ;AAC1C,UAAM,aAAc,QAAQ,CAAC;AAE7B,QAAI,OAAO,OAAO;AAChB,cAAQ,MAAM,6BAA6B;AAAA,QACzC;AAAA,QACA,MAAM,KAAK,UAAU,IAAI;AAAA,MAC3B,CAAC;AAAA,IACH;AAEA,WAAO,iBAAiB,WAAW,MAAM,YAAY,OAAO,OAAO,OAAO,mBAAmB,MAAM;AAAA,EACrG,CAAC;AAED,SAAO;AACT;AAOA,eAAsB,YAAY,QAA+B;AAC/D,QAAM,YAAY,IAAI,qBAAqB;AAG3C,QAAM,WAAW,YAAY;AAC3B,YAAQ,MAAM,oCAAoC;AAClD,UAAM,OAAO,MAAM;AACnB,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,UAAQ,GAAG,UAAU,QAAQ;AAC7B,UAAQ,GAAG,WAAW,QAAQ;AAG9B,UAAQ,GAAG,qBAAqB,CAAC,UAAU;AACzC,YAAQ,MAAM,+BAA+B,KAAK;AAClD,YAAQ,KAAK,CAAC;AAAA,EAChB,CAAC;AAED,UAAQ,GAAG,sBAAsB,CAAC,WAAW;AAC3C,YAAQ,MAAM,gCAAgC,MAAM;AACpD,YAAQ,KAAK,CAAC;AAAA,EAChB,CAAC;AAGD,QAAM,OAAO,QAAQ,SAAS;AAChC;","names":[]}

package/dist/tools/core/context-helper.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Context Helper
+ *
+ * Provides utilities for injecting working context from .specforge/config.json
+ * into tool arguments. This ensures tools scope to the correct project/specification
+ * when not explicitly provided.
+ */
+import type { ResolvedAgentTeamsConfig } from '../../cli/config/loader.js';
+import type { ActiveSpecification } from '../../cli/config/agent-teams.types.js';
+type ContextField = 'projectId' | 'specificationId';
+/**
+ * Inject missing context fields from .specforge/config.json.
+ * Explicit args always take precedence over config values.
+ *
+ * @param args - Tool arguments that may be missing context fields
+ * @param fields - Context fields to inject if missing
+ * @returns Args with context fields injected from config
+ */
+export declare function injectContext<T extends Record<string, unknown>>(args: T, fields: ContextField[]): T;
+/**
+ * Inject context and validate required fields are present.
+ * Throws error if required fields cannot be resolved from config.
+ *
+ * @param args - Tool arguments that may be missing context fields
+ * @param requiredFields - Fields that MUST be present after injection
+ * @param optionalFields - Fields to inject if available but not require
+ * @returns Args with context fields injected
+ * @throws Error if required fields cannot be resolved
+ */
+export declare function injectContextRequired<T extends Record<string, unknown>>(args: T, requiredFields: ContextField[], optionalFields?: ContextField[]): T;
+/**
+ * Get the resolved Agent Teams config from .specforge/config.json.
+ *
+ * Claude Code Agent Teams only. Not used by MCP tool handlers.
+ *
+ * Always returns a fully-resolved config with defaults applied (never null).
+ * Used by CLI commands like `plan` and `status --teams` to read the user's
+ * preferred strategy, team limits, and other settings.
+ */
+export declare function getAgentTeamsContext(): ResolvedAgentTeamsConfig;
+/**
+ * Get the active specification from .specforge/config.json.
+ *
+ * Claude Code Agent Teams only. Not used by MCP tool handlers.
+ *
+ * @returns ActiveSpecification if set, null if no spec is activated
+ */
+export declare function getActiveSpecificationContext(): ActiveSpecification | null;
+export {};
+//# sourceMappingURL=context-helper.d.ts.map

package/dist/tools/core/context-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-helper.d.ts","sourceRoot":"","sources":["../../../src/tools/core/context-helper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAEjF,KAAK,YAAY,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAwBpD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,YAAY,EAAE,GACrB,CAAC,CAaH;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,IAAI,EAAE,CAAC,EACP,cAAc,EAAE,YAAY,EAAE,EAC9B,cAAc,GAAE,YAAY,EAAO,GAClC,CAAC,CAWH;AAQD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,wBAAwB,CAG/D;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,mBAAmB,GAAG,IAAI,CAG1E"}

package/dist/tools/core/context-helper.js

@@ -0,0 +1,49 @@
+import {
+  tryLoadProjectConfig,
+  getAgentTeamsConfig as resolveAgentTeamsConfig,
+  getActiveSpecification as resolveActiveSpecification
+} from "../../cli/config/loader.js";
+function getLocalContext() {
+  const config = tryLoadProjectConfig();
+  return {
+    projectId: config?.projectId,
+    specificationId: config?.specificationId
+  };
+}
+function injectContext(args, fields) {
+  const missingFields = fields.filter((f) => !args[f]);
+  if (missingFields.length === 0) return args;
+  const context = getLocalContext();
+  const result = { ...args };
+  for (const field of missingFields) {
+    if (context[field]) {
+      result[field] = context[field];
+    }
+  }
+  return result;
+}
+function injectContextRequired(args, requiredFields, optionalFields = []) {
+  const result = injectContext(args, [...requiredFields, ...optionalFields]);
+  const missing = requiredFields.filter((f) => !result[f]);
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required context: ${missing.join(", ")}. Provide explicitly or run 'specforge switch' to set working context.`
+    );
+  }
+  return result;
+}
+function getAgentTeamsContext() {
+  const config = tryLoadProjectConfig();
+  return resolveAgentTeamsConfig(config);
+}
+function getActiveSpecificationContext() {
+  const config = tryLoadProjectConfig();
+  return resolveActiveSpecification(config);
+}
+export {
+  getActiveSpecificationContext,
+  getAgentTeamsContext,
+  injectContext,
+  injectContextRequired
+};
+//# sourceMappingURL=context-helper.js.map

package/dist/tools/core/context-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/tools/core/context-helper.ts"],"sourcesContent":["/**\n * Context Helper\n *\n * Provides utilities for injecting working context from .specforge/config.json\n * into tool arguments. This ensures tools scope to the correct project/specification\n * when not explicitly provided.\n */\n\nimport {\n  tryLoadProjectConfig,\n  getAgentTeamsConfig as resolveAgentTeamsConfig,\n  getActiveSpecification as resolveActiveSpecification,\n} from '../../cli/config/loader.js';\nimport type { ResolvedAgentTeamsConfig } from '../../cli/config/loader.js';\nimport type { ActiveSpecification } from '../../cli/config/agent-teams.types.js';\n\ntype ContextField = 'projectId' | 'specificationId';\n\ninterface LocalContext {\n  projectId?: string;\n  specificationId?: string;\n}\n\n// ============================================================\n// UNIVERSAL CONTEXT — Used by MCP tool handlers\n// Works with any MCP-connected agent CLI\n// ============================================================\n\n/**\n * Get context from .specforge/config.json file.\n * This is the source of truth for the current project/specification.\n */\nfunction getLocalContext(): LocalContext {\n  const config = tryLoadProjectConfig();\n  return {\n    projectId: config?.projectId,\n    specificationId: config?.specificationId,\n  };\n}\n\n/**\n * Inject missing context fields from .specforge/config.json.\n * Explicit args always take precedence over config values.\n *\n * @param args - Tool arguments that may be missing context fields\n * @param fields - Context fields to inject if missing\n * @returns Args with context fields injected from config\n */\nexport function injectContext<T extends Record<string, unknown>>(\n  args: T,\n  fields: ContextField[]\n): T {\n  const missingFields = fields.filter(f => !args[f]);\n  if (missingFields.length === 0) return args;\n\n  const context = getLocalContext();\n  const result: Record<string, unknown> = { ...args };\n\n  for (const field of missingFields) {\n    if (context[field]) {\n      result[field] = context[field];\n    }\n  }\n  return result as T;\n}\n\n/**\n * Inject context and validate required fields are present.\n * Throws error if required fields cannot be resolved from config.\n *\n * @param args - Tool arguments that may be missing context fields\n * @param requiredFields - Fields that MUST be present after injection\n * @param optionalFields - Fields to inject if available but not require\n * @returns Args with context fields injected\n * @throws Error if required fields cannot be resolved\n */\nexport function injectContextRequired<T extends Record<string, unknown>>(\n  args: T,\n  requiredFields: ContextField[],\n  optionalFields: ContextField[] = []\n): T {\n  const result = injectContext(args, [...requiredFields, ...optionalFields]);\n\n  const missing = requiredFields.filter(f => !result[f]);\n  if (missing.length > 0) {\n    throw new Error(\n      `Missing required context: ${missing.join(', ')}. ` +\n      `Provide explicitly or run 'specforge switch' to set working context.`\n    );\n  }\n  return result;\n}\n\n// ============================================================\n// AGENT TEAMS CONTEXT — Claude Code specific\n// Used by CLI orchestration layer only (spec-activate, plan, status --teams)\n// NOT used by any MCP tool handler\n// ============================================================\n\n/**\n * Get the resolved Agent Teams config from .specforge/config.json.\n *\n * Claude Code Agent Teams only. Not used by MCP tool handlers.\n *\n * Always returns a fully-resolved config with defaults applied (never null).\n * Used by CLI commands like `plan` and `status --teams` to read the user's\n * preferred strategy, team limits, and other settings.\n */\nexport function getAgentTeamsContext(): ResolvedAgentTeamsConfig {\n  const config = tryLoadProjectConfig();\n  return resolveAgentTeamsConfig(config);\n}\n\n/**\n * Get the active specification from .specforge/config.json.\n *\n * Claude Code Agent Teams only. Not used by MCP tool handlers.\n *\n * @returns ActiveSpecification if set, null if no spec is activated\n */\nexport function getActiveSpecificationContext(): ActiveSpecification | null {\n  const config = tryLoadProjectConfig();\n  return resolveActiveSpecification(config);\n}\n"],"mappings":"AAQA;AAAA,EACE;AAAA,EACA,uBAAuB;AAAA,EACvB,0BAA0B;AAAA,OACrB;AAoBP,SAAS,kBAAgC;AACvC,QAAM,SAAS,qBAAqB;AACpC,SAAO;AAAA,IACL,WAAW,QAAQ;AAAA,IACnB,iBAAiB,QAAQ;AAAA,EAC3B;AACF;AAUO,SAAS,cACd,MACA,QACG;AACH,QAAM,gBAAgB,OAAO,OAAO,OAAK,CAAC,KAAK,CAAC,CAAC;AACjD,MAAI,cAAc,WAAW,EAAG,QAAO;AAEvC,QAAM,UAAU,gBAAgB;AAChC,QAAM,SAAkC,EAAE,GAAG,KAAK;AAElD,aAAW,SAAS,eAAe;AACjC,QAAI,QAAQ,KAAK,GAAG;AAClB,aAAO,KAAK,IAAI,QAAQ,KAAK;AAAA,IAC/B;AAAA,EACF;AACA,SAAO;AACT;AAYO,SAAS,sBACd,MACA,gBACA,iBAAiC,CAAC,GAC/B;AACH,QAAM,SAAS,cAAc,MAAM,CAAC,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAEzE,QAAM,UAAU,eAAe,OAAO,OAAK,CAAC,OAAO,CAAC,CAAC;AACrD,MAAI,QAAQ,SAAS,GAAG;AACtB,UAAM,IAAI;AAAA,MACR,6BAA6B,QAAQ,KAAK,IAAI,CAAC;AAAA,IAEjD;AAAA,EACF;AACA,SAAO;AACT;AAiBO,SAAS,uBAAiD;AAC/D,QAAM,SAAS,qBAAqB;AACpC,SAAO,wBAAwB,MAAM;AACvC;AASO,SAAS,gCAA4D;AAC1E,QAAM,SAAS,qBAAqB;AACpC,SAAO,2BAA2B,MAAM;AAC1C;","names":[]}

package/dist/tools/core/index.d.ts

@@ -0,0 +1,2 @@
+export * from './context-helper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/core/index.ts"],"names":[],"mappings":"AAEA,cAAc,qBAAqB,CAAC"}

package/dist/tools/core/index.js

@@ -0,0 +1,2 @@
+export * from "./context-helper.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/tools/core/index.ts"],"sourcesContent":["// mcp/src/tools/core/index.ts\n\nexport * from './context-helper.js';\n"],"mappings":"AAEA,cAAc;","names":[]}