grimoire-framework 1.0.0

package/.grimoire/hooks/unified/runners/precompact-runner.js

@@ -0,0 +1,98 @@
+/**
+ * PreCompact Hook Runner - Session Digest Trigger
+ *
+ * Captures session knowledge before context compact via PreCompact hook.
+ * Uses fire-and-forget async execution to avoid blocking the compact operation.
+ *
+ * Architecture: Open Core
+ * - grimoire: Hook runner (this file) + pro detection
+ * - grimoire-pro: Digest extraction logic (memory/session-digest/)
+ *
+ * @module .grimoire/hooks/unified/runners/precompact-runner
+ * @see Story MIS-3 - Session Digest (PreCompact Hook)
+ * @see Story PRO-5 - grimoire-pro Repository Bootstrap
+ */
+
+'use strict';
+
+const path = require('path');
+const proDetectorPath = path.resolve(__dirname, '../../../..', 'bin', 'utils', 'pro-detector');
+const { isProAvailable, loadProModule } = require(proDetectorPath);
+
+/**
+ * PreCompact hook handler - Fire-and-forget session digest
+ *
+ * Execution flow:
+ * 1. Detect grimoire-pro availability via pro-detector
+ * 2. If available, fire-and-forget async digest extraction
+ * 3. If not available, graceful no-op (log and return)
+ * 4. NEVER block the compact operation (< 5s)
+ *
+ * @param {Object} context - Hook context from Claude Code
+ * @param {string} context.sessionId - Current session identifier
+ * @param {string} context.projectDir - Project root directory
+ * @param {Object} context.conversation - Conversation metadata
+ * @param {string} context.provider - CLI provider ('claude' or 'gemini')
+ * @returns {Promise<void>}
+ */
+async function onPreCompact(context) {
+  try {
+    // 1. Detect grimoire-pro availability
+    const proAvailable = isProAvailable();
+
+    if (!proAvailable) {
+      console.log('[PreCompact] grimoire-pro not available, skipping session digest');
+      return; // Graceful degradation - no-op
+    }
+
+    // 2. Fire-and-forget async execution (don't block compact)
+    setImmediate(async () => {
+      try {
+        // Dynamic import from grimoire-pro
+        const digestModule = loadProModule('memory/session-digest/extractor.js');
+
+        if (!digestModule || typeof digestModule.extractSessionDigest !== 'function') {
+          console.error('[PreCompact] Digest extractor not found or invalid in grimoire-pro');
+          return;
+        }
+
+        // Execute digest extraction
+        await digestModule.extractSessionDigest(context);
+
+        console.log('[PreCompact] Session digest completed successfully');
+      } catch (err) {
+        // Silent failure - log but don't propagate (never block user)
+        console.error('[PreCompact] Digest extraction failed (silent):', err.message);
+      }
+    });
+
+    // 3. Return immediately - don't wait for digest to complete
+    return;
+  } catch (err) {
+    // Outer error boundary - silent failure
+    console.error('[PreCompact] Hook runner error:', err.message);
+    // Never throw - graceful degradation
+  }
+}
+
+/**
+ * Get hook configuration for registration
+ *
+ * @returns {Object} Hook configuration metadata
+ */
+function getHookConfig() {
+  return {
+    name: 'precompact-session-digest',
+    event: 'PreCompact',
+    handler: onPreCompact,
+    timeout: 5000, // Max 5s to avoid delaying compact
+    description: 'Capture session knowledge before context compact (MIS-3)',
+  };
+}
+
+module.exports = {
+  onPreCompact,
+  getHookConfig,
+};
+
+

package/.grimoire/index.esm.js

@@ -0,0 +1,17 @@
+// @grimoire/grimoire/core - ES Module Entry Point
+import MetaAgent from './infrastructure/scripts/component-generator.js';
+import TaskManager from './infrastructure/scripts/batch-creator.js';
+import ElicitationEngine from './core/elicitation/elicitation-engine.js';
+import TemplateEngine from './infrastructure/scripts/template-engine.js';
+import ComponentSearch from './infrastructure/scripts/component-search.js';
+import DependencyAnalyzer from './infrastructure/scripts/dependency-analyzer.js';
+
+export {
+    MetaAgent,
+    TaskManager,
+    ElicitationEngine,
+    TemplateEngine,
+    ComponentSearch,
+    DependencyAnalyzer
+};
+

package/.grimoire/index.js

