@soleri/forge 9.9.0 → 9.10.0

package/src/compose-claude-md.ts

@@ -11,6 +11,57 @@ import { parse as parseYaml } from 'yaml';
 import { AgentYamlSchema, type AgentYaml } from './agent-schema.js';
 import { ENGINE_MODULE_MANIFEST, CORE_KEY_OPS } from '@soleri/core/module-manifest';
 
+// ─── User Custom Zone ────────────────────────────────────────────────
+
+const USER_CUSTOM_OPEN = '<!-- user:custom -->';
+const USER_CUSTOM_CLOSE = '<!-- /user:custom -->';
+
+const DEFAULT_USER_CUSTOM_BLOCK = [
+  USER_CUSTOM_OPEN,
+  '<!-- Add your custom instructions here. This section survives regeneration. -->',
+  USER_CUSTOM_CLOSE,
+].join('\n');
+
+/**
+ * Extract content between `<!-- user:custom -->` and `<!-- /user:custom -->` markers.
+ * Returns the full block (including markers) or null if not found.
+ */
+export function extractUserCustomZone(content: string): string | null {
+  const openIdx = content.indexOf(USER_CUSTOM_OPEN);
+  if (openIdx === -1) return null;
+
+  const closeIdx = content.indexOf(USER_CUSTOM_CLOSE, openIdx);
+  if (closeIdx === -1) return null;
+
+  return content.slice(openIdx, closeIdx + USER_CUSTOM_CLOSE.length);
+}
+
+/**
+ * Inject a user:custom zone into composed CLAUDE.md content.
+ * Replaces the existing user:custom block if present, otherwise inserts
+ * before the engine-rules-ref marker (or appends at the end).
+ */
+export function injectUserCustomZone(content: string, userZone: string): string {
+  // If the content already has a user:custom block, replace it
+  const existing = extractUserCustomZone(content);
+  if (existing) {
+    return content.replace(existing, userZone);
+  }
+
+  // Insert before engine-rules-ref if present
+  const engineRefMarker = '<!-- soleri:engine-rules-ref -->';
+  const engineIdx = content.indexOf(engineRefMarker);
+  if (engineIdx !== -1) {
+    return content.slice(0, engineIdx) + userZone + '\n\n' + content.slice(engineIdx);
+  }
+
+  // Fallback: append before the last newline
+  if (content.endsWith('\n')) {
+    return content.slice(0, -1) + '\n\n' + userZone + '\n';
+  }
+  return content + '\n\n' + userZone + '\n';
+}
+
 // ─── Types ────────────────────────────────────────────────────────────
 
 export interface ComposedClaudeMd {
@@ -37,6 +88,15 @@ export interface ToolEntry {
 export function composeClaudeMd(agentDir: string, tools?: ToolEntry[]): ComposedClaudeMd {
   const sources: string[] = [];
 
+  // 0. Read existing CLAUDE.md to preserve user:custom zone
+  const existingClaudeMdPath = join(agentDir, 'CLAUDE.md');
+  let preservedUserZone: string | null = null;
+  let existingContent: string | null = null;
+  if (existsSync(existingClaudeMdPath)) {
+    existingContent = readFileSync(existingClaudeMdPath, 'utf-8');
+    preservedUserZone = extractUserCustomZone(existingContent);
+  }
+
   // 1. Read agent.yaml
   const agentYamlPath = join(agentDir, 'agent.yaml');
   const agentYaml = AgentYamlSchema.parse(parseYaml(readFileSync(agentYamlPath, 'utf-8')));
@@ -128,10 +188,74 @@ export function composeClaudeMd(agentDir: string, tools?: ToolEntry[]): Composed
     if (skillsSection) sections.push(skillsSection);
   }
 
+  // 10. Inject user:custom zone (preserved from old file, or default empty block)
+  const userZone = preservedUserZone ?? DEFAULT_USER_CUSTOM_BLOCK;
+  sections.splice(findUserCustomInsertIndex(sections), 0, userZone);
+
   const content = sections.join('\n\n') + '\n';
+
+  // 11. Detect orphaned content in old file (compare against newly composed content)
+  if (existingContent) {
+    detectOrphanedContent(existingContent, content);
+  }
+
   return { content, sources };
 }
 
+// ─── User Custom Zone Helpers ────────────────────────────────────────
+
+/**
+ * Find the insertion index for the user:custom zone in the sections array.
+ * Target: after user instructions (instructions/user.md content), before engine-rules-ref.
+ */
+function findUserCustomInsertIndex(sections: string[]): number {
+  // Look for the engine-rules-ref marker
+  const engineRefIdx = sections.findIndex((s) => s.includes('<!-- soleri:engine-rules-ref -->'));
+  if (engineRefIdx !== -1) return engineRefIdx;
+
+  // Fallback: insert before the last section
+  return sections.length;
+}
+
+/**
+ * Detect content in existing CLAUDE.md that was manually added outside of
+ * the user:custom zone. Compares the old file's headings against a freshly
+ * composed version — any heading in the old file that doesn't appear in
+ * the new composition (and isn't inside user:custom) is orphaned.
+ *
+ * @param existingContent - The current CLAUDE.md content before regeneration
+ * @param newContent - The freshly composed CLAUDE.md content
+ */
+function detectOrphanedContent(existingContent: string, newContent: string): void {
+  // Extract headings from old file (excluding those inside user:custom zone)
+  const oldHeadings = extractHeadingsOutsideUserCustom(existingContent);
+  if (oldHeadings.length === 0) return;
+
+  // Extract headings from new composed content
+  const newHeadingSet = new Set(newContent.match(/^#{1,3} .+$/gm)?.map((h) => h.trim()) ?? []);
+
+  // Find headings in old that don't exist in new
+  const orphaned = oldHeadings.filter((h) => !newHeadingSet.has(h));
+
+  if (orphaned.length > 0) {
+    process.stderr.write(
+      '\u26a0 CLAUDE.md contains content outside managed sections. ' +
+        'Move to instructions/ or <!-- user:custom --> to preserve across regeneration.\n',
+    );
+  }
+}
+
+/**
+ * Extract markdown headings from content, excluding any inside the user:custom zone.
+ */
+function extractHeadingsOutsideUserCustom(content: string): string[] {
+  // Remove user:custom zone content first
+  const userZone = extractUserCustomZone(content);
+  const cleaned = userZone ? content.replace(userZone, '') : content;
+
+  return cleaned.match(/^#{1,3} .+$/gm)?.map((h) => h.trim()) ?? [];
+}
+
 // ─── Section Composers ────────────────────────────────────────────────
 
 function composeIdentityBlock(agent: AgentYaml): string {

package/src/lib.ts

@@ -34,7 +34,13 @@ export { composeClaudeMd } from './compose-claude-md.js';
 export type { ComposedClaudeMd, ToolEntry } from './compose-claude-md.js';
 export { generateExtensionsIndex, generateExampleOp } from './templates/extensions.js';
 export { generateClaudeMdTemplate } from './templates/claude-md-template.js';
-export { getEngineRulesContent, getEngineMarker } from './templates/shared-rules.js';
+export {
+  getEngineRulesContent,
+  getEngineMarker,
+  getModularEngineRules,
+  ENGINE_FEATURES,
+} from './templates/shared-rules.js';
+export type { EngineFeature } from './templates/shared-rules.js';
 export { generateInjectClaudeMd } from './templates/inject-claude-md.js';
 export { generateSkills } from './templates/skills.js';
 export { generateTelegramBot } from './templates/telegram-bot.js';

package/src/scaffold-filetree.ts

@@ -13,7 +13,8 @@ import { fileURLToPath } from 'node:url';
 import { stringify as yamlStringify } from 'yaml';
 import type { AgentYaml, AgentYamlInput } from './agent-schema.js';
 import { AgentYamlSchema } from './agent-schema.js';
-import { getEngineRulesContent } from './templates/shared-rules.js';
+import { getModularEngineRules } from './templates/shared-rules.js';
+import type { EngineFeature } from './templates/shared-rules.js';
 import { composeClaudeMd } from './compose-claude-md.js';
 import { generateSkills } from './templates/skills.js';
 import type { AgentConfig } from './types.js';
@@ -567,8 +568,14 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     filesCreated,
   );
 
-  // ─── 5. Write engine rules ──────────────────────────────────
-  writeFile(agentDir, 'instructions/_engine.md', getEngineRulesContent(), filesCreated);
+  // ─── 5. Write engine rules (modular — respects engine.features) ─────
+  const engineFeatures = config.engine?.features as EngineFeature[] | undefined;
+  writeFile(
+    agentDir,
+    'instructions/_engine.md',
+    getModularEngineRules(engineFeatures),
+    filesCreated,
+  );
 
   // ─── 6. Write user instruction files ────────────────────────
   // Generate user.md — user-editable file with priority placement in CLAUDE.md

package/src/templates/inject-claude-md.ts

@@ -70,10 +70,15 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     ' * `<!-- soleri:engine-rules -->`. If already present, they are updated.',
     ' * Agent block (identity + facade table) is injected under',
     ` * \`<!-- ${marker} -->\`.`,
+    ' *',
+    ' * @param skipEngineRules - If true, skip engine rules injection (used for global files)',
     ' */',
-    'function injectIntoFile(filePath: string): InjectResult {',
-    '  // Step 1: Engine rules — shared across all agents',
-    '  const engineAction = injectBlock(filePath, getEngineRulesContent(), getEngineRulesMarker());',
+    'function injectIntoFile(filePath: string, skipEngineRules = false): InjectResult {',
+    '  // Step 1: Engine rules — shared across all agents (skip for global files)',
+    '  let engineAction: string = "skipped";',
+    '  if (!skipEngineRules) {',
+    '    engineAction = injectBlock(filePath, getEngineRulesContent(), getEngineRulesMarker());',
+    '  }',
     '',
     '  // Step 2: Agent-specific block',
     '  const agentAction = injectBlock(filePath, getClaudeMdContent(), getClaudeMdMarker());',
@@ -99,13 +104,24 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     ' * Inject into the global ~/.claude/CLAUDE.md.',
     " * Creates ~/.claude/ directory if it doesn't exist.",
     ' * This makes the activation phrase work in any project.',
+    ' * Engine rules are NOT injected globally — they live in project-level CLAUDE.md only.',
     ' */',
     'export function injectClaudeMdGlobal(): InjectResult {',
     "  const claudeDir = join(homedir(), '.claude');",
     '  if (!existsSync(claudeDir)) {',
     '    mkdirSync(claudeDir, { recursive: true });',
     '  }',
-    "  return injectIntoFile(join(claudeDir, 'CLAUDE.md'));",
+    "  const filePath = join(claudeDir, 'CLAUDE.md');",
+    '',
+    '  // Add header comment for new files',
+    '  if (!existsSync(filePath)) {',
+    "    writeFileSync(filePath, '<!-- Global agent activation file. Engine rules live in project-level CLAUDE.md only. -->\\n', 'utf-8');",
+    '  }',
+    '',
+    '  // Self-heal: strip engine rules if they leaked into the global file',
+    '  removeBlock(filePath, getEngineRulesMarker());',
+    '',
+    '  return injectIntoFile(filePath, true);',
     '}',
     '',
     '/**',
@@ -154,6 +170,24 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     '}',
     '',
     '/**',
+    ' * Remove engine rules from the global ~/.claude/CLAUDE.md.',
+    ' * Self-healing: strips engine rules that should not be in the global file.',
+    ' */',
+    'export function removeEngineRulesFromGlobal(): { removed: boolean; path: string } {',
+    "  const filePath = join(homedir(), '.claude', 'CLAUDE.md');",
+    '  return { removed: removeBlock(filePath, getEngineRulesMarker()), path: filePath };',
+    '}',
+    '',
+    '/**',
+    ' * Remove engine rules from the global ~/.config/opencode/AGENTS.md.',
+    ' * Self-healing: strips engine rules that should not be in the global file.',
+    ' */',
+    'export function removeEngineRulesFromGlobalAgentsMd(): { removed: boolean; path: string } {',
+    "  const filePath = join(homedir(), '.config', 'opencode', 'AGENTS.md');",
+    '  return { removed: removeBlock(filePath, getEngineRulesMarker()), path: filePath };',
+    '}',
+    '',
+    '/**',
     ' * Check if the agent marker exists in a CLAUDE.md file.',
     ' */',
     'export function hasAgentMarker(filePath: string): boolean {',
@@ -186,13 +220,24 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     ' * Inject into the global ~/.config/opencode/AGENTS.md.',
     " * Creates ~/.config/opencode/ directory if it doesn't exist.",
     ' * This makes the activation phrase work in any OpenCode project.',
+    ' * Engine rules are NOT injected globally — they live in project-level AGENTS.md only.',
     ' */',
     'export function injectAgentsMdGlobal(): InjectResult {',
     "  const opencodeDir = join(homedir(), '.config', 'opencode');",
     '  if (!existsSync(opencodeDir)) {',
     '    mkdirSync(opencodeDir, { recursive: true });',
     '  }',
-    "  return injectIntoFile(join(opencodeDir, 'AGENTS.md'));",
+    "  const filePath = join(opencodeDir, 'AGENTS.md');",
+    '',
+    '  // Add header comment for new files',
+    '  if (!existsSync(filePath)) {',
+    "    writeFileSync(filePath, '<!-- Global agent activation file. Engine rules live in project-level AGENTS.md only. -->\\n', 'utf-8');",
+    '  }',
+    '',
+    '  // Self-heal: strip engine rules if they leaked into the global file',
+    '  removeBlock(filePath, getEngineRulesMarker());',
+    '',
+    '  return injectIntoFile(filePath, true);',
     '}',
     '',
     '/**',

package/src/templates/section-parser.ts

@@ -0,0 +1,97 @@
+/**
+ * Section parser for marker-delimited engine rules content.
+ *
+ * Extracts `<!-- soleri:xxx -->` sections from the engine rules markdown,
+ * enabling selective inclusion of feature modules.
+ *
+ * Single-pass: splits on `## ` headings, maps chunks to markers, filters.
+ */
+
+export interface ParsedSection {
+  /** e.g. 'soleri:response-integrity' */
+  marker: string;
+  /** Full text including heading and marker comment */
+  content: string;
+}
+
+export interface ParsedContent {
+  /** Everything before the first section */
+  preamble: string;
+  /** Ordered list of parsed sections */
+  sections: ParsedSection[];
+  /** Closing marker line and anything after */
+  closing: string;
+}
+
+const SECTION_MARKER_RE = /<!-- (soleri:[a-z-]+) -->/;
+const CLOSING_MARKER = '<!-- /soleri:engine-rules -->';
+
+/**
+ * Parse marker-delimited sections from engine rules content.
+ *
+ * Strategy: split on `## ` heading boundaries, then classify each chunk
+ * as preamble, section (has a marker), or closing (has closing marker).
+ */
+export function parseSections(content: string): ParsedContent {
+  // Split at each `## ` heading — lookahead preserves the heading in the chunk
+  const chunks = content.split(/(?=^## )/m);
+
+  let preamble = '';
+  const sections: ParsedSection[] = [];
+  let closing = '';
+  let foundFirstSection = false;
+
+  for (const chunk of chunks) {
+    // Check if this chunk contains the closing marker
+    const closingIdx = chunk.indexOf(CLOSING_MARKER);
+    if (closingIdx !== -1) {
+      // Content before closing marker belongs to last section or preamble
+      const beforeClosing = chunk.slice(0, closingIdx);
+      const afterClosing = chunk.slice(closingIdx);
+
+      if (beforeClosing.trim()) {
+        const markerMatch = beforeClosing.match(SECTION_MARKER_RE);
+        if (markerMatch && markerMatch[1] !== 'soleri:engine-rules') {
+          sections.push({ marker: markerMatch[1], content: beforeClosing });
+          foundFirstSection = true;
+        } else if (!foundFirstSection) {
+          preamble += beforeClosing;
+        }
+      }
+      closing = afterClosing;
+      continue;
+    }
+
+    // Check if chunk has a section marker
+    const markerMatch = chunk.match(SECTION_MARKER_RE);
+    if (markerMatch && markerMatch[1] !== 'soleri:engine-rules') {
+      sections.push({ marker: markerMatch[1], content: chunk });
+      foundFirstSection = true;
+    } else {
+      // No marker — this is preamble (before first section)
+      if (!foundFirstSection) {
+        preamble += chunk;
+      }
+    }
+  }
+
+  return { preamble, sections, closing };
+}
+
+/**
+ * Rebuild content from parsed sections, including only allowed markers.
+ */
+export function filterSections(parsed: ParsedContent, allowedMarkers: Set<string>): string {
+  const parts: string[] = [parsed.preamble];
+
+  for (const section of parsed.sections) {
+    if (allowedMarkers.has(section.marker)) {
+      let text = section.content;
+      if (!text.endsWith('\n')) text += '\n';
+      parts.push(text);
+    }
+  }
+
+  parts.push(parsed.closing);
+  return parts.join('\n');
+}

package/src/templates/shared-rules.ts

@@ -9,6 +9,8 @@
  * Uses op:name syntax — the active agent provides the tool prefix.
  */
 
+import { parseSections, filterSections } from './section-parser.js';
+
 const ENGINE_MARKER = 'soleri:engine-rules';
 
 export function getEngineMarker(): string {
@@ -20,6 +22,83 @@ export function getEngineRulesContent(): string {
   return ENGINE_RULES_LINES.join('\n');
 }
 
+// ─── Modular Engine Rules ────────────────────────────────────────────
+
+/** Feature modules that can be selectively included in engine rules. */
+export type EngineFeature = 'vault' | 'planning' | 'brain' | 'advanced';
+
+/** All available feature modules. */
+export const ENGINE_FEATURES: readonly EngineFeature[] = [
+  'vault',
+  'planning',
+  'brain',
+  'advanced',
+] as const;
+
+/**
+ * Section markers grouped by module.
+ *
+ * 'core' sections are always included.
+ * Feature modules are included only when requested (or when no filter is specified).
+ */
+const MODULE_SECTIONS: Record<'core' | EngineFeature, readonly string[]> = {
+  core: [
+    'soleri:what-is-soleri',
+    'soleri:response-integrity',
+    'soleri:tool-schema-validation',
+    'soleri:memory-quality',
+    'soleri:output-formatting',
+    'soleri:clean-commits',
+    'soleri:intent-detection',
+    'soleri:overlay-mode',
+    'soleri:session',
+    'soleri:getting-started',
+    'soleri:cli',
+    'soleri:persona-self-update',
+    'soleri:workspace-routing',
+  ],
+  vault: [
+    'soleri:vault-protocol',
+    'soleri:knowledge-capture',
+    'soleri:tool-advocacy',
+    'soleri:cross-project',
+  ],
+  planning: [
+    'soleri:planning',
+    'soleri:workflow-overrides',
+    'soleri:yolo-mode',
+    'soleri:task-routing',
+    'soleri:validation-loop',
+    'soleri:verification-protocol',
+  ],
+  brain: ['soleri:brain', 'soleri:model-routing'],
+  advanced: ['soleri:subagent-identity'],
+};
+
+/**
+ * Returns engine rules with only selected feature modules included.
+ *
+ * Core rules are ALWAYS included. Feature modules are included when:
+ * - `features` is undefined/empty → ALL modules included (backward compatible)
+ * - `features` is specified → only listed modules + core
+ *
+ * @param features - Feature modules to include. Omit for all.
+ */
+export function getModularEngineRules(features?: EngineFeature[]): string {
+  if (!features || features.length === 0) {
+    return getEngineRulesContent();
+  }
+
+  const allowedMarkers = new Set<string>(MODULE_SECTIONS.core);
+  for (const feature of features) {
+    const sections = MODULE_SECTIONS[feature];
+    if (sections) for (const m of sections) allowedMarkers.add(m);
+  }
+
+  const parsed = parseSections(getEngineRulesContent());
+  return filterSections(parsed, allowedMarkers);
+}
+
 const ENGINE_RULES_LINES: string[] = [
   `<!-- ${ENGINE_MARKER} -->`,
   '',
@@ -683,28 +762,28 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### How Your CLAUDE.md is Built',
   '',
-  'Your CLAUDE.md is **auto-generated** — never edit it manually. It gets regenerated by `composeClaudeMd()` in these scenarios:',
-  '',
-  '| Trigger | How |',
-  '|---------|-----|',
-  '| `soleri dev` | Hot-reloads and regenerates on file changes |',
-  '| `soleri agent refresh` | Explicitly regenerates from latest templates |',
-  '| `soleri agent update` | After engine update, regenerates to pick up new rules |',
-  '| Scaffold (`create-soleri`) | Generates initial CLAUDE.md for new agents |',
+  'Your CLAUDE.md is **auto-generated** — never edit it manually (except inside `<!-- user:custom -->` markers). Regenerated by `soleri dev`, `soleri agent refresh`, `soleri agent update`, and on scaffold.',
   '',
   'The composition pipeline assembles CLAUDE.md from:',
   '',
   '1. **Agent identity** — from `agent.yaml`',
   '2. **Custom instructions** — from `instructions/user.md` (priority placement, before engine rules)',
-  '3. **Engine rules** — from `@soleri/forge` shared rules (this section)',
+  '3. **Engine rules** — modular, controlled by `engine.features` in `agent.yaml`',
   '4. **User instructions** — from `instructions/*.md` (alphabetically sorted, excluding `user.md` and `_engine.md`)',
   '5. **Tools table** — from engine registration',
   '6. **Workflow index** — from `workflows/`',
   '7. **Skills index** — from `skills/`',
   '',
-  '`instructions/user.md` is the recommended place for your most important agent-specific rules — it appears early in CLAUDE.md for maximum influence on model behavior. Other `instructions/*.md` files are included after engine rules.',
+  '**Modular engine rules:** The `engine.features` array in `agent.yaml` controls which rule modules are included. Available: `vault`, `planning`, `brain`, `advanced`. Core rules are always included. Default (no features specified) = all modules.',
+  '',
+  '### What Survives Regeneration',
   '',
-  'When the engine updates (`@soleri/core` or `@soleri/forge`), running `soleri agent refresh` regenerates CLAUDE.md with the latest shared rules. Your own `instructions/*.md` files are where agent-specific behavior lives — those survive regeneration.',
+  '| Source | Survives? |',
+  '|--------|-----------|',
+  '| `instructions/*.md` | Yes — re-read on every regen |',
+  '| `<!-- user:custom -->` zone in CLAUDE.md | Yes — extracted and re-injected |',
+  '| `agent.yaml` | Drives regen (source of truth) |',
+  '| Manual CLAUDE.md edits outside markers | No — overwritten, warning logged |',
   '',
   '### System Requirements',
   '',