fraim-framework 2.0.70 → 2.0.72

package/dist/src/cli/commands/doctor.js

@@ -8,6 +8,7 @@ const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
+const inheritance_parser_1 = require("../../core/utils/inheritance-parser");
 exports.doctorCommand = new commander_1.Command('doctor')
     .description('Validate FRAIM installation and configuration')
     .action(async () => {
@@ -71,4 +72,58 @@ exports.doctorCommand = new commander_1.Command('doctor')
     else {
         console.log(chalk_1.default.red(`\n🩹 Found ${issuesFound} issues. See recommendations above.`));
     }
+    // 5. Check for overrides
+    const overridesDir = path_1.default.join(fraimDir, 'overrides');
+    if (fs_1.default.existsSync(overridesDir)) {
+        console.log(chalk_1.default.blue('\n📝 Override Diagnostics:\n'));
+        const overrides = [];
+        const scanDir = (dir, base = '') => {
+            const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const relativePath = path_1.default.join(base, entry.name);
+                if (entry.isDirectory()) {
+                    scanDir(path_1.default.join(dir, entry.name), relativePath);
+                }
+                else {
+                    overrides.push(relativePath.replace(/\\/g, '/'));
+                }
+            }
+        };
+        scanDir(overridesDir);
+        if (overrides.length === 0) {
+            console.log(chalk_1.default.gray('  No active overrides found.'));
+        }
+        else {
+            console.log(chalk_1.default.green(`  Found ${overrides.length} active override(s):\n`));
+            const parser = new inheritance_parser_1.InheritanceParser();
+            for (const override of overrides) {
+                const overridePath = path_1.default.join(overridesDir, override);
+                const content = fs_1.default.readFileSync(overridePath, 'utf-8');
+                const parseResult = parser.parse(content);
+                if (parseResult.hasImports) {
+                    console.log(chalk_1.default.white(`  📄 ${override}`));
+                    console.log(chalk_1.default.gray(`     Inherits from: ${parseResult.imports.join(', ')}`));
+                    // Validate import syntax
+                    let hasErrors = false;
+                    for (const importPath of parseResult.imports) {
+                        try {
+                            parser.sanitizePath(importPath);
+                        }
+                        catch (error) {
+                            console.log(chalk_1.default.red(`     ⚠️ Invalid import: ${error.message}`));
+                            hasErrors = true;
+                        }
+                    }
+                    if (!hasErrors) {
+                        console.log(chalk_1.default.green(`     ✅ Syntax valid`));
+                    }
+                }
+                else {
+                    console.log(chalk_1.default.white(`  📄 ${override}`));
+                    console.log(chalk_1.default.gray(`     Full override (no inheritance)`));
+                }
+                console.log('');
+            }
+        }
+    }
 });

package/dist/src/cli/commands/list-overridable.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listOverridableCommand = void 0;
+const commander_1 = require("commander");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+exports.listOverridableCommand = new commander_1.Command('list-overridable')
+    .description('List all FRAIM registry paths that can be overridden')
+    .action(async () => {
+    const projectRoot = process.cwd();
+    const fraimDir = path_1.default.join(projectRoot, '.fraim');
+    const configPath = path_1.default.join(fraimDir, 'config.json');
+    const overridesDir = path_1.default.join(fraimDir, 'overrides');
+    // Validate .fraim directory exists
+    if (!fs_1.default.existsSync(fraimDir)) {
+        console.log(chalk_1.default.red('❌ .fraim/ directory not found. Run "fraim setup" or "fraim init-project" first.'));
+        process.exit(1);
+    }
+    console.log(chalk_1.default.blue('📋 Overridable FRAIM Registry Paths:\n'));
+    // Define overridable categories
+    const categories = [
+        {
+            name: 'Workflows',
+            paths: [
+                'workflows/product-building/spec.md',
+                'workflows/product-building/design.md',
+                'workflows/product-building/implement.md',
+                'workflows/product-building/test.md',
+                'workflows/product-building/resolve.md',
+                'workflows/product-building/prep-issue.md'
+            ]
+        },
+        {
+            name: 'Templates',
+            paths: [
+                'templates/specs/FEATURESPEC-TEMPLATE.md',
+                'templates/design/DESIGN-TEMPLATE.md'
+            ]
+        },
+        {
+            name: 'Rules',
+            paths: [
+                'rules/coding-standards.md',
+                'rules/communication.md'
+            ]
+        }
+    ];
+    // Get list of existing overrides
+    const existingOverrides = new Set();
+    if (fs_1.default.existsSync(overridesDir)) {
+        const scanDir = (dir, base = '') => {
+            const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const relativePath = path_1.default.join(base, entry.name);
+                if (entry.isDirectory()) {
+                    scanDir(path_1.default.join(dir, entry.name), relativePath);
+                }
+                else {
+                    existingOverrides.add(relativePath.replace(/\\/g, '/'));
+                }
+            }
+        };
+        scanDir(overridesDir);
+    }
+    // Display categories
+    for (const category of categories) {
+        console.log(chalk_1.default.bold.cyan(`${category.name}:`));
+        for (const filePath of category.paths) {
+            const hasOverride = existingOverrides.has(filePath);
+            const status = hasOverride
+                ? chalk_1.default.green('[OVERRIDDEN]')
+                : chalk_1.default.gray('[OVERRIDABLE]');
+            console.log(`  ${status} ${filePath}`);
+        }
+        console.log('');
+    }
+    // Show existing overrides not in the standard list
+    const standardPaths = new Set(categories.flatMap(c => c.paths));
+    const customOverrides = Array.from(existingOverrides)
+        .filter(p => !standardPaths.has(p));
+    if (customOverrides.length > 0) {
+        console.log(chalk_1.default.bold.cyan('Custom Overrides:'));
+        for (const filePath of customOverrides) {
+            console.log(`  ${chalk_1.default.green('[OVERRIDDEN]')} ${filePath}`);
+        }
+        console.log('');
+    }
+    // Show tips
+    console.log(chalk_1.default.gray('Tips:'));
+    console.log(chalk_1.default.gray('  • Use "fraim override <path> --inherit" to inherit from global'));
+    console.log(chalk_1.default.gray('  • Use "fraim override <path> --copy" to copy current content'));
+    console.log(chalk_1.default.gray('  • Overrides are stored in .fraim/overrides/'));
+});