@@ -0,0 +1,17 @@
+// @grimoire/grimoire/core - CommonJS Entry Point
+const MetaAgent = require('./infrastructure/scripts/component-generator.js');
+const TaskManager = require('./infrastructure/scripts/batch-creator.js');
+const ElicitationEngine = require('./core/elicitation/elicitation-engine.js');
+const TemplateEngine = require('./infrastructure/scripts/template-engine.js');
+const ComponentSearch = require('./infrastructure/scripts/component-search.js');
+const DependencyAnalyzer = require('./infrastructure/scripts/dependency-analyzer.js');
+
+module.exports = {
+  MetaAgent: MetaAgent,
+  TaskManager: TaskManager,
+  ElicitationEngine: ElicitationEngine,
+  TemplateEngine: TemplateEngine,
+  ComponentSearch: ComponentSearch,
+  DependencyAnalyzer: DependencyAnalyzer,
+};
+

package/.grimoire/infrastructure/README.md

@@ -0,0 +1,128 @@
+# Infrastructure Module
+
+Base layer of the grimoire modular architecture. Contains tools, integrations, scripts, and PM adapters.
+
+## Structure
+
+```
+infrastructure/
+├── tools/                      # Tool configurations (14 files)
+│   ├── cli/                    # CLI tools (github-cli, railway-cli, supabase-cli)
+│   ├── local/                  # Local tools (ffmpeg)
+│   ├── mcp/                    # MCP tools (9 configs)
+│   └── README.md
+│
+├── scripts/                    # Infrastructure scripts (50+)
+│   ├── _archived/              # Archived migration scripts
+│   └── *.js                    # Active infrastructure scripts
+│
+├── integrations/               # External integrations
+│   └── pm-adapters/            # PM tool adapters (4 adapters)
+│
+├── tests/                      # Test utilities
+│   ├── project-status-loader.test.js
+│   └── regression-suite-v2.md
+│
+├── index.js                    # Module exports
+└── README.md                   # This file
+```
+
+## Dependency Direction
+
+Infrastructure is the **base layer** - it has no dependencies on other modules:
+
+```
+infrastructure/ ← core/ ← development/ ← product/
+```
+
+- `infrastructure/` CAN import from: nothing (base layer)
+- `core/` CAN import from: `infrastructure/`
+- `development/` CAN import from: `infrastructure/`, `core/`
+- `product/` CAN import from: `infrastructure/`, `core/`
+
+## Key Components
+
+### Git Integration
+- `GitWrapper` - Git CLI wrapper for all git operations
+- `GitConfigDetector` - Detects git configuration status
+- `BranchManager` - Branch management utilities
+- `CommitMessageGenerator` - Generates commit messages
+
+### PM Integration
+- `getPMAdapter()` - Factory for PM tool adapters
+- `PMAdapter` - Base adapter class
+- Adapters: ClickUp, GitHub Projects, Jira, Local (standalone)
+
+### Template & Generation
+- `TemplateEngine` - Template rendering
+- `ComponentGenerator` - grimoire component generation
+- `BatchCreator` - Batch operations
+
+### Validation
+- `grimoireValidator` - grimoire component validation
+- `TemplateValidator` - Template validation
+- `SpotCheckValidator` - Spot check validation
+
+### Analysis
+- `DependencyAnalyzer` - Dependency analysis
+- `SecurityChecker` - Security validation
+- `CapabilityAnalyzer` - Capability analysis
+
+### Testing
+- `TestGenerator` - Test file generation
+- `CoverageAnalyzer` - Coverage analysis
+- `SandboxTester` - Sandbox testing
+
+### Performance
+- `PerformanceAnalyzer` - Performance analysis
+- `PerformanceTracker` - Performance tracking
+- `PerformanceOptimizer` - Performance optimization
+
+### Quality
+- `CodeQualityImprover` - Code quality improvements
+- `RefactoringSuggester` - Refactoring suggestions
+- `ImprovementEngine` - General improvements
+
+## Usage
+
+```javascript
+// Import from infrastructure module
+const {
+  GitWrapper,
+  getPMAdapter,
+  TemplateEngine,
+  resolveTool
+} = require('.grimoire/infrastructure');
+
+// Or import directly from scripts
+const GitWrapper = require('.grimoire/infrastructure/scripts/git-wrapper');
+```
+
+## Tool Resolution
+
+```javascript
+const { resolveTool } = require('.grimoire/infrastructure');
+
+// Get tool configuration
+const clickupTool = await resolveTool('clickup');
+const githubCli = await resolveTool('github-cli');
+```
+
+## PM Adapters
+
+```javascript
+const { getPMAdapter, isPMToolConfigured } = require('.grimoire/infrastructure');
+
+// Check if PM tool is configured
+if (isPMToolConfigured()) {
+  const adapter = getPMAdapter();
+  await adapter.syncStory(storyPath);
+}
+```
+
+## Migration Reference
+
+Created as part of Story 2.5 - Infrastructure Module Creation.
+See [ADR-002 Migration Map](../../docs/architecture/decisions/ADR-002-migration-map.md).
+
+

