grimoire-framework 1.0.0

package/.grimoire/core/synapse/scripts/generate-constitution.js

@@ -0,0 +1,205 @@
+/**
+ * Constitution Generator
+ *
+ * Reads .grimoire/constitution.md and generates .synapse/constitution
+ * in KEY=VALUE format for the SYNAPSE Context Engine L0 layer.
+ *
+ * Usage: node .grimoire/core/synapse/scripts/generate-constitution.js
+ *
+ * @module core/synapse/scripts/generate-constitution
+ * @version 1.0.0
+ * @created Story SYN-8 - Domain Content Files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Roman numeral to Arabic number map (I-X)
+ */
+const ROMAN_TO_ARABIC = {
+  'I': 1, 'II': 2, 'III': 3, 'IV': 4, 'V': 5,
+  'VI': 6, 'VII': 7, 'VIII': 8, 'IX': 9, 'X': 10,
+};
+
+/**
+ * Clean markdown formatting from text
+ * Removes backticks and trims whitespace
+ *
+ * @param {string} text - Text with possible markdown formatting
+ * @returns {string} Cleaned text
+ */
+function cleanText(text) {
+  return text.replace(/`/g, '').trim();
+}
+
+/**
+ * Parse constitution.md and extract articles with their rules
+ *
+ * @param {string} content - Raw markdown content of constitution.md
+ * @returns {Array<{number: number, roman: string, title: string, severity: string, rules: string[]}>}
+ */
+function parseConstitution(content) {
+  if (!content || typeof content !== 'string') {
+    return [];
+  }
+
+  const articles = [];
+
+  // Match article headers: ### I. Title (SEVERITY)
+  const articleRegex = /^### ([IVXLC]+)\.\s+(.+?)\s*\(([^)]+)\)\s*$/gm;
+
+  let match;
+  const articlePositions = [];
+
+  while ((match = articleRegex.exec(content)) !== null) {
+    articlePositions.push({
+      roman: match[1],
+      title: match[2].trim(),
+      severity: match[3].trim(),
+      startIndex: match.index,
+    });
+  }
+
+  for (let i = 0; i < articlePositions.length; i++) {
+    const start = articlePositions[i].startIndex;
+    const end = i + 1 < articlePositions.length
+      ? articlePositions[i + 1].startIndex
+      : content.indexOf('## Governance', start) !== -1
+        ? content.indexOf('## Governance', start)
+        : content.length;
+
+    const articleContent = content.substring(start, end);
+    const rules = extractRules(articleContent);
+
+    const num = ROMAN_TO_ARABIC[articlePositions[i].roman];
+    if (!num) {
+      continue;
+    }
+
+    articles.push({
+      number: num,
+      roman: articlePositions[i].roman,
+      title: articlePositions[i].title,
+      severity: articlePositions[i].severity,
+      rules,
+    });
+  }
+
+  return articles;
+}
+
+/**
+ * Extract rules from article content
+ * Matches bullet points starting with MUST:, MUST NOT:, SHOULD:, SHOULD NOT:, EXCEPTION:
+ *
+ * @param {string} articleContent - Markdown content of a single article
+ * @returns {string[]} Array of rule strings
+ */
+function extractRules(articleContent) {
+  const rules = [];
+  const lines = articleContent.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const ruleMatch = trimmed.match(/^-\s+(MUST(?:\s+NOT)?|SHOULD(?:\s+NOT)?|EXCEPTION):\s+(.+)$/);
+    if (ruleMatch) {
+      rules.push(`${ruleMatch[1]}: ${cleanText(ruleMatch[2])}`);
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Generate KEY=VALUE constitution content from parsed articles
+ *
+ * @param {Array<{number: number, roman: string, title: string, severity: string, rules: string[]}>} articles
+ * @returns {string} KEY=VALUE formatted content
+ */
+function generateConstitution(articles) {
+  const lines = [
+    '# SYNAPSE Constitution Domain (L0)',
+    '# Auto-generated from .grimoire/constitution.md',
+    '# DO NOT EDIT MANUALLY — re-run generate-constitution.js',
+    '',
+  ];
+
+  for (const article of articles) {
+    lines.push(`# Article ${article.roman}: ${article.title} (${article.severity})`);
+
+    // Rule 0: title + severity summary
+    lines.push(`CONSTITUTION_RULE_ART${article.number}_0=${article.title} (${article.severity})`);
+
+    // Subsequent rules from bullet points
+    for (let i = 0; i < article.rules.length; i++) {
+      lines.push(`CONSTITUTION_RULE_ART${article.number}_${i + 1}=${article.rules[i]}`);
+    }
+
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Main entry point: read constitution.md, generate .synapse/constitution
+ *
+ * @param {object} [options] - Override paths for testing
+ * @param {string} [options.projectRoot] - Project root directory
+ * @param {string} [options.constitutionPath] - Path to constitution.md
+ * @param {string} [options.outputPath] - Path to output file
+ * @returns {{success: boolean, articles?: number, rules?: number, outputPath?: string, error?: string}}
+ */
+function main(options = {}) {
+  const projectRoot = options.projectRoot || path.resolve(__dirname, '..', '..', '..', '..');
+  const constitutionPath = options.constitutionPath || path.join(projectRoot, '.grimoire', 'constitution.md');
+  const outputPath = options.outputPath || path.join(projectRoot, '.synapse', 'constitution');
+
+  // Read source
+  let content;
+  try {
+    content = fs.readFileSync(constitutionPath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.error(`Constitution not found: ${constitutionPath}`);
+      process.exitCode = 1;
+      return { success: false, error: 'Constitution file not found' };
+    }
+    throw error;
+  }
+
+  // Parse articles
+  const articles = parseConstitution(content);
+
+  if (articles.length === 0) {
+    console.error('No articles found in constitution.md');
+    process.exitCode = 1;
+    return { success: false, error: 'No articles found' };
+  }
+
+  // Generate output
+  const output = generateConstitution(articles);
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write output (idempotent — overwrites cleanly)
+  fs.writeFileSync(outputPath, output, 'utf8');
+
+  const totalRules = articles.reduce((sum, a) => sum + a.rules.length + 1, 0);
+  console.log(`Constitution generated: ${articles.length} articles, ${totalRules} rules`);
+
+  return { success: true, articles: articles.length, rules: totalRules, outputPath };
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseConstitution, extractRules, generateConstitution, cleanText, main, ROMAN_TO_ARABIC };
+

package/.grimoire/core/synapse/session/session-manager.js

@@ -0,0 +1,403 @@
+/**
+ * SYNAPSE Session Manager
+ *
+ * Manages session state (active agent, workflow, task, squad) persisted as JSON.
+ * Sessions are stored in `.synapse/sessions/{uuid}.json` using schema v2.0.
+ *
+ * Features:
+ * - CRUD operations for sessions
+ * - Stale session cleanup (>24h inactive)
+ * - Auto-title generation from first meaningful prompt
+ * - Gitignore creation for sessions/ and cache/
+ *
+ * @module core/synapse/session/session-manager
+ * @version 1.0.0
+ * @created Story SYN-2 - Session Manager
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = '2.0';
+const DEFAULT_MAX_AGE_HOURS = 24;
+const MAX_TITLE_LENGTH = 50;
+
+/**
+ * Build the default session object conforming to schema v2.0
+ *
+ * @param {string} sessionId - UUID from Claude Code
+ * @param {string} cwd - Working directory
+ * @returns {object} Session object with schema v2.0 defaults
+ */
+function buildDefaultSession(sessionId, cwd) {
+  const now = new Date().toISOString();
+  const label = path.basename(cwd);
+
+  return {
+    uuid: sessionId,
+    schema_version: SCHEMA_VERSION,
+    started: now,
+    last_activity: now,
+    cwd,
+    label,
+    title: null,
+    prompt_count: 0,
+    active_agent: { id: null, activated_at: null, activation_quality: null },
+    active_workflow: null,
+    active_squad: null,
+    active_task: null,
+    context: { last_bracket: 'FRESH', last_tokens_used: 0, last_context_percent: 100 },
+    overrides: {},
+    history: { star_commands_used: [], domains_loaded_last: [], agents_activated: [] },
+  };
+}
+
+/**
+ * Resolve sessions directory path from a base .synapse/ path
+ *
+ * @param {string} sessionsDir - Path to sessions directory
+ * @returns {string} Resolved sessions directory path
+ */
+function resolveSessionFile(sessionId, sessionsDir) {
+  // Sanitize sessionId to prevent path traversal
+  if (typeof sessionId !== 'string' || sessionId.includes('..') || sessionId.includes('/') || sessionId.includes('\\')) {
+    throw new Error('[synapse:session] Invalid sessionId: contains path separators or traversal');
+  }
+
+  const filePath = path.join(sessionsDir, `${sessionId}.json`);
+  const resolved = path.resolve(filePath);
+  const resolvedDir = path.resolve(sessionsDir);
+
+  if (!resolved.startsWith(resolvedDir + path.sep) && resolved !== resolvedDir) {
+    throw new Error('[synapse:session] Invalid sessionId: resolved path escapes sessions directory');
+  }
+
+  return filePath;
+}
+
+/**
+ * Ensure a directory exists, creating it recursively if needed
+ *
+ * @param {string} dirPath - Directory path to ensure
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Ensure .synapse/.gitignore exists with required entries
+ *
+ * @param {string} synapsePath - Path to .synapse/ directory
+ */
+function ensureGitignore(synapsePath) {
+  const gitignorePath = path.join(synapsePath, '.gitignore');
+
+  if (fs.existsSync(gitignorePath)) {
+    return;
+  }
+
+  const content = [
+    '# SYNAPSE runtime data (auto-generated)',
+    'sessions/',
+    'cache/',
+    '',
+  ].join('\n');
+
+  ensureDir(synapsePath);
+  fs.writeFileSync(gitignorePath, content, 'utf8');
+}
+
+/**
+ * Create a new session
+ *
+ * Creates the session JSON file with schema v2.0 defaults.
+ * Auto-creates the sessions/ directory and .gitignore if they don't exist.
+ *
+ * @param {string} sessionId - UUID from Claude Code
+ * @param {string} cwd - Working directory
+ * @param {string} [sessionsDir] - Sessions directory (default: cwd/.synapse/sessions)
+ * @returns {object} Created session object
+ */
+function createSession(sessionId, cwd, sessionsDir) {
+  const dir = sessionsDir || path.join(cwd, '.synapse', 'sessions');
+  ensureDir(dir);
+
+  // Ensure .gitignore exists in .synapse/
+  const synapsePath = path.dirname(dir);
+  ensureGitignore(synapsePath);
+
+  const session = buildDefaultSession(sessionId, cwd);
+  const filePath = resolveSessionFile(sessionId, dir);
+
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(session, null, 2), 'utf8');
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      console.error(`[synapse:session] Error: Permission denied creating session ${sessionId}`);
+      return null;
+    }
+    throw error;
+  }
+
+  return session;
+}
+
+/**
+ * Load an existing session
+ *
+ * @param {string} sessionId - Session UUID
+ * @param {string} sessionsDir - Path to sessions directory
+ * @returns {object|null} Session object, or null if not found or corrupted
+ */
+function loadSession(sessionId, sessionsDir) {
+  const filePath = resolveSessionFile(sessionId, sessionsDir);
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const session = JSON.parse(raw);
+
+    if (session.schema_version !== SCHEMA_VERSION) {
+      console.warn(
+        `[synapse:session] Warning: Session ${sessionId} has schema_version "${session.schema_version}", expected "${SCHEMA_VERSION}"`,
+      );
+      return null;
+    }
+
+    return session;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      console.warn(`[synapse:session] Warning: Corrupted JSON for session ${sessionId}`);
+      return null;
+    }
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      console.error(`[synapse:session] Error: Permission denied reading session ${sessionId}`);
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Update an existing session with partial merge
+ *
+ * Deep-merges the updates into the existing session.
+ * Increments prompt_count and updates last_activity on every call.
+ *
+ * @param {string} sessionId - Session UUID
+ * @param {string} sessionsDir - Path to sessions directory
+ * @param {object} updates - Partial updates to merge
+ * @returns {object|null} Updated session, or null if session not found
+ */
+function updateSession(sessionId, sessionsDir, updates) {
+  const session = loadSession(sessionId, sessionsDir);
+
+  if (!session) {
+    return null;
+  }
+
+  // Shallow merge top-level fields
+  for (const [key, value] of Object.entries(updates)) {
+    if (key === 'history' && typeof value === 'object' && value !== null) {
+      // Merge history arrays by appending unique values
+      session.history = mergeHistory(session.history, value);
+    } else if (key === 'overrides' && typeof value === 'object' && value !== null) {
+      // Merge overrides
+      Object.assign(session.overrides, value);
+    } else if (key === 'context' && typeof value === 'object' && value !== null) {
+      // Merge context
+      Object.assign(session.context, value);
+    } else if (key === 'active_agent' && typeof value === 'object' && value !== null) {
+      // Replace active_agent entirely
+      session.active_agent = value;
+    } else {
+      session[key] = value;
+    }
+  }
+
+  // Always increment prompt_count and update last_activity
+  session.prompt_count += 1;
+  session.last_activity = new Date().toISOString();
+
+  const filePath = resolveSessionFile(sessionId, sessionsDir);
+
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(session, null, 2), 'utf8');
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      console.error(`[synapse:session] Error: Permission denied writing session ${sessionId}`);
+      return null;
+    }
+    throw error;
+  }
+
+  return session;
+}
+
+/**
+ * Merge history objects by appending unique values to arrays
+ *
+ * @param {object} existing - Existing history
+ * @param {object} incoming - Incoming history updates
+ * @returns {object} Merged history
+ */
+function mergeHistory(existing, incoming) {
+  const merged = { ...existing };
+
+  for (const [key, value] of Object.entries(incoming)) {
+    if (Array.isArray(value) && Array.isArray(merged[key])) {
+      const combined = [...merged[key]];
+      for (const item of value) {
+        if (!combined.includes(item)) {
+          combined.push(item);
+        }
+      }
+      merged[key] = combined;
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Delete a session
+ *
+ * @param {string} sessionId - Session UUID
+ * @param {string} sessionsDir - Path to sessions directory
+ * @returns {boolean} True if deleted, false if not found
+ */
+function deleteSession(sessionId, sessionsDir) {
+  const filePath = resolveSessionFile(sessionId, sessionsDir);
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      return false;
+    }
+
+    fs.unlinkSync(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      console.error(`[synapse:session] Error: Permission denied deleting session ${sessionId}`);
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Clean stale sessions (inactive for more than maxAgeHours)
+ *
+ * Reads each session file individually to avoid loading all into memory.
+ * Does not fail if sessions directory doesn't exist.
+ *
+ * @param {string} sessionsDir - Path to sessions directory
+ * @param {number} [maxAgeHours=24] - Maximum inactivity threshold in hours
+ * @returns {number} Count of removed sessions
+ */
+function cleanStaleSessions(sessionsDir, maxAgeHours = DEFAULT_MAX_AGE_HOURS) {
+  ensureDir(sessionsDir);
+
+  let removedCount = 0;
+  const cutoffMs = maxAgeHours * 60 * 60 * 1000;
+  const now = Date.now();
+
+  let files;
+  try {
+    files = fs.readdirSync(sessionsDir);
+  } catch (_error) {
+    return 0;
+  }
+
+  for (const file of files) {
+    if (!file.endsWith('.json')) {
+      continue;
+    }
+
+    const filePath = path.join(sessionsDir, file);
+
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const session = JSON.parse(raw);
+
+      if (session.last_activity) {
+        const lastActivity = new Date(session.last_activity).getTime();
+        const age = now - lastActivity;
+
+        if (age > cutoffMs) {
+          fs.unlinkSync(filePath);
+          removedCount++;
+        }
+      }
+    } catch (_error) {
+      // Skip corrupted files during cleanup
+      continue;
+    }
+  }
+
+  return removedCount;
+}
+
+/**
+ * Generate a title from a user prompt
+ *
+ * Extracts a meaningful title (max 50 chars) from the first significant prompt.
+ * Ignores *commands and single-word prompts.
+ *
+ * @param {string} prompt - User prompt text
+ * @returns {string|null} Generated title, or null if prompt is not title-worthy
+ */
+function generateTitle(prompt) {
+  if (!prompt || typeof prompt !== 'string') {
+    return null;
+  }
+
+  const trimmed = prompt.trim();
+
+  // Ignore *commands
+  if (trimmed.startsWith('*')) {
+    return null;
+  }
+
+  // Ignore single words
+  if (!trimmed.includes(' ')) {
+    return null;
+  }
+
+  // Ignore very short prompts (less than 3 chars)
+  if (trimmed.length < 3) {
+    return null;
+  }
+
+  // Truncate to max length, respecting word boundaries
+  if (trimmed.length <= MAX_TITLE_LENGTH) {
+    return trimmed;
+  }
+
+  const truncated = trimmed.substring(0, MAX_TITLE_LENGTH);
+  const lastSpace = truncated.lastIndexOf(' ');
+
+  if (lastSpace > 0) {
+    return truncated.substring(0, lastSpace);
+  }
+
+  return truncated;
+}
+
+module.exports = {
+  createSession,
+  loadSession,
+  updateSession,
+  deleteSession,
+  cleanStaleSessions,
+  generateTitle,
+  ensureGitignore,
+  SCHEMA_VERSION,
+};

package/.grimoire/core/synapse/utils/paths.js

@@ -0,0 +1,57 @@
+/**
+ * SYNAPSE Path Utilities
+ *
+ * Cross-platform path resolution for the .synapse/ directory.
+ * Compatible with Windows (backslash) and Unix (forward slash).
+ *
+ * @module core/synapse/utils/paths
+ * @version 1.0.0
+ * @created Story SYN-1 - Domain Loader + Manifest Parser
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Resolve the .synapse/ directory path from a given working directory
+ *
+ * Looks for a `.synapse/` directory in the given cwd.
+ * Uses path.join for cross-platform compatibility (Windows \ and Unix /).
+ *
+ * @param {string} cwd - The working directory to search from
+ * @returns {{ exists: boolean, synapsePath: string, manifestPath: string }}
+ */
+function resolveSynapsePath(cwd) {
+  const synapsePath = path.join(cwd, '.synapse');
+  const manifestPath = path.join(synapsePath, 'manifest');
+
+  let exists = false;
+  try {
+    const stat = fs.statSync(synapsePath);
+    exists = stat.isDirectory();
+  } catch (_error) {
+    exists = false;
+  }
+
+  return {
+    exists,
+    synapsePath,
+    manifestPath,
+  };
+}
+
+/**
+ * Resolve a domain file path within the .synapse/ directory
+ *
+ * @param {string} synapsePath - Path to .synapse/ directory
+ * @param {string} fileName - Domain file name (e.g., 'agent-dev')
+ * @returns {string} Full path to domain file
+ */
+function resolveDomainPath(synapsePath, fileName) {
+  return path.join(synapsePath, fileName);
+}
+
+module.exports = {
+  resolveSynapsePath,
+  resolveDomainPath,
+};

package/.grimoire/core/synapse/utils/tokens.js

@@ -0,0 +1,25 @@
+/**
+ * SYNAPSE Token Utilities
+ *
+ * Shared token estimation used by formatter and memory bridge.
+ *
+ * @module core/synapse/utils/tokens
+ * @version 1.0.0
+ * @created Story SYN-10 - Pro Memory Bridge (extracted from formatter.js)
+ */
+
+'use strict';
+
+/**
+ * Estimate the number of tokens from a string.
+ *
+ * Uses the proven heuristic: tokens ~ string.length / 4
+ *
+ * @param {string} text - Text to estimate
+ * @returns {number} Estimated token count
+ */
+function estimateTokens(text) {
+  return Math.ceil((text || '').length / 4);
+}
+
+module.exports = { estimateTokens };