package/dist/src/cli/commands/override.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overrideCommand = void 0;
+const commander_1 = require("commander");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const axios_1 = __importDefault(require("axios"));
+exports.overrideCommand = new commander_1.Command('override')
+    .description('Create a local override for a FRAIM registry file')
+    .argument('<path>', 'Registry path to override (e.g., workflows/product-building/spec.md)')
+    .option('--inherit', 'Create override with {{ import }} directive (inherits from global)')
+    .option('--copy', 'Copy current content from remote to local')
+    .action(async (registryPath, options) => {
+    const projectRoot = process.cwd();
+    const fraimDir = path_1.default.join(projectRoot, '.fraim');
+    const configPath = path_1.default.join(fraimDir, 'config.json');
+    // Validate .fraim directory exists
+    if (!fs_1.default.existsSync(fraimDir)) {
+        console.log(chalk_1.default.red('❌ .fraim/ directory not found. Run "fraim setup" or "fraim init-project" first.'));
+        process.exit(1);
+    }
+    // Validate path format
+    if (registryPath.includes('..') || path_1.default.isAbsolute(registryPath)) {
+        console.log(chalk_1.default.red('❌ Invalid path. Path must be relative and cannot contain ".."'));
+        process.exit(1);
+    }
+    // Ensure exactly one option is specified
+    if (options.inherit && options.copy) {
+        console.log(chalk_1.default.red('❌ Cannot use both --inherit and --copy. Choose one.'));
+        process.exit(1);
+    }
+    if (!options.inherit && !options.copy) {
+        console.log(chalk_1.default.red('❌ Must specify either --inherit or --copy.'));
+        process.exit(1);
+    }
+    // Create overrides directory structure
+    const overridePath = path_1.default.join(fraimDir, 'overrides', registryPath);
+    const overrideDir = path_1.default.dirname(overridePath);
+    if (!fs_1.default.existsSync(overrideDir)) {
+        fs_1.default.mkdirSync(overrideDir, { recursive: true });
+    }
+    // Check if override already exists
+    if (fs_1.default.existsSync(overridePath)) {
+        console.log(chalk_1.default.yellow(`⚠️ Override already exists: ${registryPath}`));
+        console.log(chalk_1.default.gray(`   Location: ${overridePath}`));
+        process.exit(0);
+    }
+    let content;
+    if (options.inherit) {
+        // Create file with import directive
+        content = `{{ import: ${registryPath} }}\n\n<!-- Add your custom content below -->\n`;
+        console.log(chalk_1.default.blue(`📝 Creating inherited override for: ${registryPath}`));
+    }
+    else {
+        // Fetch current content from remote
+        console.log(chalk_1.default.blue(`📥 Fetching current content from remote: ${registryPath}`));
+        try {
+            // Read config to get remote URL
+            let config = {};
+            if (fs_1.default.existsSync(configPath)) {
+                config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
+            }
+            const remoteUrl = config.remoteUrl || 'https://fraim-registry.azurewebsites.net';
+            const apiKey = config.apiKey;
+            // Determine endpoint based on path
+            let endpoint;
+            if (registryPath.startsWith('workflows/')) {
+                const workflowName = registryPath.replace('workflows/', '').replace('.md', '');
+                endpoint = `${remoteUrl}/api/workflows/${workflowName}`;
+            }
+            else {
+                endpoint = `${remoteUrl}/api/files/${registryPath}`;
+            }
+            const headers = {};
+            if (apiKey) {
+                headers['x-api-key'] = apiKey;
+            }
+            const response = await axios_1.default.get(endpoint, {
+                headers,
+                timeout: 30000
+            });
+            // Extract content from response
+            if (response.data.content) {
+                content = response.data.content;
+            }
+            else if (typeof response.data === 'string') {
+                content = response.data;
+            }
+            else {
+                throw new Error('Unexpected response format');
+            }
+            console.log(chalk_1.default.green(`✅ Fetched ${content.length} bytes from remote`));
+        }
+        catch (error) {
+            console.log(chalk_1.default.red(`❌ Failed to fetch content from remote: ${error.message}`));
+            console.log(chalk_1.default.gray('   Tip: Check your network connection and .fraim/config.json settings'));
+            process.exit(1);
+        }
+    }
+    // Write override file
+    try {
+        fs_1.default.writeFileSync(overridePath, content, 'utf-8');
+        console.log(chalk_1.default.green(`✅ Created override: ${registryPath}`));
+        console.log(chalk_1.default.gray(`   Location: ${overridePath}`));
+        console.log(chalk_1.default.gray(`   Edit this file to customize for your project`));
+    }
+    catch (error) {
+        console.log(chalk_1.default.red(`❌ Failed to write override file: ${error.message}`));
+        process.exit(1);
+    }
+});