package/.grimoire/infrastructure/contracts/compatibility/grimoire-4.0.4.yaml

@@ -0,0 +1,46 @@
+release: "grimoire 4.0.4"
+updated_at: "2026-02-16"
+source_of_truth:
+  docs_matrix: "docs/ide-integration.md"
+  validator: ".grimoire/infrastructure/scripts/validate-parity.js"
+
+global_required_checks:
+  - paths
+
+ide_matrix:
+  - ide: "claude-code"
+    display_name: "Claude Code"
+    expected_status: "Works"
+    required_checks:
+      - claude-sync
+      - claude-integration
+  - ide: "gemini"
+    display_name: "Gemini CLI"
+    expected_status: "Works"
+    required_checks:
+      - gemini-sync
+      - gemini-integration
+  - ide: "codex"
+    display_name: "Codex CLI"
+    expected_status: "Limited"
+    required_checks:
+      - codex-sync
+      - codex-integration
+      - codex-skills
+  - ide: "cursor"
+    display_name: "Cursor"
+    expected_status: "Limited"
+    required_checks:
+      - cursor-sync
+  - ide: "github-copilot"
+    display_name: "GitHub Copilot"
+    expected_status: "Limited"
+    required_checks:
+      - github-copilot-sync
+  - ide: "antigravity"
+    display_name: "AntiGravity"
+    expected_status: "Limited"
+    required_checks:
+      - antigravity-sync
+
+

package/.grimoire/infrastructure/index.js

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview Infrastructure Module - Entry Point
+ *
+ * Centralizes tools, integrations, scripts, and PM adapters.
+ * This is the base layer of the grimoire modular architecture.
+ *
+ * Uses safe loading to handle optional dependencies gracefully.
+ *
+ * @module infrastructure
+ * @see ADR-002 Migration Map
+ */
+
+/**
+ * Safely require a module, returning null if it fails
+ */
+function safeRequire(modulePath) {
+  try {
+    return require(modulePath);
+  } catch (error) {
+    // Only log in debug mode to avoid noise
+    if (process.env.grimoire_DEBUG) {
+      console.warn(`[infrastructure] Failed to load ${modulePath}: ${error.message}`);
+    }
+    return null;
+  }
+}
+
+// Git Integration
+const GitWrapper = safeRequire('./scripts/git-wrapper');
+const GitConfigDetector = safeRequire('./scripts/git-config-detector');
+const BranchManager = safeRequire('./scripts/branch-manager');
+const CommitMessageGenerator = safeRequire('./scripts/commit-message-generator');
+
+// PM Integration
+const pmAdapter = safeRequire('./scripts/pm-adapter');
+const PMAdapter = pmAdapter ? pmAdapter.PMAdapter : null;
+const pmFactory = safeRequire('./scripts/pm-adapter-factory');
+const getPMAdapter = pmFactory ? pmFactory.getPMAdapter : null;
+const isPMToolConfigured = pmFactory ? pmFactory.isPMToolConfigured : null;
+const clearPMAdapterCache = pmFactory ? pmFactory.clearPMAdapterCache : null;
+const StatusMapper = safeRequire('./scripts/status-mapper');
+const ClickUpHelpers = safeRequire('./scripts/clickup-helpers');
+
+// Template & Generation
+const TemplateEngine = safeRequire('./scripts/template-engine');
+const ComponentGenerator = safeRequire('./scripts/component-generator');
+const ComponentMetadata = safeRequire('./scripts/component-metadata');
+const ComponentSearch = safeRequire('./scripts/component-search');
+const BatchCreator = safeRequire('./scripts/batch-creator');
+
+// Validation
+const grimoireValidator = safeRequire('./scripts/grimoire-validator');
+const TemplateValidator = safeRequire('./scripts/template-validator');
+const validateOutputPatternModule = safeRequire('./scripts/validate-output-pattern');
+const validateOutputPattern = validateOutputPatternModule ? validateOutputPatternModule.validateOutputPattern : null;
+const SpotCheckValidator = safeRequire('./scripts/spot-check-validator');
+
+// Analysis
+const DependencyAnalyzer = safeRequire('./scripts/dependency-analyzer');
+const DependencyImpactAnalyzer = safeRequire('./scripts/dependency-impact-analyzer');
+const FrameworkAnalyzer = safeRequire('./scripts/framework-analyzer');
+const CapabilityAnalyzer = safeRequire('./scripts/capability-analyzer');
+const SecurityChecker = safeRequire('./scripts/security-checker');
+const ModificationRiskAssessment = safeRequire('./scripts/modification-risk-assessment');
+
+// Testing
+const CoverageAnalyzer = safeRequire('./scripts/coverage-analyzer');
+const TestGenerator = safeRequire('./scripts/test-generator');
+const TestUtilities = safeRequire('./scripts/test-utilities');
+const TestUtilitiesFast = safeRequire('./scripts/test-utilities-fast');
+const TestQualityAssessment = safeRequire('./scripts/test-quality-assessment');
+const SandboxTester = safeRequire('./scripts/sandbox-tester');
+
+// Performance
+const PerformanceAnalyzer = safeRequire('./scripts/performance-analyzer');
+const PerformanceOptimizer = safeRequire('./scripts/performance-optimizer');
+const PerformanceTracker = safeRequire('./scripts/performance-tracker');
+const PerformanceAndErrorResolver = safeRequire('./scripts/performance-and-error-resolver');
+
+// Quality
+const CodeQualityImprover = safeRequire('./scripts/code-quality-improver');
+const RefactoringSuggester = safeRequire('./scripts/refactoring-suggester');
+const ImprovementEngine = safeRequire('./scripts/improvement-engine');
+const ImprovementValidator = safeRequire('./scripts/improvement-validator');
+const ModificationValidator = safeRequire('./scripts/modification-validator');
+
+// Utilities
+const ConflictResolver = safeRequire('./scripts/conflict-resolver');
+const DocumentationSynchronizer = safeRequire('./scripts/documentation-synchronizer');
+const toolResolver = safeRequire('./scripts/tool-resolver');
+const resolveTool = toolResolver ? toolResolver.resolveTool : null;
+const UsageAnalytics = safeRequire('./scripts/usage-analytics');
+const projectStatusLoader = safeRequire('./scripts/project-status-loader');
+const loadProjectStatus = projectStatusLoader ? projectStatusLoader.loadProjectStatus : null;
+const formatStatusDisplay = projectStatusLoader ? projectStatusLoader.formatStatusDisplay : null;
+const VisualImpactGenerator = safeRequire('./scripts/visual-impact-generator');
+const AtomicLayerClassifier = safeRequire('./scripts/atomic-layer-classifier');
+
+// System
+const BackupManager = safeRequire('./scripts/backup-manager');
+const TransactionManager = safeRequire('./scripts/transaction-manager');
+const RepositoryDetector = safeRequire('./scripts/repository-detector');
+const ApprovalWorkflow = safeRequire('./scripts/approval-workflow');
+
+// Config
+const ConfigCache = safeRequire('./scripts/config-cache');
+const ConfigLoader = safeRequire('./scripts/config-loader');
+const OutputFormatter = safeRequire('./scripts/output-formatter');
+const YamlValidator = safeRequire('./scripts/yaml-validator');
+
+// Build exports object, filtering out null values
+const moduleExports = {
+  // Git Integration
+  GitWrapper,
+  GitConfigDetector,
+  BranchManager,
+  CommitMessageGenerator,
+
+  // PM Integration
+  PMAdapter,
+  getPMAdapter,
+  isPMToolConfigured,
+  clearPMAdapterCache,
+  StatusMapper,
+  ClickUpHelpers,
+
+  // Template & Generation
+  TemplateEngine,
+  ComponentGenerator,
+  ComponentMetadata,
+  ComponentSearch,
+  BatchCreator,
+
+  // Validation
+  grimoireValidator,
+  TemplateValidator,
+  validateOutputPattern,
+  SpotCheckValidator,
+
+  // Analysis
+  DependencyAnalyzer,
+  DependencyImpactAnalyzer,
+  FrameworkAnalyzer,
+  CapabilityAnalyzer,
+  SecurityChecker,
+  ModificationRiskAssessment,
+
+  // Testing
+  CoverageAnalyzer,
+  TestGenerator,
+  TestUtilities,
+  TestUtilitiesFast,
+  TestQualityAssessment,
+  SandboxTester,
+
+  // Performance
+  PerformanceAnalyzer,
+  PerformanceOptimizer,
+  PerformanceTracker,
+  PerformanceAndErrorResolver,
+
+  // Quality
+  CodeQualityImprover,
+  RefactoringSuggester,
+  ImprovementEngine,
+  ImprovementValidator,
+  ModificationValidator,
+
+  // Utilities
+  ConflictResolver,
+  DocumentationSynchronizer,
+  resolveTool,
+  UsageAnalytics,
+  loadProjectStatus,
+  formatStatusDisplay,
+  VisualImpactGenerator,
+  AtomicLayerClassifier,
+
+  // System
+  BackupManager,
+  TransactionManager,
+  RepositoryDetector,
+  ApprovalWorkflow,
+
+  // Config
+  ConfigCache,
+  ConfigLoader,
+  OutputFormatter,
+  YamlValidator,
+};
+
+// Remove null exports for cleaner API
+Object.keys(moduleExports).forEach(key => {
+  if (moduleExports[key] === null) {
+    delete moduleExports[key];
+  }
+});
+
+module.exports = moduleExports;
+