package/dist/src/cli/fraim.js

@@ -12,6 +12,8 @@ const setup_1 = require("./commands/setup");
 const init_project_1 = require("./commands/init-project");
 const test_mcp_1 = require("./commands/test-mcp");
 const add_ide_1 = require("./commands/add-ide");
+const override_1 = require("./commands/override");
+const list_overridable_1 = require("./commands/list-overridable");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const program = new commander_1.Command();
@@ -46,4 +48,6 @@ program.addCommand(setup_1.setupCommand);
 program.addCommand(init_project_1.initProjectCommand);
 program.addCommand(test_mcp_1.testMCPCommand);
 program.addCommand(add_ide_1.addIDECommand);
+program.addCommand(override_1.overrideCommand);
+program.addCommand(list_overridable_1.listOverridableCommand);
 program.parse(process.argv);

package/dist/src/core/utils/inheritance-parser.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * InheritanceParser
+ *
+ * Parses and resolves {{ import: path }} directives in registry files,
+ * enabling local overrides to inherit from global registry files.
+ *
+ * Security features:
+ * - Path traversal protection (rejects .. and absolute paths)
+ * - Circular import detection
+ * - Max depth limit (5 levels)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InheritanceParser = exports.InheritanceError = void 0;
+class InheritanceError extends Error {
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'InheritanceError';
+    }
+}
+exports.InheritanceError = InheritanceError;
+/**
+ * Regular expression to match {{ import: path }} directives
+ */
+const IMPORT_REGEX = /\{\{\s*import:\s*([^\}]+)\s*\}\}/g;
+class InheritanceParser {
+    constructor(maxDepth = 5) {
+        this.maxDepth = maxDepth;
+    }
+    /**
+     * Extract import directives from content without resolving them
+     */
+    extractImports(content) {
+        const imports = [];
+        let match;
+        // Reset regex state
+        IMPORT_REGEX.lastIndex = 0;
+        while ((match = IMPORT_REGEX.exec(content)) !== null) {
+            imports.push(match[1].trim());
+        }
+        return imports;
+    }
+    /**
+     * Sanitize and validate import path
+     *
+     * @throws {InheritanceError} If path is invalid
+     */
+    sanitizePath(path) {
+        const trimmed = path.trim();
+        // Reject empty paths
+        if (!trimmed) {
+            throw new InheritanceError('Import path cannot be empty');
+        }
+        // Reject absolute paths (Unix and Windows)
+        if (trimmed.startsWith('/') || trimmed.match(/^[A-Za-z]:\\/)) {
+            throw new InheritanceError(`Absolute paths not allowed: ${trimmed}`, trimmed);
+        }
+        // Reject path traversal attempts
+        if (trimmed.includes('..')) {
+            throw new InheritanceError(`Path traversal not allowed: ${trimmed}`, trimmed);
+        }
+        return trimmed;
+    }
+    /**
+     * Detect circular imports
+     *
+     * Special case: If the import path is the same as the current path,
+     * it's not a circular import - it's importing the parent/remote version.
+     * This allows local overrides to inherit from their remote counterparts.
+     *
+     * @throws {InheritanceError} If circular import detected
+     */
+    detectCircularImport(path, visited, isParentImport = false) {
+        // If this is a parent import (same path as current), allow it
+        if (isParentImport) {
+            return;
+        }
+        if (visited.has(path)) {
+            throw new InheritanceError(`Circular import detected: ${path}`, path);
+        }
+    }
+    /**
+     * Resolve all import directives in content recursively
+     *
+     * @param content - Content with {{ import }} directives
+     * @param currentPath - Path of current file (for circular detection)
+     * @param options - Resolution options
+     * @returns Resolved content with all imports replaced
+     *
+     * @throws {InheritanceError} If circular import, path traversal, or max depth exceeded
+     */
+    async resolve(content, currentPath, options) {
+        const depth = options.currentDepth || 0;
+        const visited = options.visited || new Set();
+        const maxDepth = options.maxDepth || this.maxDepth;
+        // Check depth limit
+        if (depth > maxDepth) {
+            throw new InheritanceError(`Max import depth exceeded (${maxDepth})`, currentPath);
+        }
+        // Check circular imports (but allow importing the same path as parent)
+        this.detectCircularImport(currentPath, visited, false);
+        visited.add(currentPath);
+        // Extract imports
+        const imports = this.extractImports(content);
+        if (imports.length === 0) {
+            return content;
+        }
+        // Resolve each import
+        let resolved = content;
+        for (const importPath of imports) {
+            // Sanitize path
+            const sanitized = this.sanitizePath(importPath);
+            // Check if this is a parent import (same path as current)
+            const isParentImport = sanitized === currentPath;
+            // Fetch parent content
+            let parentContent;
+            try {
+                parentContent = await options.fetchParent(sanitized);
+            }
+            catch (error) {
+                throw new InheritanceError(`Failed to fetch parent content: ${sanitized}. ${error.message}`, sanitized);
+            }
+            // Recursively resolve parent imports
+            // For parent imports, use a fresh visited set to allow the same path
+            const parentVisited = isParentImport ? new Set() : new Set(visited);
+            const resolvedParent = await this.resolve(parentContent, sanitized, {
+                ...options,
+                currentDepth: depth + 1,
+                visited: parentVisited
+            });
+            // Replace import directive with resolved parent content
+            const importDirective = `{{ import: ${importPath} }}`;
+            resolved = resolved.replace(importDirective, resolvedParent);
+        }
+        return resolved;
+    }
+    /**
+     * Parse content and return detailed information about imports
+     */
+    parse(content) {
+        const imports = this.extractImports(content);
+        return {
+            content,
+            imports,
+            hasImports: imports.length > 0
+        };
+    }
+}
+exports.InheritanceParser = InheritanceParser;