package/.grimoire/infrastructure/integrations/ai-providers/README.md

@@ -0,0 +1,103 @@
+# AI Providers
+
+Multi-provider AI integration for grimoire. Supports Claude Code and Gemini CLI with automatic fallback and task-based routing.
+
+## Architecture
+
+```
+ai-providers/
+├── ai-provider.js           # Base abstract class
+├── claude-provider.js       # Claude Code implementation
+├── gemini-provider.js       # Gemini CLI implementation
+├── ai-provider-factory.js   # Factory with routing and fallback
+└── index.js                 # Module exports
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+const { getPrimaryProvider, executeWithFallback } = require('./ai-providers');
+
+// Get primary provider from config
+const provider = getPrimaryProvider();
+const response = await provider.execute('Write a hello world function');
+
+// Execute with automatic fallback
+const response = await executeWithFallback('Explain this code');
+```
+
+### Task-Based Routing
+
+```javascript
+const { getProviderForTask } = require('./ai-providers');
+
+// Get optimal provider for task type
+const provider = getProviderForTask('code_generation'); // Returns Gemini (faster)
+const provider = getProviderForTask('security');        // Returns Claude (deeper reasoning)
+```
+
+### Direct Provider Access
+
+```javascript
+const { ClaudeProvider, GeminiProvider } = require('./ai-providers');
+
+// Claude
+const claude = new ClaudeProvider({ model: 'claude-3-5-sonnet' });
+const response = await claude.execute('Explain this function');
+
+// Gemini with JSON output
+const gemini = new GeminiProvider({ jsonOutput: true });
+const response = await gemini.executeJson('List 5 best practices');
+```
+
+### Check Provider Status
+
+```javascript
+const { getProvidersStatus } = require('./ai-providers');
+
+const status = await getProvidersStatus();
+console.log(status);
+// {
+//   claude: { available: true, version: '1.0.0', ... },
+//   gemini: { available: true, version: '0.27.0', ... }
+// }
+```
+
+## Configuration
+
+Create `.grimoire-ai-config.yaml` in project root:
+
+```yaml
+ai_providers:
+  primary: claude
+  fallback: gemini
+  routing:
+    simple_tasks: gemini
+    complex_tasks: claude
+
+claude:
+  model: claude-3-5-sonnet
+  timeout: 300000
+
+gemini:
+  model: gemini-2.0-flash
+  previewFeatures: true
+```
+
+## Provider Comparison
+
+| Feature | Claude | Gemini |
+|---------|--------|--------|
+| Best for | Complex reasoning, security | Speed, cost efficiency |
+| JSON output | Manual parsing | Native `--output-format json` |
+| Cost | Higher | ~4x cheaper (Flash) |
+| SWE-bench | ~70% | 78% (Flash) |
+
+## Epic Reference
+
+- **Epic:** GEMINI-INT
+- **Story:** Story 2 - AI Provider Factory Pattern
+- **Status:** Completed
+