package/dist/src/core/utils/local-registry-resolver.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * LocalRegistryResolver
+ *
+ * Resolves registry file requests by checking for local overrides first,
+ * then falling back to remote registry. Handles inheritance via InheritanceParser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRegistryResolver = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const inheritance_parser_1 = require("./inheritance-parser");
+class LocalRegistryResolver {
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.remoteContentResolver = options.remoteContentResolver;
+        this.parser = new inheritance_parser_1.InheritanceParser(options.maxDepth);
+    }
+    /**
+     * Check if a local override exists for the given path
+     */
+    hasLocalOverride(path) {
+        const overridePath = this.getOverridePath(path);
+        const exists = (0, fs_1.existsSync)(overridePath);
+        console.error(`[LocalRegistryResolver] hasLocalOverride(${path}) -> ${overridePath} -> ${exists}`);
+        return exists;
+    }
+    /**
+     * Get the full path to a local override file
+     */
+    getOverridePath(path) {
+        return (0, path_1.join)(this.workspaceRoot, '.fraim/overrides', path);
+    }
+    /**
+     * Read local override file content
+     */
+    readLocalOverride(path) {
+        const overridePath = this.getOverridePath(path);
+        try {
+            return (0, fs_1.readFileSync)(overridePath, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read local override: ${path}. ${error.message}`);
+        }
+    }
+    /**
+     * Resolve inheritance in local override content
+     */
+    async resolveInheritance(content, currentPath) {
+        // Check if content has imports
+        const parseResult = this.parser.parse(content);
+        if (!parseResult.hasImports) {
+            return { content, imports: [] };
+        }
+        // Resolve imports
+        try {
+            const resolved = await this.parser.resolve(content, currentPath, {
+                fetchParent: this.remoteContentResolver,
+                maxDepth: 5
+            });
+            return {
+                content: resolved,
+                imports: parseResult.imports
+            };
+        }
+        catch (error) {
+            if (error instanceof inheritance_parser_1.InheritanceError) {
+                throw error;
+            }
+            throw new Error(`Failed to resolve inheritance for ${currentPath}: ${error.message}`);
+        }
+    }
+    /**
+     * Generate metadata comment for resolved content
+     */
+    generateMetadata(result) {
+        if (result.source === 'remote') {
+            return '';
+        }
+        if (result.inherited && result.imports && result.imports.length > 0) {
+            return `<!-- 📝 Using local override (inherited from: ${result.imports.join(', ')}) -->\n\n`;
+        }
+        return `<!-- 📝 Using local override -->\n\n`;
+    }
+    /**
+     * Resolve a registry file request
+     *
+     * Resolution order:
+     * 1. Check for local override in .fraim/overrides/
+     * 2. If found, read and resolve inheritance
+     * 3. If not found, fetch from remote
+     *
+     * @param path - Registry path (e.g., "workflows/product-building/spec.md")
+     * @returns Resolved file with metadata
+     */
+    async resolveFile(path) {
+        console.error(`[LocalRegistryResolver] ===== resolveFile called for: ${path} =====`);
+        // Check for local override
+        if (!this.hasLocalOverride(path)) {
+            // No override, fetch from remote
+            try {
+                const content = await this.remoteContentResolver(path);
+                return {
+                    content,
+                    source: 'remote',
+                    inherited: false
+                };
+            }
+            catch (error) {
+                throw new Error(`Failed to fetch from remote: ${path}. ${error.message}`);
+            }
+        }
+        // Read local override
+        let localContent;
+        try {
+            localContent = this.readLocalOverride(path);
+        }
+        catch (error) {
+            // If local read fails, fall back to remote
+            console.warn(`Local override read failed, falling back to remote: ${path}`);
+            const content = await this.remoteContentResolver(path);
+            return {
+                content,
+                source: 'remote',
+                inherited: false
+            };
+        }
+        // Resolve inheritance
+        let resolved;
+        try {
+            console.error(`[LocalRegistryResolver] Resolving inheritance for ${path}`);
+            console.error(`[LocalRegistryResolver] Local content length: ${localContent.length} chars`);
+            console.error(`[LocalRegistryResolver] Local content preview: ${localContent.substring(0, 200)}`);
+            resolved = await this.resolveInheritance(localContent, path);
+            console.error(`[LocalRegistryResolver] Inheritance resolved: ${resolved.imports.length} imports`);
+            console.error(`[LocalRegistryResolver] Resolved content length: ${resolved.content.length} chars`);
+            console.error(`[LocalRegistryResolver] Resolved content preview: ${resolved.content.substring(0, 200)}`);
+        }
+        catch (error) {
+            // If inheritance resolution fails, fall back to remote
+            console.error(`❌ Inheritance resolution failed for ${path}:`, error);
+            const content = await this.remoteContentResolver(path);
+            return {
+                content,
+                source: 'remote',
+                inherited: false
+            };
+        }
+        // Build result
+        const result = {
+            content: resolved.content,
+            source: 'local',
+            inherited: resolved.imports.length > 0,
+            imports: resolved.imports.length > 0 ? resolved.imports : undefined
+        };
+        // Add metadata comment
+        const metadata = this.generateMetadata(result);
+        if (metadata) {
+            result.metadata = metadata;
+            result.content = metadata + result.content;
+        }
+        return result;
+    }
+}
+exports.LocalRegistryResolver = LocalRegistryResolver;

package/dist/src/local-mcp-server/stdio-server.js

@@ -27,6 +27,7 @@ const crypto_1 = require("crypto");
 const axios_1 = __importDefault(require("axios"));
 const provider_utils_1 = require("../core/utils/provider-utils");
 const object_utils_1 = require("../core/utils/object-utils");
+const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
 /**
  * Handle template substitution logic separately for better testability
  */
@@ -80,22 +81,35 @@ class FraimTemplateEngine {
         const filename = this.workingStyle === 'Conversation' ? 'delivery-conversation.json' : 'delivery-pr.json';
         try {
             let content = null;
-            if (this.projectRoot) {
-                const deliveryPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', filename);
-                if ((0, fs_1.existsSync)(deliveryPath)) {
-                    content = (0, fs_1.readFileSync)(deliveryPath, 'utf-8');
-                }
-            }
+            // Try framework installation directory first (relative to this file)
+            // This file is in dist/src/local-mcp-server/, so go up to framework root
+            const frameworkRoot = (0, path_1.join)(__dirname, '..', '..', '..');
+            const frameworkPath = (0, path_1.join)(frameworkRoot, 'registry', 'providers', filename);
+            if ((0, fs_1.existsSync)(frameworkPath)) {
+                content = (0, fs_1.readFileSync)(frameworkPath, 'utf-8');
+                this.logFn(`✅ Loaded delivery templates from framework: ${frameworkPath}`);
+            }
+            // Fallback: try node_modules if not found in framework root
             if (!content) {
                 const nodeModulesPath = (0, path_1.join)(process.cwd(), 'node_modules', '@fraim', 'framework', 'registry', 'providers', filename);
                 if ((0, fs_1.existsSync)(nodeModulesPath)) {
                     content = (0, fs_1.readFileSync)(nodeModulesPath, 'utf-8');
+                    this.logFn(`✅ Loaded delivery templates from node_modules: ${nodeModulesPath}`);
+                }
+            }
+            // Last resort: try project root (for custom overrides)
+            if (!content && this.projectRoot) {
+                const deliveryPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', filename);
+                if ((0, fs_1.existsSync)(deliveryPath)) {
+                    content = (0, fs_1.readFileSync)(deliveryPath, 'utf-8');
+                    this.logFn(`✅ Loaded delivery templates from project: ${deliveryPath}`);
                 }
             }
             if (content) {
                 this.deliveryTemplatesCache = JSON.parse(content);
                 return this.deliveryTemplatesCache;
             }
+            this.logFn(`⚠️ Could not find delivery templates: ${filename}`);
             return null;
         }
         catch (error) {
@@ -121,18 +135,26 @@ class FraimTemplateEngine {
             return this.providerTemplatesCache[provider];
         try {
             let content = null;
-            if (this.projectRoot) {
-                const providerPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', `${provider}.json`);
-                if ((0, fs_1.existsSync)(providerPath)) {
-                    content = (0, fs_1.readFileSync)(providerPath, 'utf-8');
-                }
+            // Try framework installation directory first (relative to this file)
+            const frameworkRoot = (0, path_1.join)(__dirname, '..', '..', '..');
+            const frameworkPath = (0, path_1.join)(frameworkRoot, 'registry', 'providers', `${provider}.json`);
+            if ((0, fs_1.existsSync)(frameworkPath)) {
+                content = (0, fs_1.readFileSync)(frameworkPath, 'utf-8');
             }
+            // Fallback: try node_modules
             if (!content) {
                 const nodeModulesPath = (0, path_1.join)(process.cwd(), 'node_modules', '@fraim', 'framework', 'registry', 'providers', `${provider}.json`);
                 if ((0, fs_1.existsSync)(nodeModulesPath)) {
                     content = (0, fs_1.readFileSync)(nodeModulesPath, 'utf-8');
                 }
             }
+            // Last resort: try project root (for custom overrides)
+            if (!content && this.projectRoot) {
+                const providerPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', `${provider}.json`);
+                if ((0, fs_1.existsSync)(providerPath)) {
+                    content = (0, fs_1.readFileSync)(providerPath, 'utf-8');
+                }
+            }
             if (content) {
                 const templates = JSON.parse(content);
                 this.providerTemplatesCache[provider] = templates;
@@ -178,6 +200,7 @@ class FraimLocalMCPServer {
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
+        this.registryResolver = null;
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = process.env.FRAIM_API_KEY || '';
         this.localVersion = this.detectLocalVersion();
@@ -349,6 +372,10 @@ class FraimLocalMCPServer {
         if (this.repoInfo) {
             return this.repoInfo;
         }
+        // Ensure config is loaded before trying to detect repo info
+        if (!this.config) {
+            this.loadConfig();
+        }
         try {
             const projectDir = this.findProjectRoot() || process.cwd();
             // Try to get git remote URL
@@ -464,6 +491,112 @@ class FraimLocalMCPServer {
         }
         return this.engine.substituteTemplates(content);
     }
+    /**
+     * Initialize the LocalRegistryResolver for override resolution
+     */
+    getRegistryResolver() {
+        if (!this.registryResolver) {
+            const projectRoot = this.findProjectRoot();
+            this.log(`🔍 getRegistryResolver: projectRoot = ${projectRoot}`);
+            if (!projectRoot) {
+                this.log('⚠️ No project root found, override resolution disabled');
+                // Return a resolver that always falls back to remote
+                this.registryResolver = new local_registry_resolver_1.LocalRegistryResolver({
+                    workspaceRoot: process.cwd(),
+                    remoteContentResolver: async (path) => {
+                        throw new Error('No project root available');
+                    }
+                });
+            }
+            else {
+                this.registryResolver = new local_registry_resolver_1.LocalRegistryResolver({
+                    workspaceRoot: projectRoot,
+                    remoteContentResolver: async (path) => {
+                        // Fetch parent content from remote for inheritance
+                        this.log(`🔄 Remote content resolver: fetching ${path}`);
+                        let request;
+                        if (path.startsWith('workflows/')) {
+                            // Extract workflow name from path: workflows/category/name.md -> name
+                            const pathParts = path.replace('workflows/', '').replace('.md', '').split('/');
+                            const workflowName = pathParts[pathParts.length - 1]; // Get last part (name)
+                            this.log(`🔄 Fetching workflow: ${workflowName}`);
+                            request = {
+                                jsonrpc: '2.0',
+                                id: (0, crypto_1.randomUUID)(),
+                                method: 'tools/call',
+                                params: {
+                                    name: 'get_fraim_workflow',
+                                    arguments: { workflow: workflowName }
+                                }
+                            };
+                        }
+                        else {
+                            // For non-workflow files (templates, rules, etc.), use get_fraim_file
+                            this.log(`🔄 Fetching file: ${path}`);
+                            request = {
+                                jsonrpc: '2.0',
+                                id: (0, crypto_1.randomUUID)(),
+                                method: 'tools/call',
+                                params: {
+                                    name: 'get_fraim_file',
+                                    arguments: { path }
+                                }
+                            };
+                        }
+                        const response = await this.proxyToRemote(request);
+                        if (response.error) {
+                            this.logError(`❌ Remote content resolver failed: ${response.error.message}`);
+                            throw new Error(`Failed to fetch parent: ${response.error.message}`);
+                        }
+                        // Extract content from MCP response format
+                        if (response.result?.content && Array.isArray(response.result.content)) {
+                            const textContent = response.result.content.find((c) => c.type === 'text');
+                            if (textContent?.text) {
+                                this.log(`✅ Remote content resolver: fetched ${textContent.text.length} chars`);
+                                return textContent.text;
+                            }
+                        }
+                        this.logError(`❌ Remote content resolver: no content in response for ${path}`);
+                        this.logError(`Response: ${JSON.stringify(response, null, 2)}`);
+                        throw new Error(`No content in remote response for ${path}`);
+                    }
+                });
+            }
+        }
+        return this.registryResolver;
+    }
+    /**
+     * Determine workflow category from workflow name
+     */
+    getWorkflowCategory(workflowName) {
+        // Product development workflows
+        const productWorkflows = [
+            'prep-issue', 'spec', 'design', 'implement', 'test', 'resolve',
+            'prototype', 'refactor', 'iterate-on-pr-comments', 'retrospect'
+        ];
+        // Customer development workflows
+        const customerWorkflows = [
+            'linkedin-outreach', 'customer-interview', 'insight-analysis',
+            'insight-triage', 'interview-preparation', 'strategic-brainstorming',
+            'thank-customers', 'user-survey-dispatch', 'users-to-target', 'weekly-newsletter'
+        ];
+        // Business development workflows
+        const businessWorkflows = [
+            'partnership-outreach', 'investor-pitch', 'create-business-plan',
+            'ideate-business-opportunity', 'price-product'
+        ];
+        if (productWorkflows.includes(workflowName)) {
+            return 'product-building';
+        }
+        else if (customerWorkflows.includes(workflowName)) {
+            return 'customer-development';
+        }
+        else if (businessWorkflows.includes(workflowName)) {
+            return 'business-development';
+        }
+        // Default to product-building for unknown workflows
+        return 'product-building';
+    }
     /**
      * Process template substitution in MCP response
      */
@@ -522,16 +655,20 @@ class FraimLocalMCPServer {
                     this.log(`[req:${requestId}] Auto-detected and injected repo info: ${args.repo.owner}/${args.repo.name}`);
                 }
                 else {
-                    // If detection fails completely, return error instead of sending garbage
-                    this.logError(`[req:${requestId}] Could not detect repo info and no config available`);
-                    return {
-                        jsonrpc: '2.0',
-                        id: request.id,
-                        error: {
-                            code: -32603,
-                            message: 'Failed to detect repository information. Please ensure you are in a git repository or have .fraim/config.json configured with repository details.'
-                        }
-                    };
+                    // If detection fails, use agent-provided values (if any)
+                    if (!args.repo || !args.repo.url) {
+                        // Only return error if agent didn't provide repo info either
+                        this.logError(`[req:${requestId}] Could not detect repo info and no repo info provided by agent`);
+                        return {
+                            jsonrpc: '2.0',
+                            id: request.id,
+                            error: {
+                                code: -32603,
+                                message: 'Failed to detect repository information. Please ensure you are in a git repository or have .fraim/config.json configured with repository details, or provide repo info in fraim_connect arguments.'
+                            }
+                        };
+                    }
+                    this.log(`[req:${requestId}] Using agent-provided repo info: ${args.repo.owner}/${args.repo.name}`);
                 }
                 // Update the request with injected info
                 request.params.arguments = args;
@@ -640,6 +777,94 @@ class FraimLocalMCPServer {
             this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
             return processedResponse;
         }
+        // Intercept get_fraim_workflow and get_fraim_file for override resolution
+        if (request.method === 'tools/call' &&
+            (request.params?.name === 'get_fraim_workflow' ||
+                request.params?.name === 'get_fraim_file')) {
+            try {
+                const toolName = request.params.name;
+                const args = request.params.arguments || {};
+                // Extract the requested path
+                let requestedPath;
+                if (toolName === 'get_fraim_workflow') {
+                    // Convert workflow name to path (e.g., "spec" -> "workflows/product-building/spec.md")
+                    const workflowName = args.workflow;
+                    if (!workflowName) {
+                        this.log('⚠️ No workflow name provided in get_fraim_workflow');
+                    }
+                    else {
+                        // Determine workflow category from name
+                        const category = this.getWorkflowCategory(workflowName);
+                        requestedPath = `workflows/${category}/${workflowName}.md`;
+                        this.log(`🔍 Checking for override: ${requestedPath}`);
+                        const resolver = this.getRegistryResolver();
+                        const hasOverride = resolver.hasLocalOverride(requestedPath);
+                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
+                        if (hasOverride) {
+                            this.log(`✅ Local override found: ${requestedPath}`);
+                            const resolved = await resolver.resolveFile(requestedPath);
+                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
+                            // Build MCP response with resolved content
+                            const response = {
+                                jsonrpc: '2.0',
+                                id: request.id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: resolved.content
+                                        }
+                                    ]
+                                }
+                            };
+                            // Apply template substitution
+                            const processedResponse = this.processResponse(response);
+                            this.log(`📤 ${request.method} → OK`);
+                            return processedResponse;
+                        }
+                    }
+                }
+                else if (toolName === 'get_fraim_file') {
+                    requestedPath = args.path;
+                    if (!requestedPath) {
+                        this.log('⚠️ No path provided in get_fraim_file');
+                    }
+                    else {
+                        this.log(`🔍 Checking for override: ${requestedPath}`);
+                        const resolver = this.getRegistryResolver();
+                        const hasOverride = resolver.hasLocalOverride(requestedPath);
+                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
+                        if (hasOverride) {
+                            this.log(`✅ Local override found: ${requestedPath}`);
+                            const resolved = await resolver.resolveFile(requestedPath);
+                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
+                            // Build MCP response with resolved content
+                            const response = {
+                                jsonrpc: '2.0',
+                                id: request.id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: resolved.content
+                                        }
+                                    ]
+                                }
+                            };
+                            // Apply template substitution
+                            const processedResponse = this.processResponse(response);
+                            this.log(`📤 ${request.method} → OK`);
+                            return processedResponse;
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                this.logError(`Override resolution failed: ${error.message}`);
+                this.log('⚠️ Falling back to remote');
+                // Fall through to proxy to remote
+            }
+        }
         // Proxy to remote server
         const response = await this.proxyToRemote(request);
         // Process template substitution (config vars, platform actions, delivery templates)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.70",
+  "version": "2.0.72",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -66,13 +66,10 @@
     "@types/express": "^5.0.6",
     "@types/node": "^20.0.0",
     "@types/prompts": "^2.4.9",
-    "cors": "^2.8.5",
-    "express": "^5.2.1",
     "fast-glob": "^3.3.3",
     "html-to-docx": "^1.8.0",
     "markdown-it": "^14.1.0",
     "markdown-it-highlightjs": "^4.2.0",
-    "mongodb": "^7.0.0",
     "pptxgenjs": "^4.0.1",
     "puppeteer": "^24.36.1",
     "qrcode": "^1.5.4",
@@ -101,6 +98,9 @@
     "commander": "^14.0.2",
     "dotenv": "^16.4.7",
     "prompts": "^2.4.2",
-    "tree-kill": "^1.2.2"
+    "tree-kill": "^1.2.2",
+    "express": "^5.2.1",
+    "cors": "^2.8.5",
+    "mongodb": "^7.0.0"
   }
 }

package/CHANGELOG.md

@@ -1,76 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-
-## [2.1.0] - 2026-02-04
-
-### 🔄 Workflow Refinement
-- **Consolidated Workflows**: Inlined all phase content into main workflow files (`spec.md`, `design.md`, `implement.md`) for better context retention and reduced file scatter.
-- **Removed Redundant Files**: Deleted separate phase folders (`design-phases`, `implement-phases`, `spec-phases`, etc.) to streamline repository structure.
-- **Terminology Update**: Renamed "AI Coach" to "AI Mentor" across all workflows to align with new branding.
-- **Enhanced Spec Workflow**: Added `spec-competitor-analysis` phase and inlined validation steps.
-- **Retrospective Integration**: Inlined retrospective phase content into all major workflows.
-
-## [2.0.0] - 2024-12-19
-
-### 🚀 Major Release: FRAIM v2 - The Future of AI-Assisted Development
-
-#### ✨ New Features
-- **Complete Generic Framework**: Removed all Ashley-specific IP, making FRAIM truly universal
-- **Enhanced Rule System**: 13 comprehensive rule files covering all aspects of AI agent management
-- **Simplified Label System**: Streamlined to 9 essential labels matching real-world usage
-- **Spec Workflow**: Added specification phase for requirements and user experience definition
-- **Timeout Management**: Advanced timeout scripts with output visibility for long-running tasks
-- **Evidence-Based Validation**: Mandatory test evidence collection and validation
-- **Systematic Debugging**: Structured debugging patterns with learning capture
-
-#### 🔧 Improvements
-- **Single Install Method**: Simplified to `npm install -g fraim-framework`
-- **Better Documentation**: Comprehensive README with marketing-style positioning
-- **Example Test Cases**: Complete example with tagging system and documentation
-- **TypeScript Support**: Full TypeScript compilation and type safety
-- **Git Safety**: Safe Git commands preventing agent hangs
-- **Merge Requirements**: Advanced branch management with conflict resolution
-
-#### 🛡️ Security & Reliability
-- **Agent Integrity Rules**: Prevents "fake it till you make it" behavior
-- **Test Ethics**: Mandatory evidence collection and validation
-- **Communication Standards**: Clear accountability and progress reporting
-- **Architecture Discipline**: Clean separation of concerns and technical debt prevention
-
-#### 📚 Documentation
-- **Marketing README**: Compelling documentation positioning FRAIM as the future
-- **Problem-Solution Mapping**: Each rule clearly mapped to specific problems
-- **Human-Agent Parallels**: Clear comparison between human and AI development
-- **Success Stories**: Realistic testimonials and quantified benefits
-
-#### 🎯 Workflow Enhancements
-- **RIGOR Methodology**: Reviews, Isolation, GitOps, Observability, Retrospectives
-- **Phase-Based Development**: Spec → Design → Implementation → Testing → Resolution
-- **Agent Coordination**: Seamless handoffs between multiple AI agents
-- **Continuous Learning**: Retrospective-driven improvement system
-
-#### 🔄 Breaking Changes
-- **Simplified Labels**: Reduced from 15 to 9 essential labels
-- **Install Method**: Single npm install method (removed curl, Python options)
-- **Generic Examples**: All Ashley-specific examples replaced with universal patterns
-
-#### 🐛 Bug Fixes
-- **TypeScript Compilation**: Fixed all compilation issues
-- **Import Dependencies**: Resolved missing dependencies
-- **Test Utilities**: Made generic and framework-agnostic
-- **Repository References**: Updated all URLs to point to FRAIM repository
-
-#### 📦 Dependencies
-- Added TypeScript support with proper type definitions
-- Added tsx for TypeScript execution
-- Added dotenv for environment management
-- Updated Node.js engine requirement to >=16.0.0
-
----
-
-## [1.0.12] - Previous Release
-- Initial FRAIM framework with Ashley-specific implementations
-- Basic rule system and workflows
-- GitHub integration and automation